Event flows

Workflow creation

1. Accept the command

   The HTTP gateway validates session, CSRF state, input, and the idempotency key before calling the workflows service.
2. Commit state and intent

   PostgreSQL stores workflow state, idempotency output, and an outbox event in one transaction.
3. Publish durably

   The outbox relay claims the row and publishes the workflow event to Kafka.
4. Prepare execution

   The workflow worker validates payload, resolves the image digest, and updates build state through gRPC.

Automatic scheduling

The scheduling worker scans due workflows, validates generation and build state, then creates replay-safe job dispatch work. Manual scheduling enters the same job lifecycle with trigger MANUAL.

Job execution

The execution worker consumes the job event, claims a lease, receives the runtime endpoint registered by runtime-agent, ensures the resolved image on that runtime, starts the container through the Docker proxy, attaches its container ID, renews ownership, and publishes output. Terminal state changes require the lease token.

Logs and analytics

Live output uses Redis pub/sub. Retained output flows through Kafka to ClickHouse and Meilisearch. Workflow, job, and log events feed replay-safe analytics updates in PostgreSQL.

Failure path

If a worker disappears, lease recovery evaluates expired running jobs. Eligible system failures are retried; exhausted or invalid work becomes terminal and container cleanup is attempted.