# henomis/packtrail architecture

> Architecture diagram of the GitHub repository henomis/packtrail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henomis/packtrail
- Repository: https://github.com/henomis/packtrail

## Overview

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: [`internal/engine/engine.go`](https://github.com/henomis/packtrail/blob/main/internal/engine/engine.go) (Command engine), [`internal/loader/loader.go`](https://github.com/henomis/packtrail/blob/main/internal/loader/loader.go) (Execution loader), [`internal/dispatch/dispatch.go`](https://github.com/henomis/packtrail/blob/main/internal/dispatch/dispatch.go) (Effect dispatcher), [`client.go`](https://github.com/henomis/packtrail/blob/main/client.go) (Execution client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["Flow definition"]
  node_flow_model["Flow model<br/>[flow.go]"]
  node_flow_validation["Flow validation<br/>[validate.go]"]
end

subgraph group_runtime["Execution runtime"]
  node_engine["Command engine<br/>[engine.go]"]
  node_decision["Workflow decider<br/>[decide.go]"]
  node_state_fold["State folding<br/>[state.go]"]
  node_dispatch["Effect dispatcher<br/>[dispatch.go]"]
  node_schedules["Cron scheduling<br/>[cron.go]"]
end

subgraph group_durability["JetStream durability"]
  node_loader["Execution loader<br/>[loader.go]"]
  node_eventlog[("Event history<br/>[eventlog.go]")]
  node_snapshots[("State snapshots<br/>[snapshot.go]")]
  node_registry[("Flow registry<br/>[registry.go]")]
  node_projection[("Execution index<br/>[projection.go]")]
  node_jetstream[("NATS JetStream")]
end

subgraph group_interfaces["Clients and workers"]
  node_cli["CLI commands<br/>[main.go]"]
  node_client["Execution client<br/>[client.go]"]
  node_client_more["Watch and schedules<br/>[client_more.go]"]
  node_worker["Worker runtime<br/>[worker.go]"]
  node_job_api["Job handler API<br/>[job.go]"]
end

subgraph group_operations["Operations and visibility"]
  node_quarantine["Quarantine recovery<br/>[quarantine.go]"]
  node_dashboard["Debug dashboard<br/>[main.go]"]
  node_dashboard_api["Dashboard API<br/>[api.go]"]
end

node_user(("Workflow operator"))

node_user -->|"issues commands"| node_cli
node_user -->|"declares flow"| node_flow_model
node_flow_model -->|"validates graph"| node_flow_validation
node_cli -->|"validates offline"| node_flow_validation
node_cli -->|"invokes operations"| node_client
node_client -->|"publishes commands"| node_engine
node_engine -->|"loads execution"| node_loader
node_engine -.->|"requests decision"| node_decision
node_engine -.->|"appends events"| node_eventlog
node_engine -.->|"dispatches events"| node_dispatch
node_engine -->|"updates index"| node_projection
node_loader -->|"reads history"| node_eventlog
node_loader -->|"loads snapshots"| node_snapshots
node_loader -->|"loads flow"| node_registry
node_eventlog -->|"stores events"| node_jetstream
node_snapshots -->|"stores snapshots"| node_jetstream
node_registry -->|"stores flow versions"| node_jetstream
node_projection -->|"stores index"| node_jetstream
node_dispatch -->|"publishes jobs"| node_jetstream
node_dispatch -->|"dispatches task jobs"| node_worker
node_worker -->|"builds handler job"| node_job_api
node_worker -->|"publishes outcomes"| node_jetstream
node_client -->|"reads execution state"| node_loader
node_client_more -->|"schedules and watches"| node_jetstream
node_engine -.->|"processes cron"| node_schedules
node_dispatch -.->|"routes poison events"| node_quarantine
node_user -->|"inspects executions"| node_dashboard
node_dashboard -.->|"serves API"| node_dashboard_api
node_dashboard_api -.->|"reads and controls"| node_client

click node_flow_model "https://github.com/henomis/packtrail/blob/main/flow/flow.go"
click node_flow_validation "https://github.com/henomis/packtrail/blob/main/flow/validate.go"
click node_cli "https://github.com/henomis/packtrail/blob/main/cmd/packtrail/main.go"
click node_client "https://github.com/henomis/packtrail/blob/main/client.go"
click node_client_more "https://github.com/henomis/packtrail/blob/main/client_more.go"
click node_engine "https://github.com/henomis/packtrail/blob/main/internal/engine/engine.go"
click node_decision "https://github.com/henomis/packtrail/blob/main/internal/fold/decide.go"
click node_state_fold "https://github.com/henomis/packtrail/blob/main/internal/fold/state.go"
click node_dispatch "https://github.com/henomis/packtrail/blob/main/internal/dispatch/dispatch.go"
click node_quarantine "https://github.com/henomis/packtrail/blob/main/internal/dispatch/quarantine.go"
click node_loader "https://github.com/henomis/packtrail/blob/main/internal/loader/loader.go"
click node_eventlog "https://github.com/henomis/packtrail/blob/main/internal/eventlog/eventlog.go"
click node_snapshots "https://github.com/henomis/packtrail/blob/main/internal/snapshot/snapshot.go"
click node_registry "https://github.com/henomis/packtrail/blob/main/internal/registry/registry.go"
click node_projection "https://github.com/henomis/packtrail/blob/main/internal/projection/projection.go"
click node_worker "https://github.com/henomis/packtrail/blob/main/worker/worker.go"
click node_job_api "https://github.com/henomis/packtrail/blob/main/worker/job.go"
click node_schedules "https://github.com/henomis/packtrail/blob/main/internal/engine/cron.go"
click node_dashboard "https://github.com/henomis/packtrail/blob/main/cmd/packtrail-ui/main.go"
click node_dashboard_api "https://github.com/henomis/packtrail/blob/main/cmd/packtrail-ui/api.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flow_model,node_flow_validation toneBlue
class node_engine,node_decision,node_state_fold,node_dispatch,node_schedules toneAmber
class node_loader,node_eventlog,node_snapshots,node_registry,node_projection,node_jetstream toneMint
class node_cli,node_client,node_client_more,node_worker,node_job_api toneRose
class node_quarantine,node_dashboard,node_dashboard_api,node_user toneIndigo
```

## Components

### Flow definition

- [Flow model](https://github.com/henomis/packtrail/blob/main/flow/flow.go): `flow/flow.go`
- [Flow validation](https://github.com/henomis/packtrail/blob/main/flow/validate.go): `flow/validate.go`

### Execution runtime

- [Command engine](https://github.com/henomis/packtrail/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [Workflow decider](https://github.com/henomis/packtrail/blob/main/internal/fold/decide.go): `internal/fold/decide.go`
- [State folding](https://github.com/henomis/packtrail/blob/main/internal/fold/state.go): `internal/fold/state.go`
- [Effect dispatcher](https://github.com/henomis/packtrail/blob/main/internal/dispatch/dispatch.go): `internal/dispatch/dispatch.go`
- [Cron scheduling](https://github.com/henomis/packtrail/blob/main/internal/engine/cron.go): `internal/engine/cron.go`

### JetStream durability

- [Execution loader](https://github.com/henomis/packtrail/blob/main/internal/loader/loader.go): `internal/loader/loader.go`
- [Event history](https://github.com/henomis/packtrail/blob/main/internal/eventlog/eventlog.go): `internal/eventlog/eventlog.go`
- [State snapshots](https://github.com/henomis/packtrail/blob/main/internal/snapshot/snapshot.go): `internal/snapshot/snapshot.go`
- [Flow registry](https://github.com/henomis/packtrail/blob/main/internal/registry/registry.go): `internal/registry/registry.go`
- [Execution index](https://github.com/henomis/packtrail/blob/main/internal/projection/projection.go): `internal/projection/projection.go`
- **NATS JetStream**

### Clients and workers

- [CLI commands](https://github.com/henomis/packtrail/blob/main/cmd/packtrail/main.go): `cmd/packtrail/main.go`
- [Execution client](https://github.com/henomis/packtrail/blob/main/client.go): `client.go`
- [Watch and schedules](https://github.com/henomis/packtrail/blob/main/client_more.go): `client_more.go`
- [Worker runtime](https://github.com/henomis/packtrail/blob/main/worker/worker.go): `worker/worker.go`
- [Job handler API](https://github.com/henomis/packtrail/blob/main/worker/job.go): `worker/job.go`

### Operations and visibility

- [Quarantine recovery](https://github.com/henomis/packtrail/blob/main/internal/dispatch/quarantine.go): `internal/dispatch/quarantine.go`
- [Debug dashboard](https://github.com/henomis/packtrail/blob/main/cmd/packtrail-ui/main.go): `cmd/packtrail-ui/main.go`
- [Dashboard API](https://github.com/henomis/packtrail/blob/main/cmd/packtrail-ui/api.go): `cmd/packtrail-ui/api.go`

### Other components

- **Workflow operator**

## Connections

- Workflow operator → CLI commands: issues commands (evidence: `cmd/packtrail/main.go`)
- Workflow operator → Flow model: declares flow
- Flow model → Flow validation: validates graph (evidence: `flow/validate.go`)
- CLI commands → Flow validation: validates offline
- CLI commands → Execution client: invokes operations (evidence: `cmd/packtrail/main.go`)
- Execution client → Command engine: publishes commands (evidence: `client.go`)
- Command engine → Execution loader: loads execution (evidence: `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 (evidence: `internal/engine/engine.go`)
- Execution loader → Event history: reads history (evidence: `internal/loader/loader.go`)
- Execution loader → State snapshots: loads snapshots (evidence: `internal/loader/loader.go`)
- Execution loader → Flow registry: loads flow (evidence: `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 (evidence: `internal/projection/projection.go`)
- Effect dispatcher → NATS JetStream: publishes jobs (evidence: `internal/dispatch/dispatch.go`)
- Effect dispatcher → Worker runtime: dispatches task jobs
- Worker runtime → Job handler API: builds handler job (evidence: `worker/worker.go`)
- Worker runtime → NATS JetStream: publishes outcomes (evidence: `worker/worker.go`)
- Execution client → Execution loader: reads execution state (evidence: `client.go`)
- Watch and schedules → NATS JetStream: schedules and watches (evidence: `client_more.go`)
- Command engine → Cron scheduling: processes cron
- Effect dispatcher → Quarantine recovery: routes poison events
- Workflow operator → Debug dashboard: inspects executions (evidence: `cmd/packtrail-ui/main.go`)
- Debug dashboard → Dashboard API: serves API
- Dashboard API → Execution client: reads and controls
