Architecture Deep Dive#
API server, scheduler, cron loop, and worker reaper all run in a single process. Core durable execution needs PostgreSQL in production or SQLite for local and single-node use. Optional integrations such as NATS, object storage, plugins, and external workers add their own dependencies.
Crate structure
The engine is a Rust workspace with five crates:
orch8-typesShared domain types — IDs, instance states, block types, signals, context, configorch8-engineCore execution logic — scheduler, evaluator, handlers, signals, templates, recovery, metricsorch8-storageDatabase abstraction trait + PostgreSQL implementationorch8-apiREST API layer — health, sequences, instances, metrics endpointsorch8-serverApplication entry point — config loading, server startup, graceful shutdown
Snapshot-based execution
Orch8 persists execution state as work advances and resumes from the stored position rather than replaying user workflow code from the beginning. Recovery still includes normal database queries and scheduler work; it is not a latency guarantee.
| Aspect | Temporal | Orch8 |
|---|---|---|
| Resume mechanism | Replay entire history | Read last snapshot |
| Coding rules | No Date.now(), no Math.random() | Write normal code |
| State visibility | Custom query handlers | REST API — GET /instances/{id} |
| Code changes | Require patched() markers | Apply immediately to new instances |
| Payload handling | History and payload limits apply | Database and configured storage limits apply |
| Testing | SDK test environments | Engine validation and dry-run APIs |
Two execution paths
Timer-driven (scheduling)
For campaign sequences where steps fire on a schedule. Every tick (default 100ms), the engine claims due instances using SELECT ... FOR UPDATE SKIP LOCKED, ordered by priority then fire time. For each instance it checks rate limits and either fires the handler or defers to the next available window.
Event-driven (orchestration)
For workflows with parallel steps, races, loops, and signals. When a step completes or a signal arrives, the engine evaluates the execution tree and immediately runs the next block — no timer delay.
Technology stack
| Language | Rust | Performance, memory safety, no GC pauses |
| Storage | PostgreSQL + SQLite | Production on Postgres, zero-dep local dev on SQLite |
| API | REST + gRPC + SSE | axum-based REST; Tonic gRPC; SSE via /instances/{id}/stream |
| Plugin runtime | Wasmtime (WASM) | Sandboxed handler execution; wasm:// dispatch prefix |
| Message queue | NATS (optional) | async-nats subscriber; config-driven trigger subjects |
| File events | notify crate | Cross-platform fs-event trigger; recursive watch support |
| Metrics | Prometheus | Counters, histograms, gauges at /metrics |
| Logging | Structured JSON | Configurable level, tracing-based |
| Deployment | Single binary + Docker | Minimal ops |
Storage abstraction
The engine uses a StorageBackend trait that abstracts all database operations. The PostgreSQL implementation is the production backend. The trait is designed so additional backends can be added.
Ready to try Orch8?
One command to install. Then run your first local sequence.
curl -fsSL https://orch8.io/start.sh | sh