# michael-bill/knotra architecture

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

- Interactive diagram: https://gitdiagram.com/michael-bill/knotra
- Repository: https://github.com/michael-bill/knotra

## Overview

Knotra is a YAML-defined AI-pipeline authoring and execution system. The main workflow is to create or validate a pipeline package, start it through the CLI or desktop, execute its graph through the durable engine and worker adapters, then observe runs, answer human requests, and retrieve artifacts. Desktop also provides workspace editing, run history, diagnostics, and resource views. The README documents the major runtime integrations; source excerpts show only selected wiring, so unverified subsystem links are omitted.

Main entry points: [`internal/app/server.go`](https://github.com/michael-bill/knotra/blob/main/internal/app/server.go) (Service wiring), [`internal/api/server.go`](https://github.com/michael-bill/knotra/blob/main/internal/api/server.go) (HTTP API), [`app/src/App.tsx`](https://github.com/michael-bill/knotra/blob/main/app/src/App.tsx) (Desktop workspace), [`internal/engine/workflow.go`](https://github.com/michael-bill/knotra/blob/main/internal/engine/workflow.go) (Durable workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Pipeline authoring"]
  node_validation_ui["Package validation<br/>[validation.ts]"]
  node_package["Pipeline package<br/>[package.ts]"]
  node_contract["Contract compiler<br/>[compile.go]"]
end

subgraph group_runtime["Execution runtime"]
  node_app_server["Service wiring<br/>[server.go]"]
  node_workflow["Durable workflow<br/>[workflow.go]"]
  node_graph["Graph execution<br/>[graph.go]"]
  node_control["Execution control<br/>[control.go]"]
  node_adapters["Node adapters<br/>[adapters.go]"]
  node_agent["Agent execution<br/>[agent.go]"]
end

subgraph group_interfaces["User interfaces"]
  node_desktop["Desktop workspace<br/>[App.tsx]"]
  node_workspace["Workspace editing<br/>[WorkspaceView.tsx]"]
  node_cli["CLI<br/>[root.go]"]
  node_api["HTTP API<br/>[server.go]"]
  node_observe["Run observation"]
  node_history["Run history"]
  node_inbox["Human request inbox"]
end

subgraph group_state["Persistence and events"]
  node_store[("Run state store<br/>[store.go]")]
  node_artifacts[("Artifact storage<br/>[artifacts.go]")]
end

subgraph group_integrations["External integrations"]
  node_ollama["Ollama models<br/>[ollama.go]"]
  node_mcp["MCP servers<br/>[mcp.go]"]
  node_sandbox["Docker sandbox<br/>[docker.go]"]
  node_temporal["Temporal"]
  node_postgres[("PostgreSQL")]
end

node_user(("Pipeline author"))
node_human(("Human reviewer"))

node_user -->|"edits"| node_workspace
node_workspace -->|"validates"| node_validation_ui
node_validation_ui -->|"checks package"| node_package
node_user -->|"runs commands"| node_cli
node_cli -->|"validates package"| node_contract
node_cli -->|"calls HTTP API"| node_api
node_desktop -->|"uses shared API"| node_api
node_desktop -->|"hosts editor"| node_workspace
node_desktop -->|"shows runs"| node_observe
node_desktop -->|"shows history"| node_history
node_app_server -->|"registers routes"| node_api
node_app_server -->|"registers workflow"| node_workflow
node_app_server -->|"executes nodes"| node_adapters
node_app_server -->|"wires persistence"| node_store
node_app_server -->|"starts workflows"| node_temporal
node_workflow -->|"runs graph"| node_graph
node_workflow -.->|"manages execution"| node_control
node_adapters -.->|"supports agents"| node_agent
node_agent -.->|"uses model"| node_ollama
node_agent -.->|"uses tools"| node_mcp
node_adapters -->|"runs isolated"| node_sandbox
node_api -->|"reads and writes"| node_store
node_store -->|"persists state"| node_postgres
node_app_server -->|"stores artifacts"| node_artifacts
node_app_server -->|"registers workers"| node_temporal
node_api -.->|"serves run data"| node_observe
node_observe -->|"requests events"| node_api
node_history -->|"loads history"| node_api
node_human -.->|"answers requests"| node_inbox

click node_desktop "https://github.com/michael-bill/knotra/blob/main/app/src/App.tsx"
click node_workspace "https://github.com/michael-bill/knotra/blob/main/app/src/components/WorkspaceView.tsx"
click node_validation_ui "https://github.com/michael-bill/knotra/blob/main/app/src/lib/validation.ts"
click node_package "https://github.com/michael-bill/knotra/blob/main/app/src/lib/package.ts"
click node_contract "https://github.com/michael-bill/knotra/blob/main/internal/contract/compile.go"
click node_cli "https://github.com/michael-bill/knotra/blob/main/internal/cli/root.go"
click node_api "https://github.com/michael-bill/knotra/blob/main/internal/api/server.go"
click node_app_server "https://github.com/michael-bill/knotra/blob/main/internal/app/server.go"
click node_workflow "https://github.com/michael-bill/knotra/blob/main/internal/engine/workflow.go"
click node_graph "https://github.com/michael-bill/knotra/blob/main/internal/engine/graph.go"
click node_control "https://github.com/michael-bill/knotra/blob/main/internal/engine/control.go"
click node_adapters "https://github.com/michael-bill/knotra/blob/main/internal/adapters/adapters.go"
click node_agent "https://github.com/michael-bill/knotra/blob/main/internal/adapters/agent.go"
click node_ollama "https://github.com/michael-bill/knotra/blob/main/internal/adapters/ollama.go"
click node_mcp "https://github.com/michael-bill/knotra/blob/main/internal/adapters/mcp.go"
click node_sandbox "https://github.com/michael-bill/knotra/blob/main/internal/adapters/docker.go"
click node_store "https://github.com/michael-bill/knotra/blob/main/internal/store/store.go"
click node_artifacts "https://github.com/michael-bill/knotra/blob/main/internal/store/artifacts.go"
click node_observe "https://github.com/michael-bill/knotra/blob/main/app/src/components/EngineExecutionView.tsx"
click node_history "https://github.com/michael-bill/knotra/blob/main/app/src/components/EngineHistoryView.tsx"
click node_inbox "https://github.com/michael-bill/knotra/blob/main/app/src/components/EngineInboxView.tsx"

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_validation_ui,node_package,node_contract,node_human toneBlue
class node_app_server,node_workflow,node_graph,node_control,node_adapters,node_agent toneAmber
class node_desktop,node_workspace,node_cli,node_api,node_observe,node_history,node_inbox toneMint
class node_store,node_artifacts toneRose
class node_ollama,node_mcp,node_sandbox,node_temporal,node_postgres,node_user toneIndigo
```

## Components

### Pipeline authoring

- [Package validation](https://github.com/michael-bill/knotra/blob/main/app/src/lib/validation.ts): `app/src/lib/validation.ts`
- [Pipeline package](https://github.com/michael-bill/knotra/blob/main/app/src/lib/package.ts): `app/src/lib/package.ts`
- [Contract compiler](https://github.com/michael-bill/knotra/blob/main/internal/contract/compile.go): `internal/contract/compile.go`

### Execution runtime

- [Service wiring](https://github.com/michael-bill/knotra/blob/main/internal/app/server.go): `internal/app/server.go`
- [Durable workflow](https://github.com/michael-bill/knotra/blob/main/internal/engine/workflow.go): `internal/engine/workflow.go`
- [Graph execution](https://github.com/michael-bill/knotra/blob/main/internal/engine/graph.go): `internal/engine/graph.go`
- [Execution control](https://github.com/michael-bill/knotra/blob/main/internal/engine/control.go): `internal/engine/control.go`
- [Node adapters](https://github.com/michael-bill/knotra/blob/main/internal/adapters/adapters.go): `internal/adapters/adapters.go`
- [Agent execution](https://github.com/michael-bill/knotra/blob/main/internal/adapters/agent.go): `internal/adapters/agent.go`

### User interfaces

- [Desktop workspace](https://github.com/michael-bill/knotra/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Workspace editing](https://github.com/michael-bill/knotra/blob/main/app/src/components/WorkspaceView.tsx): `app/src/components/WorkspaceView.tsx`
- [CLI](https://github.com/michael-bill/knotra/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [HTTP API](https://github.com/michael-bill/knotra/blob/main/internal/api/server.go): `internal/api/server.go`
- [Run observation](https://github.com/michael-bill/knotra/blob/main/app/src/components/EngineExecutionView.tsx): `app/src/components/EngineExecutionView.tsx`
- [Run history](https://github.com/michael-bill/knotra/blob/main/app/src/components/EngineHistoryView.tsx): `app/src/components/EngineHistoryView.tsx`
- [Human request inbox](https://github.com/michael-bill/knotra/blob/main/app/src/components/EngineInboxView.tsx): `app/src/components/EngineInboxView.tsx`

### Persistence and events

- [Run state store](https://github.com/michael-bill/knotra/blob/main/internal/store/store.go): `internal/store/store.go`
- [Artifact storage](https://github.com/michael-bill/knotra/blob/main/internal/store/artifacts.go): `internal/store/artifacts.go`

### External integrations

- [Ollama models](https://github.com/michael-bill/knotra/blob/main/internal/adapters/ollama.go): `internal/adapters/ollama.go`
- [MCP servers](https://github.com/michael-bill/knotra/blob/main/internal/adapters/mcp.go): `internal/adapters/mcp.go`
- [Docker sandbox](https://github.com/michael-bill/knotra/blob/main/internal/adapters/docker.go): `internal/adapters/docker.go`
- **Temporal**
- **PostgreSQL**

### Other components

- **Pipeline author**
- **Human reviewer**

## Connections

- Pipeline author → Workspace editing: edits
- Workspace editing → Package validation: validates
- Package validation → Pipeline package: checks package (evidence: `app/src/lib/validation.ts`)
- Pipeline author → CLI: runs commands (evidence: `README.md`)
- CLI → Contract compiler: validates package (evidence: `README.md`)
- CLI → HTTP API: calls HTTP API (evidence: `README.md`)
- Desktop workspace → HTTP API: uses shared API (evidence: `README.md`)
- Desktop workspace → Workspace editing: hosts editor (evidence: `app/src/App.tsx`)
- Desktop workspace → Run observation: shows runs (evidence: `app/src/App.tsx`)
- Desktop workspace → Run history: shows history (evidence: `app/src/App.tsx`)
- Service wiring → HTTP API: registers routes (evidence: `internal/app/server.go`)
- Service wiring → Durable workflow: registers workflow (evidence: `internal/app/server.go`)
- Service wiring → Node adapters: executes nodes (evidence: `internal/app/server.go`)
- Service wiring → Run state store: wires persistence (evidence: `internal/app/server.go`)
- Service wiring → Temporal: starts workflows (evidence: `README.md`)
- Durable workflow → Graph execution: runs graph (evidence: `internal/engine/workflow.go`)
- Durable workflow → Execution control: manages execution
- Node adapters → Agent execution: supports agents
- Agent execution → Ollama models: uses model
- Agent execution → MCP servers: uses tools
- Node adapters → Docker sandbox: runs isolated (evidence: `internal/adapters/docker.go`)
- HTTP API → Run state store: reads and writes (evidence: `internal/api/server.go`)
- Run state store → PostgreSQL: persists state (evidence: `README.md`)
- Service wiring → Artifact storage: stores artifacts (evidence: `internal/app/server.go`)
- Service wiring → Temporal: registers workers (evidence: `internal/app/server.go`)
- HTTP API → Run observation: serves run data
- Run observation → HTTP API: requests events (evidence: `app/src/components/EngineExecutionView.tsx`)
- Run history → HTTP API: loads history (evidence: `app/src/components/EngineHistoryView.tsx`)
- Human reviewer → Human request inbox: answers requests
