# racecraft-lab/paddock architecture

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

- Interactive diagram: https://gitdiagram.com/racecraft-lab/paddock
- Repository: https://github.com/racecraft-lab/paddock

## Overview

Paddock is a self-hosted AI software-factory control plane. Its core flow brings GitHub issues into workspace-scoped tasks, runs work through workflows and agent harnesses, then records artifacts and governance/review evidence for human oversight. Operators interact through the dashboard and REST, CLI, or MCP interfaces; the dashboard also exposes monitoring, integrations, and administration. The README documents the broader workflow and capabilities; sampled source confirms selected GitHub, agent, and UI interactions, so uncertain subsystem wiring is not shown.

Main entry points: [`src/lib/db.ts`](https://github.com/racecraft-lab/paddock/blob/main/src/lib/db.ts) (SQLite state), [`src/app/api/github/route.ts`](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/github/route.ts) (GitHub routes), [`src/app/api/index/route.ts`](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/index/route.ts) (REST API), [`src/lib/github-sync-engine.ts`](https://github.com/racecraft-lab/paddock/blob/main/src/lib/github-sync-engine.ts) (Issue sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Work Intake"]
  node_github_route["GitHub routes<br/>[route.ts]"]
  node_sync["Issue sync"]
  node_github_client["GitHub client<br/>[github.ts]"]
  node_projects["Workspace projects<br/>[route.ts]"]
end

subgraph group_execution["Work Execution"]
  node_tasks["Task management<br/>[route.ts]"]
  node_workflows["Workflow contracts<br/>[route.ts]"]
  node_pipelines["Task pipelines<br/>[route.ts]"]
  node_agents["Agent management<br/>[route.ts]"]
  node_adapters["Harness adapters<br/>[index.ts]"]
  node_runs["Harness runs<br/>[route.ts]"]
end

subgraph group_governance["Governance and Review"]
  node_artifacts["Task artifacts<br/>[route.ts]"]
  node_review["Quality review<br/>[route.ts]"]
  node_governance_api["Resource governance<br/>[route.ts]"]
end

subgraph group_control["Operator Control"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_rest["REST API<br/>[route.ts]"]
  node_cli["CLI<br/>[mc-cli.cjs]"]
  node_mcp["MCP server<br/>[mc-mcp-server.cjs]"]
end

subgraph group_runtime["Runtime Services"]
  node_observability["Harness observability<br/>[otlp-receiver.ts]"]
  node_database[("SQLite state<br/>[db.ts]")]
  node_status["System status<br/>[route.ts]"]
end

node_operator(("Operator / Agent"))
node_github(("GitHub"))

node_operator -->|"uses"| node_dashboard
node_operator -->|"controls"| node_rest
node_operator -->|"controls"| node_cli
node_operator -->|"controls"| node_mcp
node_github -->|"issues and PRs"| node_github_route
node_github_route -->|"fetches issues"| node_github_client
node_github_route -->|"initializes labels"| node_sync
node_sync -->|"fetches issues"| node_github_client
node_sync -->|"projects work items"| node_database
node_github_route -->|"records sync state"| node_database
node_dashboard -->|"requests data"| node_rest
node_rest -->|"routes task requests"| node_tasks
node_rest -->|"routes agent requests"| node_agents
node_tasks -->|"reads and writes"| node_database
node_projects -->|"reads and writes"| node_database
node_workflows -->|"manages templates"| node_database
node_pipelines -->|"records runs"| node_database
node_agents -->|"reads and writes"| node_database
node_agents -.->|"supports harnesses"| node_adapters
node_runs -->|"records runs"| node_database
node_runs -.->|"uses harnesses"| node_adapters
node_artifacts -->|"stores handoffs"| node_database
node_review -->|"records review"| node_database
node_governance_api -->|"reads and writes"| node_database
node_observability -->|"ingests telemetry"| node_database
node_status -->|"reads status"| node_database
node_dashboard -->|"requests status"| node_status

click node_dashboard "https://github.com/racecraft-lab/paddock/blob/main/src/app/%5B%5B...panel%5D%5D/page.tsx"
click node_rest "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/index/route.ts"
click node_cli "https://github.com/racecraft-lab/paddock/blob/main/scripts/mc-cli.cjs"
click node_mcp "https://github.com/racecraft-lab/paddock/blob/main/scripts/mc-mcp-server.cjs"
click node_github_route "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/github/route.ts"
click node_sync "https://github.com/racecraft-lab/paddock/blob/main/src/lib/github-sync-engine.ts"
click node_github_client "https://github.com/racecraft-lab/paddock/blob/main/src/lib/github.ts"
click node_projects "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/projects/route.ts"
click node_tasks "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/tasks/route.ts"
click node_workflows "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/workflows/route.ts"
click node_pipelines "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/pipelines/run/route.ts"
click node_agents "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/agents/route.ts"
click node_adapters "https://github.com/racecraft-lab/paddock/blob/main/src/lib/adapters/index.ts"
click node_runs "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/v1/runs/route.ts"
click node_artifacts "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/task-artifacts/route.ts"
click node_review "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/quality-review/route.ts"
click node_governance_api "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/governance/dispatch/route.ts"
click node_observability "https://github.com/racecraft-lab/paddock/blob/main/src/lib/observability/otlp-receiver.ts"
click node_database "https://github.com/racecraft-lab/paddock/blob/main/src/lib/db.ts"
click node_status "https://github.com/racecraft-lab/paddock/blob/main/src/app/api/status/route.ts"

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_github_route,node_sync,node_github_client,node_projects toneBlue
class node_tasks,node_workflows,node_pipelines,node_agents,node_adapters,node_runs toneAmber
class node_artifacts,node_review,node_governance_api toneMint
class node_dashboard,node_rest,node_cli,node_mcp toneRose
class node_observability,node_database,node_status,node_operator,node_github toneIndigo
```

## Components

### Work Intake

- [GitHub routes](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/github/route.ts): `src/app/api/github/route.ts`
- [Issue sync](https://github.com/racecraft-lab/paddock/blob/main/src/lib/github-sync-engine.ts): `src/lib/github-sync-engine.ts`
- [GitHub client](https://github.com/racecraft-lab/paddock/blob/main/src/lib/github.ts): `src/lib/github.ts`
- [Workspace projects](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/projects/route.ts): `src/app/api/projects/route.ts`

### Work Execution

- [Task management](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/tasks/route.ts): `src/app/api/tasks/route.ts`
- [Workflow contracts](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/workflows/route.ts): `src/app/api/workflows/route.ts`
- [Task pipelines](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/pipelines/run/route.ts): `src/app/api/pipelines/run/route.ts`
- [Agent management](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/agents/route.ts): `src/app/api/agents/route.ts`
- [Harness adapters](https://github.com/racecraft-lab/paddock/blob/main/src/lib/adapters/index.ts): `src/lib/adapters/index.ts`
- [Harness runs](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/v1/runs/route.ts): `src/app/api/v1/runs/route.ts`

### Governance and Review

- [Task artifacts](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/task-artifacts/route.ts): `src/app/api/task-artifacts/route.ts`
- [Quality review](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/quality-review/route.ts): `src/app/api/quality-review/route.ts`
- [Resource governance](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/governance/dispatch/route.ts): `src/app/api/governance/dispatch/route.ts`

### Operator Control

- [Dashboard](https://github.com/racecraft-lab/paddock/blob/main/src/app/%5B%5B...panel%5D%5D/page.tsx): `src/app/[[...panel]]/page.tsx`
- [REST API](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/index/route.ts): `src/app/api/index/route.ts`
- [CLI](https://github.com/racecraft-lab/paddock/blob/main/scripts/mc-cli.cjs): `scripts/mc-cli.cjs`
- [MCP server](https://github.com/racecraft-lab/paddock/blob/main/scripts/mc-mcp-server.cjs): `scripts/mc-mcp-server.cjs`

### Runtime Services

- [Harness observability](https://github.com/racecraft-lab/paddock/blob/main/src/lib/observability/otlp-receiver.ts): `src/lib/observability/otlp-receiver.ts`
- [SQLite state](https://github.com/racecraft-lab/paddock/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [System status](https://github.com/racecraft-lab/paddock/blob/main/src/app/api/status/route.ts): `src/app/api/status/route.ts`

### Other components

- **Operator / Agent**
- **GitHub**

## Connections

- Operator / Agent → Dashboard: uses
- Operator / Agent → REST API: controls
- Operator / Agent → CLI: controls
- Operator / Agent → MCP server: controls
- GitHub → GitHub routes: issues and PRs
- GitHub routes → GitHub client: fetches issues
- GitHub routes → Issue sync: initializes labels
- Issue sync → GitHub client: fetches issues
- Issue sync → SQLite state: projects work items
- GitHub routes → SQLite state: records sync state
- Dashboard → REST API: requests data
- REST API → Task management: routes task requests
- REST API → Agent management: routes agent requests
- Task management → SQLite state: reads and writes
- Workspace projects → SQLite state: reads and writes
- Workflow contracts → SQLite state: manages templates
- Task pipelines → SQLite state: records runs
- Agent management → SQLite state: reads and writes
- Agent management → Harness adapters: supports harnesses
- Harness runs → SQLite state: records runs
- Harness runs → Harness adapters: uses harnesses
- Task artifacts → SQLite state: stores handoffs
- Quality review → SQLite state: records review
- Resource governance → SQLite state: reads and writes
- Harness observability → SQLite state: ingests telemetry
- System status → SQLite state: reads status
- Dashboard → System status: requests status