Architecture Deep Dive
API server, scheduler, cron loop, and worker reaper all run in a single process. No separate queue infrastructure. PostgreSQL is the only external dependency.
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
Unlike Temporal (which replays event history on every wake-up), Orch8 saves a state snapshot after each step. Resuming is a single database read — O(1) regardless of how many steps ran before.
| 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 limits | 64KB per event | None (Postgres rows) |
| Testing | Needs running server | Same binary, same code |
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.