# crshdn/mission-control architecture

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

- Interactive diagram: https://gitdiagram.com/crshdn/mission-control
- Repository: https://github.com/crshdn/mission-control

## Overview

1. **What this repo is**
   Autensa is a single Next.js 14 application that combines a human-facing control plane with an autonomous product-improvement engine. It is not just a dashboard: the app also runs the orchestration logic that decides when to research, ideate, dispatch agents, track progress, and create pull requests.

2. **Primary runtime boundary**
   The main process is the Next.js app (`src/app` for pages and API routes). It serves the UI, exposes all server APIs, and acts as the integration hub. The major external runtime it depends on is the **OpenClaw Gateway** over WebSocket, which is the actual agent execution environment.

3. **Core user-facing subsystems**
   The UI is split into a few large surfaces:
   - **Task orchestration**: kanban, planning, convoy, chat, activity, checkpoints
   - **Product autopilot**: research, ideation, swipe, maybe-pool, health, schedules
   - **Workspace / agent ops**: workspace views, agent health, agent discovery, live feed
   - **Cost controls**: task/product cost dashboards and budget caps  
   These are all backed by API routes rather than local client-only state.

4. **Server-side domain boundaries**
   API routes are grouped by domain under `src/app/api`:
   - `tasks/*` for task lifecycle, planning, dispatch, checkpoints, convoy, chat
   - `products/*` for autopilot lifecycle: research, ideation, swipes, schedules, health, A/B tests
   - `agents/*` for agent registry, health, mailbox, discovery/import
   - `costs/*` for spend tracking and caps
   - `workspaces/*` for workspace data and knowledge
   - `openclaw/*` for gateway proxying and session/status access
   - `webhooks/*` for GitHub and agent-completion callbacks  
   This makes the repo strongly domain-oriented rather than layered around generic CRUD.

5. **Persistence and local state**
   The system uses **SQLite** as the authoritative database for products, tasks, ideas, swipe history, costs, checkpoints, workspaces, agent health, mailbox messages, and merge state. Database schema and migrations live in `src/lib/db`, with automatic migration execution on startup and backup support before destructive changes. File-based storage is also used for task images and workspace files on disk.

6. **Autopilot data flow**
   The product autopilot pipeline is the repo’s main business flow:
   **research → ideation → swipe → plan → build → test → review → PR**  
   Research and ideation run as server-side jobs, persist results in SQLite, and emit activity/events. Swipe decisions update preference models and may create tasks or queue ideas in the maybe pool. Approved ideas become build tasks that flow into agent dispatch and eventually GitHub PR creation.

7. **Agent execution flow**
   Autensa does not execute builds itself. It prepares context, workspace, and instructions, then dispatches work to the OpenClaw Gateway. The gateway runs the agent sessions, while Autensa tracks session metadata, health, checkpoints, mailbox messages, and completion callbacks. That separation is the key architectural boundary: **Autensa orchestrates; OpenClaw executes**.

8. **Real-time feedback loop**
   The app uses SSE (`/api/events/stream`) and related event APIs to keep the UI live. Activity dashboards, live feeds, unread badges, agent health indicators, and task chat all update from streamed server events rather than polling alone. This stream is fed by task progress, agent callbacks, cost events, and lifecycle changes from the orchestration layer.

9. **Advanced orchestration features**
   Two important execution modes sit on top of the core pipeline:
   - **Convoy mode**: decomposes large work into dependent subtasks and schedules them in parallel
   - **Checkpoint / recovery**: stores agent progress so work can resume after interruption  
   These features depend on dedicated orchestration libraries in `src/lib/convoy.ts`, `checkpoint.ts`, `agent-health.ts`, and `workspace-isolation.ts`.

10. **Workspace isolation**
    Build work happens in isolated per-task environments. For repo-backed projects, the system uses **git worktrees**; for local/non-repo work it uses task sandboxes under a workspace base path. It also manages port allocation so concurrent builds do not collide. This is a distinct operational boundary between the controller and the mutable build environment.

11. **Learning and adaptation**
    The repo includes a feedback loop for improving future agent behavior. `learner.ts`, `skills.ts`, `skill-extraction.ts`, and the autopilot preference model capture what worked during builds and what the operator swiped on. That knowledge is injected into later dispatches, so the system evolves across tasks and products.

12. **Cost, safety, and governance**
    Cost tracking and budget caps are first-class features, with APIs and libraries for per-task/per-product spend, cap enforcement, and pause behavior. Safety/governance is enforced through bearer-token auth, HMAC webhook validation, input validation, rollback/backup flows, and error reporting. There are also explicit admin endpoints for backups and rollbacks.

13. **External integrations**
    The two material integrations are:
    - **OpenClaw Gateway** via WebSocket for agent execution and session management
    - **GitHub** via webhooks for completion/revert automation and PR lifecycle handling  
    AI providers are indirectly involved through the gateway and autopilot research/ideation paths, but the repo’s main architectural dependency is still the gateway rather than a direct model SDK surface.

14. **Deployment shape**
    The project is designed for self-hosting, including Docker and Compose. Runtime state is split between the app container, SQLite volume, and workspace volume, while the gateway can run locally or remotely. That means the architecture is fundamentally **controller + external agent runtime + local persistence + workspace filesystem**.

Main entry points: [`src/app/page.tsx`](https://github.com/crshdn/mission-control/blob/main/src/app/page.tsx) (Control plane), [`src/app/api/tasks/route.ts`](https://github.com/crshdn/mission-control/blob/main/src/app/api/tasks/route.ts) (Tasks API), [`src/lib/db/schema.ts`](https://github.com/crshdn/mission-control/blob/main/src/lib/db/schema.ts) (SQLite DB), [`src/app/api/products/route.ts`](https://github.com/crshdn/mission-control/blob/main/src/app/api/products/route.ts) (Products API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI surfaces"]
  node_app_shell["App shell<br/>Next.js 14<br/>[layout.tsx]"]
  node_control_home["Control plane<br/>dashboard<br/>[page.tsx]"]
  node_task_workspace_ui["Task ops UI<br/>workbench<br/>[TaskModal.tsx]"]
  node_autopilot_ui["Autopilot UI<br/>product surfaces<br/>[page.tsx]"]
  node_workspace_ui["Workspace UI<br/>workspace views<br/>[page.tsx]"]
  node_cost_ui["Cost UI<br/>budget dashboard<br/>[CostDashboard.tsx]"]
end

subgraph group_api["Server APIs"]
  node_task_api["Tasks API<br/>task orchestration<br/>[route.ts]"]
  node_product_api["Products API<br/>autopilot pipeline<br/>[route.ts]"]
  node_agent_api["Agents API<br/>agent registry<br/>[route.ts]"]
  node_workspace_api["Workspaces API<br/>workspace data<br/>[route.ts]"]
  node_openclaw_api["OpenClaw API<br/>gateway proxy<br/>[route.ts]"]
  node_cost_api["Costs API<br/>spend control<br/>[route.ts]"]
  node_event_api["Events stream<br/>SSE realtime<br/>[route.ts]"]
end

subgraph group_core["Orchestration core"]
  node_orchestration{{"Orchestration core<br/>control logic<br/>[orchestration.ts]"}}
  node_autopilot_core{{"Autopilot pipeline<br/>product improvement engine<br/>[research.ts]"}}
  node_convoy_checkpoint{{"Convoy & recovery<br/>execution control<br/>[convoy.ts]"}}
  node_workspace_isolation{{"Isolation layer<br/>worktrees and sandboxes"}}
  node_costs_core{{"Cost tracking<br/>budget logic<br/>[tracker.ts]"}}
  node_learning_core{{"Learning loop<br/>skills and prefs<br/>[learner.ts]"}}
end

subgraph group_data["State & persistence"]
  node_db[("SQLite DB<br/>authoritative state<br/>[schema.ts]")]
  node_migrations["Migrations<br/>schema management<br/>[migrations.ts]"]
  node_workspaces_fs["Workspace files<br/>filesystem state"]
end

subgraph group_integrations["External integrations"]
  node_gateway[("OpenClaw Gateway<br/>websocket runtime")]
  node_github[("GitHub<br/>webhook integration")]
end

node_app_shell -->|"renders"| node_control_home
node_control_home -->|"navigates"| node_task_workspace_ui
node_control_home -->|"navigates"| node_autopilot_ui
node_control_home -->|"navigates"| node_workspace_ui
node_control_home -->|"navigates"| node_cost_ui
node_task_workspace_ui -->|"calls"| node_task_api
node_autopilot_ui -->|"calls"| node_product_api
node_workspace_ui -->|"calls"| node_workspace_api
node_workspace_ui -->|"calls"| node_agent_api
node_cost_ui -->|"calls"| node_cost_api
node_task_api -->|"uses"| node_orchestration
node_task_api -->|"uses"| node_convoy_checkpoint
node_task_api -->|"uses"| node_workspace_isolation
node_product_api -->|"uses"| node_autopilot_core
node_product_api -->|"uses"| node_learning_core
node_agent_api -->|"proxies"| node_gateway
node_openclaw_api -->|"proxies"| node_gateway
node_orchestration -->|"dispatches"| node_gateway
node_orchestration -->|"persists"| node_db
node_autopilot_core -->|"persists"| node_db
node_convoy_checkpoint -->|"persists"| node_db
node_workspace_isolation -->|"manages"| node_workspaces_fs
node_costs_core -->|"persists"| node_db
node_event_api -->|"streams to"| node_control_home
node_event_api -->|"emits"| node_orchestration
node_event_api -->|"receives"| node_gateway
node_github -->|"callbacks"| node_task_api
node_github -->|"callbacks"| node_product_api
node_migrations -->|"initializes"| node_db

click node_app_shell "https://github.com/crshdn/mission-control/blob/main/src/app/layout.tsx"
click node_control_home "https://github.com/crshdn/mission-control/blob/main/src/app/page.tsx"
click node_task_workspace_ui "https://github.com/crshdn/mission-control/blob/main/src/components/TaskModal.tsx"
click node_autopilot_ui "https://github.com/crshdn/mission-control/blob/main/src/app/autopilot/[productId]/page.tsx"
click node_workspace_ui "https://github.com/crshdn/mission-control/blob/main/src/app/workspace/[slug]/page.tsx"
click node_cost_ui "https://github.com/crshdn/mission-control/blob/main/src/components/costs/CostDashboard.tsx"
click node_task_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/tasks/route.ts"
click node_product_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/products/route.ts"
click node_agent_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/agents/route.ts"
click node_workspace_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/workspaces/route.ts"
click node_openclaw_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/openclaw/status/route.ts"
click node_cost_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/costs/route.ts"
click node_event_api "https://github.com/crshdn/mission-control/blob/main/src/app/api/events/stream/route.ts"
click node_db "https://github.com/crshdn/mission-control/blob/main/src/lib/db/schema.ts"
click node_migrations "https://github.com/crshdn/mission-control/blob/main/src/lib/db/migrations.ts"
click node_workspaces_fs "https://github.com/crshdn/mission-control/tree/main/data/task-images"
click node_orchestration "https://github.com/crshdn/mission-control/blob/main/src/lib/orchestration.ts"
click node_autopilot_core "https://github.com/crshdn/mission-control/blob/main/src/lib/autopilot/research.ts"
click node_convoy_checkpoint "https://github.com/crshdn/mission-control/blob/main/src/lib/convoy.ts"
click node_workspace_isolation "https://github.com/crshdn/mission-control/blob/main/src/lib/workspace-isolation.ts"
click node_costs_core "https://github.com/crshdn/mission-control/blob/main/src/lib/costs/tracker.ts"
click node_learning_core "https://github.com/crshdn/mission-control/blob/main/src/lib/learner.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_app_shell,node_control_home,node_task_workspace_ui,node_autopilot_ui,node_workspace_ui,node_cost_ui toneBlue
class node_task_api,node_product_api,node_agent_api,node_workspace_api,node_openclaw_api,node_cost_api,node_event_api toneAmber
class node_orchestration,node_autopilot_core,node_convoy_checkpoint,node_workspace_isolation,node_costs_core,node_learning_core toneMint
class node_db,node_migrations,node_workspaces_fs toneRose
class node_gateway,node_github toneIndigo
```

## Components

### UI surfaces

Next.js pages and client components for operator workflows

- [App shell](https://github.com/crshdn/mission-control/blob/main/src/app/layout.tsx): Next.js 14 · Root app layout and entrypoint for the control plane · `src/app/layout.tsx`
- [Control plane](https://github.com/crshdn/mission-control/blob/main/src/app/page.tsx): dashboard · Main landing surface for tasks, products, workspace, and settings · `src/app/page.tsx`
- [Task ops UI](https://github.com/crshdn/mission-control/blob/main/src/components/TaskModal.tsx): workbench · Kanban, planning, convoy, chat, activity, checkpoints, and task detail views · `src/components/TaskModal.tsx`
- [Autopilot UI](https://github.com/crshdn/mission-control/blob/main/src/app/autopilot/[productId]/page.tsx): product surfaces · Research, ideation, swipe, review, health, and maybe-pool workflows · `src/app/autopilot/[productId]/page.tsx`
- [Workspace UI](https://github.com/crshdn/mission-control/blob/main/src/app/workspace/[slug]/page.tsx): workspace views · Workspace dashboards and agent activity surfaces · `src/app/workspace/[slug]/page.tsx`
- [Cost UI](https://github.com/crshdn/mission-control/blob/main/src/components/costs/CostDashboard.tsx): budget dashboard · Spend views and budget cap controls · `src/components/costs/CostDashboard.tsx`

### Server APIs

Domain-oriented route handlers under src/app/api

- [Tasks API](https://github.com/crshdn/mission-control/blob/main/src/app/api/tasks/route.ts): task orchestration · Task lifecycle, planning, dispatch, convoy, chat, checkpoints, and workspace binding · `src/app/api/tasks/route.ts`
- [Products API](https://github.com/crshdn/mission-control/blob/main/src/app/api/products/route.ts): autopilot pipeline · Research, ideation, swipe, maybe-pool, health, schedules, variants, and AB tests · `src/app/api/products/route.ts`
- [Agents API](https://github.com/crshdn/mission-control/blob/main/src/app/api/agents/route.ts): agent registry · Agent discovery, health, mailbox, OpenClaw bindings, and registry operations · `src/app/api/agents/route.ts`
- [Workspaces API](https://github.com/crshdn/mission-control/blob/main/src/app/api/workspaces/route.ts): workspace data · Workspace metadata, knowledge, and workflows · `src/app/api/workspaces/route.ts`
- [OpenClaw API](https://github.com/crshdn/mission-control/blob/main/src/app/api/openclaw/status/route.ts): gateway proxy · Session/status/model access and orchestration proxy endpoints · `src/app/api/openclaw/status/route.ts`
- [Costs API](https://github.com/crshdn/mission-control/blob/main/src/app/api/costs/route.ts): spend control · Cost events, breakdowns, and caps enforcement · `src/app/api/costs/route.ts`
- [Events stream](https://github.com/crshdn/mission-control/blob/main/src/app/api/events/stream/route.ts): SSE realtime · Server-sent event stream and event recording for live UI updates · `src/app/api/events/stream/route.ts`

### Orchestration core

Server-side coordination, domain logic, and runtime control

- [Orchestration core](https://github.com/crshdn/mission-control/blob/main/src/lib/orchestration.ts): control logic · High-level task and product coordination across planning, dispatch, and recovery · `src/lib/orchestration.ts`
- [Autopilot pipeline](https://github.com/crshdn/mission-control/blob/main/src/lib/autopilot/research.ts): product improvement engine · Research, ideation, swipe, preferences, maybe-pool, health, scheduling, and recovery · `src/lib/autopilot/research.ts`
- [Convoy & recovery](https://github.com/crshdn/mission-control/blob/main/src/lib/convoy.ts): execution control · Parallel subtask scheduling, checkpoints, and resume logic · `src/lib/convoy.ts`
- [Isolation layer](https://github.com/crshdn/mission-control/blob/main/src/lib/workspace-isolation.ts): worktrees and sandboxes · Per-task worktrees, sandbox paths, and port allocation for concurrent builds · `src/lib/workspace-isolation.ts`
- [Cost tracking](https://github.com/crshdn/mission-control/blob/main/src/lib/costs/tracker.ts): budget logic · Spend accounting, reporting, cap checks, and pause behavior · `src/lib/costs/tracker.ts`
- [Learning loop](https://github.com/crshdn/mission-control/blob/main/src/lib/learner.ts): skills and prefs · Learner, skills extraction, and preference updates that influence later dispatches · `src/lib/learner.ts`

### State & persistence

SQLite, files, and backup/restore support

- [SQLite DB](https://github.com/crshdn/mission-control/blob/main/src/lib/db/schema.ts): authoritative state · Persistent store for tasks, products, ideas, costs, checkpoints, agents, and merge state · `src/lib/db/schema.ts`
- [Migrations](https://github.com/crshdn/mission-control/blob/main/src/lib/db/migrations.ts): schema management · Schema setup, automatic migrations, and startup database changes · `src/lib/db/migrations.ts`
- [Workspace files](https://github.com/crshdn/mission-control/tree/main/data/task-images): filesystem state · Task images, workspace files, worktrees, and sandboxed build artifacts · `data/task-images`

### External integrations

Gateway, GitHub, webhooks, and streaming events

- **OpenClaw Gateway**: websocket runtime · External agent execution environment that runs sessions and builds
- **GitHub**: webhook integration · PR, completion, and revert automation via webhooks

## Connections

- App shell → Control plane: renders · Root layout hosts the main operator entrypoint
- Control plane → Task ops UI: navigates · Primary control plane opens task orchestration surfaces
- Control plane → Autopilot UI: navigates · Primary control plane opens product autopilot surfaces
- Control plane → Workspace UI: navigates · Primary control plane opens workspace and agent ops surfaces
- Control plane → Cost UI: navigates · Primary control plane opens spend and budget controls
- Task ops UI → Tasks API: calls · Task views are backed by task lifecycle and orchestration APIs
- Autopilot UI → Products API: calls · Autopilot views drive server-side research, ideation, swipe, and health flows
- Workspace UI → Workspaces API: calls · Workspace views load metadata, knowledge, and workflows from APIs
- Workspace UI → Agents API: calls · Agent operations and live health data are fetched through agent APIs
- Cost UI → Costs API: calls · Budget dashboards and caps manager operate through cost APIs
- Tasks API → Orchestration core: uses · Task routes delegate scheduling, dispatch, planning, and state transitions
- Tasks API → Convoy & recovery: uses · Task routes expose convoy dispatch and checkpoint recovery
- Tasks API → Isolation layer: uses · Task execution is prepared in isolated workspaces and sandboxes
- Products API → Autopilot pipeline: uses · Product routes run the research-to-PR pipeline and persist results
- Products API → Learning loop: uses · Swipe and build feedback update preference and skill models
- Agents API → OpenClaw Gateway: proxies · Agent session and health operations bridge to the OpenClaw runtime
- OpenClaw API → OpenClaw Gateway: proxies · OpenClaw endpoints expose gateway sessions, status, and model access
- Orchestration core → OpenClaw Gateway: dispatches · Autensa prepares context and delegates execution to the external agent runtime
- Orchestration core → SQLite DB: persists · Task and product orchestration state is stored in SQLite
- Autopilot pipeline → SQLite DB: persists · Research, ideation, swipe history, and product state are stored durably
- Convoy & recovery → SQLite DB: persists · Convoy progress and checkpoints are recovered from SQLite state
- Isolation layer → Workspace files: manages · Isolated build environments use worktrees, sandboxes, and task files
- Cost tracking → SQLite DB: persists · Spending records and caps are tracked in SQLite
- Events stream → Control plane: streams to · Realtime events power live dashboards and badges
- Events stream → Orchestration core: emits · Task and product lifecycle changes feed the event stream
- Events stream → OpenClaw Gateway: receives · Agent callbacks and session changes surface through realtime events
- GitHub → Tasks API: callbacks · GitHub webhooks trigger completion and revert automation
- GitHub → Products API: callbacks · GitHub webhook events support PR lifecycle handling
- Migrations → SQLite DB: initializes · Schema migrations prepare and evolve the SQLite database
