# Execution flows

Everything on the [jobs](../jobs/) and [tasks](../tasks/) pages describes the **north** side of the
service, the API your back-office application talks to. This page explains what happens on the
**south** side, between OpenGate and the device — because that is what determines how long an
operation takes, what progress you can observe, and why an operation can sit in
`WAITING_FOR_CONNECTION` for hours.

Every operation has at least a minimum workflow to be fulfilled. Beyond that minimum, the flow depends
on what the device is capable of.

## Who starts the conversation

| Flow | Who initiates | When it fits |
|---|---|---|
| **Platform-driven** | OpenGate contacts the device | The device is reachable and exposes an endpoint |
| **Device-driven** | The device asks OpenGate for pending operations | The device sleeps, sits behind NAT, or has no public address |

Device-driven operations are why an operation may report `WAITING_FOR_CONNECTION`: the work is queued
and waiting for the device to show up.

## Platform-driven flows

### Synchronous

The whole operation is resolved in a single HTTP request and response. The device does the work and
answers with the final result:

```mermaid
sequenceDiagram
    participant OG as OpenGate
    participant Dev as Device
    OG->>Dev: Operation request (HTTP POST)
    Note over Dev: executes the operation
    Dev-->>OG: Final response with result and steps (HTTP 201)
```

Simple and cheap, but it holds the connection for the whole execution — unsuitable for anything slow,
such as a firmware download.

### Asynchronous with a simple response

The device acknowledges the request immediately and reports the result later, in a request of its own:

```mermaid
sequenceDiagram
    participant OG as OpenGate
    participant Dev as Device
    OG->>Dev: Operation request (HTTP POST)
    Dev-->>OG: ACK (HTTP response)
    Note over Dev: executes the operation
    Dev->>OG: Response notification with result (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
```

### Asynchronous with multiple responses

The device reports partial progress as it goes, and closes with a final response. This is what makes a
long operation observable:

```mermaid
sequenceDiagram
    participant OG as OpenGate
    participant Dev as Device
    OG->>Dev: Operation request (HTTP POST)
    Dev-->>OG: ACK (HTTP response)
    Dev->>OG: Partial response — STEP in progress (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
    Dev->>OG: Partial response — next STEP (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
    Dev->>OG: Final response — last STEP and result (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
```

Each partial response updates the operation's `steps` array, so a north API client polling the job — or
receiving [callbacks](../callbacks/) — sees the progress accumulate.

## Device-driven flow

The device polls OpenGate for work, executes what it gets, and reports back:

```mermaid
sequenceDiagram
    participant Dev as Device
    participant OG as OpenGate
    Dev->>OG: Ask for pending operations (HTTP GET)
    OG-->>Dev: Pending operation request
    Note over Dev: executes the operation
    Dev->>OG: Response notification with result (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
```

## Single-step versus multi-step operations

The flow strategy above is about *transport*. Independently of it, an operation is either atomic or
composed of steps:

| Structure | What the device reports | Observability |
|---|---|---|
| **Simple request/response** | One result, no intermediate stages | Success or failure, nothing in between |
| **Multi-step** | A declared list of steps, each with its own result and timestamp | Progress while the operation runs |

A multi-step operation can report all its steps in one response, or spread them across partial
responses until the final step is reached. The step list belongs to the
[operation type](../operation_types/) definition: it is declared once, and every execution reports
against it.

## Where to go from here

The diagrams above are summaries. The complete south API — endpoints, ports, request and response
schemas, security requirements and the full flow diagrams — lives in the device integration section:

- [Operations over HTTP](../../device_integration/http/operations/)
- [Operations driven by platform](../../device_integration/http/operations/driven_by_platform/)
- [Operations driven by device](../../device_integration/http/operations/driven_by_device/)
- [Operations over MQTT](../../device_integration/mqtt/operations/)
- [Security tips for operations](../../device_integration/http/operations/security/)

For a real multi-step flow end to end, see the
[update operation example](../examples/update_operation/).