How michael-bill/knotra works
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: app/server.go Service wiring · api/server.go HTTP API · App.tsx Desktop workspace · workflow.go Durable workflow
Components 25
Pipeline authoring
- Package validation
app/src/lib/validation.ts - Pipeline package
app/src/lib/package.ts - Contract compiler
internal/contract/compile.go
Execution runtime
- Service wiring
internal/app/server.go - Durable workflow
internal/engine/workflow.go - Graph execution
internal/engine/graph.go - Execution control
internal/engine/control.go - Node adapters
internal/adapters/adapters.go - Agent execution
internal/adapters/agent.go
User interfaces
- Desktop workspace
app/src/App.tsx - Workspace editing
app/src/components/WorkspaceView.tsx - CLI
internal/cli/root.go - HTTP API
internal/api/server.go - Run observation
app/src/components/EngineExecutionView.tsx - Run history
app/src/components/EngineHistoryView.tsx - Human request inbox
app/src/components/EngineInboxView.tsx
Persistence and events
- Run state store
internal/store/store.go - Artifact storage
internal/store/artifacts.go
External integrations
- Ollama models
internal/adapters/ollama.go - MCP servers
internal/adapters/mcp.go - Docker sandbox
internal/adapters/docker.go - Temporal
- PostgreSQL
Other components
- Pipeline author
- Human reviewer
Connections 29
- Pipeline author → Workspace editing: edits
- Workspace editing → Package validation: validates
- Package validation → Pipeline package: checks package
app/src/lib/validation.ts - Pipeline author → CLI: runs commands
README.md - CLI → Contract compiler: validates package
README.md - CLI → HTTP API: calls HTTP API
README.md - Desktop workspace → HTTP API: uses shared API
README.md - Desktop workspace → Workspace editing: hosts editor
app/src/App.tsx - Desktop workspace → Run observation: shows runs
app/src/App.tsx - Desktop workspace → Run history: shows history
app/src/App.tsx - Service wiring → HTTP API: registers routes
internal/app/server.go - Service wiring → Durable workflow: registers workflow
internal/app/server.go - Service wiring → Node adapters: executes nodes
internal/app/server.go - Service wiring → Run state store: wires persistence
internal/app/server.go - Service wiring → Temporal: starts workflows
README.md - Durable workflow → Graph execution: runs graph
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
internal/adapters/docker.go - HTTP API → Run state store: reads and writes
internal/api/server.go - Run state store → PostgreSQL: persists state
README.md - Service wiring → Artifact storage: stores artifacts
internal/app/server.go - Service wiring → Temporal: registers workers
internal/app/server.go - HTTP API → Run observation: serves run data
- Run observation → HTTP API: requests events
app/src/components/EngineExecutionView.tsx - Run history → HTTP API: loads history
app/src/components/EngineHistoryView.tsx - Human reviewer → Human request inbox: answers requests