How racecraft-lab/paddock works
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: db.ts SQLite state · github/route.ts GitHub routes · index/route.ts REST API · github-sync-engine.ts Issue sync
Components 22
Work Intake
- GitHub routes
src/app/api/github/route.ts - Issue sync
src/lib/github-sync-engine.ts - GitHub client
src/lib/github.ts - Workspace projects
src/app/api/projects/route.ts
Work Execution
- Task management
src/app/api/tasks/route.ts - Workflow contracts
src/app/api/workflows/route.ts - Task pipelines
src/app/api/pipelines/run/route.ts - Agent management
src/app/api/agents/route.ts - Harness adapters
src/lib/adapters/index.ts - Harness runs
src/app/api/v1/runs/route.ts
Governance and Review
- Task artifacts
src/app/api/task-artifacts/route.ts - Quality review
src/app/api/quality-review/route.ts - Resource governance
src/app/api/governance/dispatch/route.ts
Operator Control
- Dashboard
src/app/[[...panel]]/page.tsx - REST API
src/app/api/index/route.ts - CLI
scripts/mc-cli.cjs - MCP server
scripts/mc-mcp-server.cjs
Runtime Services
- Harness observability
src/lib/observability/otlp-receiver.ts - SQLite state
src/lib/db.ts - System status
src/app/api/status/route.ts
Other components
- Operator / Agent
- GitHub
Connections 27
- 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