Architecture
The diagram below shows one Zoumadi deployment: what Engine and Cockpit provide, what runs on NATS JetStream, and which pieces belong to your own infrastructure rather than to Zoumadi. A full text description follows immediately after it, so the same relationships are available whether or not the image renders.
Text alternative
- Engine’s partitions live inside a NATS JetStream cluster: each partition is a replicated command log with key-value projections derived from it, so there is no relational database in this path. Each partition has a single writer at a time.
- External workers — your own processes — exchange job messages with the same NATS cluster to carry out service tasks; the engine process itself never executes your task code.
- Cockpit is a separate, read-only server that reads bounded projections from the NATS cluster to display process state; it does not write to it.
- A visitor’s browser reaches Cockpit over HTTPS, and Cockpit authenticates that visitor through a deployment-owned OIDC identity provider. A browser never receives a NATS credential directly.
- Any caller outside the deployment’s own private application/NATS network — including other automation reaching the cluster directly, such as an embedded Java API client running elsewhere — crosses a deployment-owned APISIX ingress gateway first. There is no other path into the cluster from outside.
What Zoumadi provides, and what your deployment must supply
Engine and Cockpit are the two pieces Zoumadi ships. Everything labelled “deployment-owned” above — the NATS JetStream cluster itself, the APISIX ingress gateway, and the OIDC identity provider — is infrastructure your own deployment operates and configures; Zoumadi does not install or manage it for you. NATS-level authentication is built for subject-level permissions, but each deployment still has to author and issue its own credential grants. Engine’s backup and restore mechanism, and its metrics and tracing output, are likewise built as mechanisms that your deployment wires up and operates in practice.
This page intentionally contains no throughput, latency or availability figure; none is implied by the diagram either — capacity is a property of your deployment, measured there.
The execution core keeps process state in a replicated command log, with key-value projections derived from it, and needs no relational database of its own.
Service tasks are carried out by external worker processes that connect over NATS; the engine itself does not run your task code.
Commands and jobs travel over a NATS-native protocol rather than REST or gRPC; a deployment still needs its own external ingress for traffic from outside the cluster. — callers must follow the documented at-least-once and idempotence rules.
Zoumadi is designed for traffic from outside a deployment's own network to reach it through an APISIX gateway that the deployment provides and operates.
Zoumadi supports NATS subject-level authentication and permissions; your deployment authors and issues its own credential grants. — your deployment writes its own NATS credentials and grants.
Cockpit is designed for people to sign in through your own OIDC identity provider, so Zoumadi keeps no identity directory of its own.
Each partition has exactly one writer at a time and fails over locally to a standby without a cross-region failover proof. — within a single cluster; multi-region is not covered.
Zoumadi has a built backup and total-loss restore mechanism; a deployment must still supply and prove its own storage authority and restore evidence. — your deployment decides who may invoke it.
Zoumadi emits metrics, structured logs and traces through a built telemetry mechanism; a deployment still owns wiring alerting and dashboards to it. — no external endpoint is published yet.