How henomis/packtrail works
packtrail is a durable, event-sourced workflow engine on NATS JetStream. Users declare and validate a flow, register it, start executions through a client or CLI, and observe or control execution state; workers handle dispatched tasks. Internally, the engine loads state, decides events, appends them, and dispatches effects. The README documents additional graph features and operational capabilities not fully represented in the excerpts. Arrows are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements; unsampled UI and scheduling internals are represented conservatively.
Main entry points: engine.go Command engine · loader.go Execution loader · dispatch.go Effect dispatcher · client.go Execution client
Components 22
Flow definition
- Flow model
flow/flow.go - Flow validation
flow/validate.go
Execution runtime
- Command engine
internal/engine/engine.go - Workflow decider
internal/fold/decide.go - State folding
internal/fold/state.go - Effect dispatcher
internal/dispatch/dispatch.go - Cron scheduling
internal/engine/cron.go
JetStream durability
- Execution loader
internal/loader/loader.go - Event history
internal/eventlog/eventlog.go - State snapshots
internal/snapshot/snapshot.go - Flow registry
internal/registry/registry.go - Execution index
internal/projection/projection.go - NATS JetStream
Clients and workers
- CLI commands
cmd/packtrail/main.go - Execution client
client.go - Watch and schedules
client_more.go - Worker runtime
worker/worker.go - Job handler API
worker/job.go
Operations and visibility
- Quarantine recovery
internal/dispatch/quarantine.go - Debug dashboard
cmd/packtrail-ui/main.go - Dashboard API
cmd/packtrail-ui/api.go
Other components
- Workflow operator
Connections 29
- Workflow operator → CLI commands: issues commands
cmd/packtrail/main.go - Workflow operator → Flow model: declares flow
- Flow model → Flow validation: validates graph
flow/validate.go - CLI commands → Flow validation: validates offline
- CLI commands → Execution client: invokes operations
cmd/packtrail/main.go - Execution client → Command engine: publishes commands
client.go - Command engine → Execution loader: loads execution
internal/engine/engine.go - Command engine → Workflow decider: requests decision
- Command engine → Event history: appends events
- Command engine → Effect dispatcher: dispatches events
- Command engine → Execution index: updates index
internal/engine/engine.go - Execution loader → Event history: reads history
internal/loader/loader.go - Execution loader → State snapshots: loads snapshots
internal/loader/loader.go - Execution loader → Flow registry: loads flow
internal/loader/loader.go - Event history → NATS JetStream: stores events
- State snapshots → NATS JetStream: stores snapshots
- Flow registry → NATS JetStream: stores flow versions
- Execution index → NATS JetStream: stores index
internal/projection/projection.go - Effect dispatcher → NATS JetStream: publishes jobs
internal/dispatch/dispatch.go - Effect dispatcher → Worker runtime: dispatches task jobs
- Worker runtime → Job handler API: builds handler job
worker/worker.go - Worker runtime → NATS JetStream: publishes outcomes
worker/worker.go - Execution client → Execution loader: reads execution state
client.go - Watch and schedules → NATS JetStream: schedules and watches
client_more.go - Command engine → Cron scheduling: processes cron
- Effect dispatcher → Quarantine recovery: routes poison events
- Workflow operator → Debug dashboard: inspects executions
cmd/packtrail-ui/main.go - Debug dashboard → Dashboard API: serves API
- Dashboard API → Execution client: reads and controls