# henomis/stiggy architecture

> Architecture diagram of the GitHub repository henomis/stiggy, 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/stiggy
- Repository: https://github.com/henomis/stiggy

## Overview

Stiggy turns YAML or Go configuration into durable multi-agent workflows on packtrail/NATS, then runs agent jobs with phero. The principal path is fleet definition → validated spec → compiled flows and workers → execution results observed through a client. Crews and named patterns expand into flows; exposed and remote agents, human review, memory/knowledge, tracing, and replay are additional capabilities. A separate browser designer edits project documents and compiles them to fleet YAML without connecting to NATS. Relationships for unsampled subsystems are included only where the README documents them.

Main entry points: [`agentrun/agentrun.go`](https://github.com/henomis/stiggy/blob/main/agentrun/agentrun.go) (Agent job runner), [`assembly.go`](https://github.com/henomis/stiggy/blob/main/assembly.go) (Runtime assembly), [`ui/src/App.tsx`](https://github.com/henomis/stiggy/blob/main/ui/src/App.tsx) (Browser designer), [`internal/design/design.go`](https://github.com/henomis/stiggy/blob/main/internal/design/design.go) (Designer API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["Fleet definition"]
  node_yaml["YAML loader<br/>[config.go]"]
  node_goapi["Go configuration<br/>[options.go]"]
  node_fleet["Fleet spec<br/>[spec.go]"]
  node_compiler["Flow compiler<br/>[flows.go]"]
  node_patterns["Crews and patterns<br/>[teams.go]"]
end

subgraph group_execution["Workflow execution"]
  node_assembler["Runtime assembly<br/>[assembly.go]"]
  node_engine["Packtrail engine"]
  node_nats[("NATS JetStream")]
  node_client["Execution client<br/>[stiggy.go]"]
end

subgraph group_agents["Agent capabilities"]
  node_worker["Agent job runner<br/>[agentrun.go]"]
  node_observe["Job observation<br/>[observe.go]"]
  node_memory[("Memory and storage<br/>[builtin_storage.go]")]
  node_exposure["Agent exposure<br/>[expose.go]"]
  node_human["Human review<br/>[hitl.go]"]
  node_remote["Remote agents<br/>[remote.go]"]
end

subgraph group_designer["Workflow designer"]
  node_designer["Browser designer<br/>[App.tsx]"]
  node_canvas["Workflow canvas<br/>[Canvas.tsx]"]
  node_blocks["Block catalogue<br/>[blocks.ts]"]
  node_project["Project document<br/>[project.ts]"]
  node_designerapi["Designer API<br/>[design.go]"]
  node_projectcompile["Project compiler<br/>[compile.go]"]
end

subgraph group_operations["Serving and observability"]
  node_cli["stiggy CLI<br/>[online.go]"]
  node_tracing["Execution tracing<br/>[tracing.go]"]
  node_registry["Component registry<br/>[registry.go]"]
end

node_author(("Fleet author"))

node_author -->|"defines fleet"| node_yaml
node_author -->|"configures Go"| node_goapi
node_yaml -->|"decodes"| node_fleet
node_goapi -.->|"builds"| node_fleet
node_fleet -->|"validates and compiles"| node_compiler
node_patterns -->|"expands to flows"| node_compiler
node_compiler -->|"provides flows"| node_assembler
node_assembler -->|"builds components"| node_registry
node_assembler -->|"configures runtime"| node_engine
node_engine -->|"persists executions"| node_nats
node_assembler -->|"registers workers"| node_worker
node_worker -->|"records outcomes"| node_observe
node_worker -.->|"uses agent memory"| node_memory
node_worker -.->|"requests review"| node_human
node_worker -.->|"invokes remote steps"| node_remote
node_assembler -.->|"serves agents"| node_exposure
node_client -->|"starts and watches"| node_engine
node_cli -.->|"runs fleet"| node_assembler
node_cli -.->|"serves designer"| node_designerapi
node_designer -->|"renders canvas"| node_canvas
node_designer -->|"offers blocks"| node_blocks
node_designer -->|"edits project"| node_project
node_designer -->|"calls API"| node_designerapi
node_designerapi -->|"compiles project"| node_projectcompile
node_projectcompile -->|"emits fleet YAML"| node_fleet
node_designerapi -->|"reads catalog"| node_registry
node_worker -.->|"creates spans"| node_tracing

click node_yaml "https://github.com/henomis/stiggy/blob/main/config/config.go"
click node_goapi "https://github.com/henomis/stiggy/blob/main/options.go"
click node_fleet "https://github.com/henomis/stiggy/blob/main/spec/spec.go"
click node_compiler "https://github.com/henomis/stiggy/blob/main/compile/flows.go"
click node_patterns "https://github.com/henomis/stiggy/blob/main/patterns/teams.go"
click node_assembler "https://github.com/henomis/stiggy/blob/main/assembly.go"
click node_client "https://github.com/henomis/stiggy/blob/main/stiggy.go"
click node_worker "https://github.com/henomis/stiggy/blob/main/agentrun/agentrun.go"
click node_observe "https://github.com/henomis/stiggy/blob/main/agentrun/observe.go"
click node_memory "https://github.com/henomis/stiggy/blob/main/registry/builtin_storage.go"
click node_exposure "https://github.com/henomis/stiggy/blob/main/agentrun/expose.go"
click node_human "https://github.com/henomis/stiggy/blob/main/agentrun/hitl.go"
click node_remote "https://github.com/henomis/stiggy/blob/main/agentrun/remote.go"
click node_designer "https://github.com/henomis/stiggy/blob/main/ui/src/App.tsx"
click node_canvas "https://github.com/henomis/stiggy/blob/main/ui/src/Canvas.tsx"
click node_blocks "https://github.com/henomis/stiggy/blob/main/ui/src/blocks.ts"
click node_project "https://github.com/henomis/stiggy/blob/main/ui/src/project.ts"
click node_designerapi "https://github.com/henomis/stiggy/blob/main/internal/design/design.go"
click node_projectcompile "https://github.com/henomis/stiggy/blob/main/internal/design/project/compile.go"
click node_cli "https://github.com/henomis/stiggy/blob/main/cmd/stiggy/online.go"
click node_tracing "https://github.com/henomis/stiggy/blob/main/internal/tracing/tracing.go"
click node_registry "https://github.com/henomis/stiggy/blob/main/registry/registry.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_yaml,node_goapi,node_fleet,node_compiler,node_patterns toneBlue
class node_assembler,node_engine,node_nats,node_client toneAmber
class node_worker,node_observe,node_memory,node_exposure,node_human,node_remote toneMint
class node_designer,node_canvas,node_blocks,node_project,node_designerapi,node_projectcompile toneRose
class node_cli,node_tracing,node_registry,node_author toneIndigo
```

## Components

### Fleet definition

- [YAML loader](https://github.com/henomis/stiggy/blob/main/config/config.go): `config/config.go`
- [Go configuration](https://github.com/henomis/stiggy/blob/main/options.go): `options.go`
- [Fleet spec](https://github.com/henomis/stiggy/blob/main/spec/spec.go): `spec/spec.go`
- [Flow compiler](https://github.com/henomis/stiggy/blob/main/compile/flows.go): `compile/flows.go`
- [Crews and patterns](https://github.com/henomis/stiggy/blob/main/patterns/teams.go): `patterns/teams.go`

### Workflow execution

- [Runtime assembly](https://github.com/henomis/stiggy/blob/main/assembly.go): `assembly.go`
- **Packtrail engine**
- **NATS JetStream**
- [Execution client](https://github.com/henomis/stiggy/blob/main/stiggy.go): `stiggy.go`

### Agent capabilities

- [Agent job runner](https://github.com/henomis/stiggy/blob/main/agentrun/agentrun.go): `agentrun/agentrun.go`
- [Job observation](https://github.com/henomis/stiggy/blob/main/agentrun/observe.go): `agentrun/observe.go`
- [Memory and storage](https://github.com/henomis/stiggy/blob/main/registry/builtin_storage.go): `registry/builtin_storage.go`
- [Agent exposure](https://github.com/henomis/stiggy/blob/main/agentrun/expose.go): `agentrun/expose.go`
- [Human review](https://github.com/henomis/stiggy/blob/main/agentrun/hitl.go): `agentrun/hitl.go`
- [Remote agents](https://github.com/henomis/stiggy/blob/main/agentrun/remote.go): `agentrun/remote.go`

### Workflow designer

- [Browser designer](https://github.com/henomis/stiggy/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Workflow canvas](https://github.com/henomis/stiggy/blob/main/ui/src/Canvas.tsx): `ui/src/Canvas.tsx`
- [Block catalogue](https://github.com/henomis/stiggy/blob/main/ui/src/blocks.ts): `ui/src/blocks.ts`
- [Project document](https://github.com/henomis/stiggy/blob/main/ui/src/project.ts): `ui/src/project.ts`
- [Designer API](https://github.com/henomis/stiggy/blob/main/internal/design/design.go): `internal/design/design.go`
- [Project compiler](https://github.com/henomis/stiggy/blob/main/internal/design/project/compile.go): `internal/design/project/compile.go`

### Serving and observability

- [stiggy CLI](https://github.com/henomis/stiggy/blob/main/cmd/stiggy/online.go): `cmd/stiggy/online.go`
- [Execution tracing](https://github.com/henomis/stiggy/blob/main/internal/tracing/tracing.go): `internal/tracing/tracing.go`
- [Component registry](https://github.com/henomis/stiggy/blob/main/registry/registry.go): `registry/registry.go`

### Other components

- **Fleet author**

## Connections

- Fleet author → YAML loader: defines fleet
- Fleet author → Go configuration: configures Go
- YAML loader → Fleet spec: decodes
- Go configuration → Fleet spec: builds
- Fleet spec → Flow compiler: validates and compiles
- Crews and patterns → Flow compiler: expands to flows
- Flow compiler → Runtime assembly: provides flows
- Runtime assembly → Component registry: builds components (evidence: `assembly.go`)
- Runtime assembly → Packtrail engine: configures runtime
- Packtrail engine → NATS JetStream: persists executions
- Runtime assembly → Agent job runner: registers workers (evidence: `assembly.go`)
- Agent job runner → Job observation: records outcomes (evidence: `agentrun/agentrun.go`)
- Agent job runner → Memory and storage: uses agent memory
- Agent job runner → Human review: requests review
- Agent job runner → Remote agents: invokes remote steps
- Runtime assembly → Agent exposure: serves agents
- Execution client → Packtrail engine: starts and watches
- stiggy CLI → Runtime assembly: runs fleet
- stiggy CLI → Designer API: serves designer
- Browser designer → Workflow canvas: renders canvas (evidence: `ui/src/App.tsx`)
- Browser designer → Block catalogue: offers blocks (evidence: `ui/src/App.tsx`)
- Browser designer → Project document: edits project (evidence: `ui/src/App.tsx`)
- Browser designer → Designer API: calls API (evidence: `ui/src/App.tsx`)
- Designer API → Project compiler: compiles project (evidence: `internal/design/design.go`)
- Project compiler → Fleet spec: emits fleet YAML
- Designer API → Component registry: reads catalog (evidence: `internal/design/design.go`)
- Agent job runner → Execution tracing: creates spans
