# builderz-labs/mission-control architecture

> Architecture diagram of the GitHub repository builderz-labs/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/builderz-labs/mission-control
- Repository: https://github.com/builderz-labs/mission-control

## Overview

1. **What this repo is**
   Mission Control is a self-hosted control plane for AI agents. Architecturally it is a Next.js 16 application that serves both the operator UI and a large REST API, backed by local SQLite storage and a set of synchronization/integration services.

2. **Primary runtime boundary**
   The server side lives in the Next.js app router under `src/app`. The main browser experience is a single SPA-like shell (`src/app/[[...panel]]/page.tsx`) that swaps many panels in place. Separate routes exist for login and setup, plus a dedicated `/api/*` surface for all backend operations.

3. **Request entry and security gate**
   `src/proxy.ts` is an important boundary: it applies authentication gating, CSRF checks, and network access control before requests reach the app. This aligns with the repo’s emphasis on session cookies, API keys, role-based access, and optional host allowlisting for production.

4. **Backend API surface**
   The repo exposes a broad set of feature-specific route handlers under `src/app/api`. The core domains are agents, tasks, sessions, memory, skills, security, webhooks, workflows, projects, workspaces, gateways, authentication, and diagnostics. The API is not a thin CRUD layer; many routes orchestrate local file scans, gateway calls, task dispatch, or background jobs.

5. **State and persistence**
   The central persistence layer is SQLite via `better-sqlite3`, wrapped by `src/lib/db.ts` and schema migrations in `src/lib/migrations.ts` / `src/lib/schema.sql`. Runtime data is stored in a local data directory, and the README emphasizes that the project is intentionally “zero external deps” for core operation.

6. **Domain services in `src/lib`**
   Most application logic sits in `src/lib` as composable services: auth, task routing/status/costs, scheduler/recurring tasks, event bus, webhook delivery, memory search/graph, onboarding, security events/scanning, and run/session tracking. These modules are the real business-logic boundary between UI/API and storage.

7. **Agent and gateway orchestration**
   A major subsystem is agent orchestration. Agents register, heartbeat, receive tasks, and report outcomes through `/api/agents/*` and `/api/tasks/*`. The repo also supports multi-gateway and adapter-based interoperability via `src/lib/adapters` for OpenClaw, CrewAI, LangGraph, AutoGen, Claude SDK, and a generic adapter. Gateway connectivity is optional, but when enabled it feeds real-time session and messaging flows.

8. **Local filesystem integrations**
   Several features are driven by local filesystem state rather than a remote service: Claude Code session/task discovery, agent/workspace sync, skill roots, memory files, and OpenClaw state/config discovery. This repo therefore bridges browser UI with local developer/agent environments, not just a centralized database.

9. **UI composition**
   The front end is organized into reusable layout and panel modules rather than page-specific views. `src/components/layout`, `dashboard`, `panels`, `chat`, and `modals` form the operator console, while state is coordinated through `src/store/index.ts` and server-event hooks. The UI is largely a monitoring/operations cockpit for the underlying services.

10. **Real-time data flow**
   Live updates are first-class. The README calls out WebSocket and SSE, and the codebase includes websocket utilities and server-event hooks. Typical flow is: agent/system event occurs → backend logs/normalizes it → push channel or smart polling updates the dashboard panels and live feed.

11. **Security, trust, and quality control**
   Security is a separate subsystem, not an afterthought. It includes secret scanning, MCP/audit logging, injection guards, trust scoring, security audits/scans, and exec approval flows. Quality review and eval routes add another gating layer for task completion and agent performance analysis.

12. **External service boundaries**
   The main external integrations are Google OAuth, GitHub sync, webhooks, and agent gateways. These integrations are kept behind dedicated lib modules and API routes so the core app remains usable in standalone local mode, while still supporting richer connected deployments.

13. **Operational packaging**
   Deployment is treated as part of the architecture. The repo includes Dockerfiles, compose files, install scripts, ops templates, and CLI utilities for standalone/server modes. Data persistence and runtime configuration are designed around local disk paths and environment variables, which matters for any architecture diagram of production use.

14. **Testing and contract enforcement**
   The repo has a large unit and E2E test surface plus OpenAPI documentation. Tests validate auth, API contract parity, gateway behavior, security, cron logic, and UI flows, which suggests the system is tightly coupled across UI/API/storage and relies on automated checks to preserve cross-cutting behavior.

Main entry points: [`src/app/api`](https://github.com/builderz-labs/mission-control/tree/main/src/app/api) (API surface), [`src/app/[[...panel]]/page.tsx`](https://github.com/builderz-labs/mission-control/blob/main/src/app/[[...panel]]/page.tsx) (App shell), [`src/lib/db.ts`](https://github.com/builderz-labs/mission-control/blob/main/src/lib/db.ts) (SQLite store), [`src/proxy.ts`](https://github.com/builderz-labs/mission-control/blob/main/src/proxy.ts) (Proxy gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime boundary"]
  node_proxy{{"Proxy gate<br/>auth/csrf/net gate<br/>[proxy.ts]"}}
  node_app_shell["App shell<br/>Next.js shell<br/>[page.tsx]"]
  node_login_setup["Login/setup<br/>entry routes<br/>[page.tsx]"]
  node_api_root["API surface<br/>route handlers"]
end

subgraph group_services["Core services"]
  node_auth_service["Auth & users<br/>identity service<br/>[auth.ts]"]
  node_db_layer[("SQLite store<br/>persistence<br/>[db.ts]")]
  node_task_system["Task system<br/>routing/dispatch<br/>[task-routing.ts]"]
  node_agent_orchestration["Agent orchestration<br/>runtime control<br/>[agent-sync.ts]"]
  node_scheduler["Scheduler<br/>recurring jobs<br/>[scheduler.ts]"]
  node_event_bus["Event bus<br/>live events<br/>[event-bus.ts]"]
  node_memory_service["Memory layer<br/>search/graph<br/>[memory-search.ts]"]
  node_security_service["Security layer<br/>scans/audit<br/>[security-scan.ts]"]
  node_gateway_integration["Gateway bridge<br/>adapter runtime<br/>[gateway-runtime.ts]"]
  node_adapter_layer["Adapters<br/>[index.ts]"]
  node_filesystem_sync["Filesystem sync<br/>local discovery"]
  node_webhooks["Webhooks<br/>delivery engine<br/>[webhooks.ts]"]
end

subgraph group_ui["Operator UI"]
  node_ui_layout["Layout system<br/>console chrome<br/>[header-bar.tsx]"]
  node_dashboard["Dashboard<br/>ops overview<br/>[dashboard.tsx]"]
  node_panels["Panels"]
  node_store_hooks["State hooks<br/>client state<br/>[index.ts]"]
end

subgraph group_ops["Packaging"]
  node_cli_ops["CLI & scripts<br/>ops tooling<br/>[mc-cli.cjs]"]
end

node_proxy -->|"guards"| node_app_shell
node_proxy -->|"guards"| node_api_root
node_login_setup -->|"uses"| node_auth_service
node_app_shell -->|"renders"| node_ui_layout
node_app_shell -->|"shows"| node_dashboard
node_app_shell -->|"swaps"| node_panels
node_app_shell -->|"binds"| node_store_hooks
node_api_root -->|"auth"| node_auth_service
node_api_root -->|"tasks"| node_task_system
node_api_root -->|"agents"| node_agent_orchestration
node_api_root -->|"memory"| node_memory_service
node_api_root -->|"security"| node_security_service
node_api_root -->|"cron"| node_scheduler
node_api_root -->|"deliveries"| node_webhooks
node_api_root -->|"connects"| node_gateway_integration
node_api_root -->|"adapters"| node_adapter_layer
node_api_root -->|"local sync"| node_filesystem_sync
node_task_system -->|"persists"| node_db_layer
node_agent_orchestration -->|"persists"| node_db_layer
node_memory_service -->|"stores"| node_db_layer
node_security_service -->|"records"| node_db_layer
node_scheduler -->|"stores"| node_db_layer
node_event_bus -->|"streams"| node_store_hooks
node_webhooks -->|"publishes"| node_event_bus
node_cli_ops -.->|"drives"| node_api_root
node_cli_ops -.->|"manages"| node_filesystem_sync

click node_proxy "https://github.com/builderz-labs/mission-control/blob/main/src/proxy.ts"
click node_app_shell "https://github.com/builderz-labs/mission-control/blob/main/src/app/[[...panel]]/page.tsx"
click node_login_setup "https://github.com/builderz-labs/mission-control/blob/main/src/app/login/page.tsx"
click node_api_root "https://github.com/builderz-labs/mission-control/tree/main/src/app/api"
click node_auth_service "https://github.com/builderz-labs/mission-control/blob/main/src/lib/auth.ts"
click node_db_layer "https://github.com/builderz-labs/mission-control/blob/main/src/lib/db.ts"
click node_task_system "https://github.com/builderz-labs/mission-control/blob/main/src/lib/task-routing.ts"
click node_agent_orchestration "https://github.com/builderz-labs/mission-control/blob/main/src/lib/agent-sync.ts"
click node_scheduler "https://github.com/builderz-labs/mission-control/blob/main/src/lib/scheduler.ts"
click node_event_bus "https://github.com/builderz-labs/mission-control/blob/main/src/lib/event-bus.ts"
click node_memory_service "https://github.com/builderz-labs/mission-control/blob/main/src/lib/memory-search.ts"
click node_security_service "https://github.com/builderz-labs/mission-control/blob/main/src/lib/security-scan.ts"
click node_gateway_integration "https://github.com/builderz-labs/mission-control/blob/main/src/lib/gateway-runtime.ts"
click node_adapter_layer "https://github.com/builderz-labs/mission-control/blob/main/src/lib/adapters/index.ts"
click node_filesystem_sync "https://github.com/builderz-labs/mission-control/blob/main/src/lib/local-agent-sync.ts"
click node_webhooks "https://github.com/builderz-labs/mission-control/blob/main/src/lib/webhooks.ts"
click node_ui_layout "https://github.com/builderz-labs/mission-control/blob/main/src/components/layout/header-bar.tsx"
click node_dashboard "https://github.com/builderz-labs/mission-control/blob/main/src/components/dashboard/dashboard.tsx"
click node_panels "https://github.com/builderz-labs/mission-control/blob/main/src/components/panels/task-board-panel.tsx"
click node_store_hooks "https://github.com/builderz-labs/mission-control/blob/main/src/store/index.ts"
click node_cli_ops "https://github.com/builderz-labs/mission-control/blob/main/scripts/mc-cli.cjs"

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_proxy,node_app_shell,node_login_setup,node_api_root toneBlue
class node_auth_service,node_db_layer,node_task_system,node_agent_orchestration,node_scheduler,node_event_bus,node_memory_service,node_security_service,node_gateway_integration,node_adapter_layer,node_filesystem_sync,node_webhooks toneAmber
class node_ui_layout,node_dashboard,node_panels,node_store_hooks toneMint
class node_cli_ops toneRose
```

## Components

### Runtime boundary

Next.js app routes, request gating, and the browser shell

- [Proxy gate](https://github.com/builderz-labs/mission-control/blob/main/src/proxy.ts): auth/csrf/net gate · Applies authentication, CSRF, and access control before app routes. · `src/proxy.ts`
- [App shell](https://github.com/builderz-labs/mission-control/blob/main/src/app/[[...panel]]/page.tsx): Next.js shell · Single-panel browser experience that swaps operator views in place. · `src/app/[[...panel]]/page.tsx`
- [Login/setup](https://github.com/builderz-labs/mission-control/blob/main/src/app/login/page.tsx): entry routes · Dedicated authentication and onboarding entry points. · `src/app/login/page.tsx`
- [API surface](https://github.com/builderz-labs/mission-control/tree/main/src/app/api): route handlers · Main REST surface for agents, tasks, memory, security, workflows, and admin flows. · `src/app/api`

### Core services

Domain logic, persistence, scheduling, security, and integrations

- [Auth & users](https://github.com/builderz-labs/mission-control/blob/main/src/lib/auth.ts): identity service · Sessions, login, user lookup, access requests, and Google OAuth. · `src/lib/auth.ts`
- [SQLite store](https://github.com/builderz-labs/mission-control/blob/main/src/lib/db.ts): persistence · Local SQLite access, schema, and migrations. · `src/lib/db.ts`
- [Task system](https://github.com/builderz-labs/mission-control/blob/main/src/lib/task-routing.ts): routing/dispatch · Task routing, status, costs, queueing, comments, and outcomes. · `src/lib/task-routing.ts`
- [Agent orchestration](https://github.com/builderz-labs/mission-control/blob/main/src/lib/agent-sync.ts): runtime control · Agent registration, heartbeats, sync, optimization, and workspace linkage. · `src/lib/agent-sync.ts`
- [Scheduler](https://github.com/builderz-labs/mission-control/blob/main/src/lib/scheduler.ts): recurring jobs · Cron parsing, scheduled execution, and background orchestration. · `src/lib/scheduler.ts`
- [Event bus](https://github.com/builderz-labs/mission-control/blob/main/src/lib/event-bus.ts): live events · Normalizes and broadcasts system activity to real-time consumers. · `src/lib/event-bus.ts`
- [Memory layer](https://github.com/builderz-labs/mission-control/blob/main/src/lib/memory-search.ts): search/graph · Memory search, graph, linking, and context processing. · `src/lib/memory-search.ts`
- [Security layer](https://github.com/builderz-labs/mission-control/blob/main/src/lib/security-scan.ts): scans/audit · Secret scanning, security events, approvals, and audit flows. · `src/lib/security-scan.ts`
- [Gateway bridge](https://github.com/builderz-labs/mission-control/blob/main/src/lib/gateway-runtime.ts): adapter runtime · Gateway connectivity, runtime abstraction, and session/message transport. · `src/lib/gateway-runtime.ts`
- [Adapters](https://github.com/builderz-labs/mission-control/blob/main/src/lib/adapters/index.ts): interop adapters · OpenClaw, CrewAI, LangGraph, AutoGen, Claude SDK, and generic adapter support. · `src/lib/adapters/index.ts`
- [Filesystem sync](https://github.com/builderz-labs/mission-control/blob/main/src/lib/local-agent-sync.ts): local discovery · Discovers and syncs local agent, workspace, skill, and session state. · `src/lib/local-agent-sync.ts`
- [Webhooks](https://github.com/builderz-labs/mission-control/blob/main/src/lib/webhooks.ts): delivery engine · Outbound webhook delivery, retries, and verification support. · `src/lib/webhooks.ts`

### Operator UI

Reusable console layout, dashboards, and panels

- [Layout system](https://github.com/builderz-labs/mission-control/blob/main/src/components/layout/header-bar.tsx): console chrome · Global header, nav rail, live feed, banners, and shell framing. · `src/components/layout/header-bar.tsx`
- [Dashboard](https://github.com/builderz-labs/mission-control/blob/main/src/components/dashboard/dashboard.tsx): ops overview · Operator overview with health, activity, and fleet widgets. · `src/components/dashboard/dashboard.tsx`
- [Panels](https://github.com/builderz-labs/mission-control/blob/main/src/components/panels/task-board-panel.tsx): feature panels · Task, agent, memory, gateway, security, and admin panels. · `src/components/panels/task-board-panel.tsx`
- [State hooks](https://github.com/builderz-labs/mission-control/blob/main/src/store/index.ts): client state · Shared store and server-event / smart-poll hooks for live UI updates. · `src/store/index.ts`

### Packaging

CLI, scripts, and deployment helpers

- [CLI & scripts](https://github.com/builderz-labs/mission-control/blob/main/scripts/mc-cli.cjs): ops tooling · Standalone server, CLI, TUI, and operational scripts. · `scripts/mc-cli.cjs`

## Connections

- Proxy gate → App shell: guards · Requests reach the browser shell only after auth and access checks.
- Proxy gate → API surface: guards · Gatekeeps API requests with security checks.
- Login/setup → Auth & users: uses · Login and onboarding routes rely on auth/session logic.
- App shell → Layout system: renders · The shell composes the global console layout.
- App shell → Dashboard: shows · Primary panel experience is dashboard and operational views.
- App shell → Panels: swaps · Panel routing changes in-place without leaving the shell.
- App shell → State hooks: binds · Client state and live updates drive the shell UI.
- API surface → Auth & users: auth · Authentication routes and user/session endpoints depend on identity services.
- API surface → Task system: tasks · Task routes orchestrate dispatch, comments, outcomes, and queueing.
- API surface → Agent orchestration: agents · Agent routes manage registration, heartbeat, sync, and diagnostics.
- API surface → Memory layer: memory · Memory routes expose search, graph, context, and processing operations.
- API surface → Security layer: security · Security routes trigger audits, scans, approvals, and fixes.
- API surface → Scheduler: cron · Schedule and recurring-task routes delegate to the scheduler.
- API surface → Webhooks: deliveries · Webhook routes create, verify, retry, and inspect deliveries.
- API surface → Gateway bridge: connects · Gateway routes connect and control external agent gateways.
- API surface → Adapters: adapters · Adapter endpoints and runtime discovery use the adapter layer.
- API surface → Filesystem sync: local sync · Local discovery routes inspect host files and runtime state.
- Task system → SQLite store: persists · Task state is stored in the local SQLite database.
- Agent orchestration → SQLite store: persists · Agent registry and runtime metadata are backed by SQLite.
- Memory layer → SQLite store: stores · Memory structures and indexes are backed by local persistence.
- Security layer → SQLite store: records · Security events, scans, and approvals are persisted locally.
- Scheduler → SQLite store: stores · Recurring jobs and run state use the database layer.
- Event bus → State hooks: streams · Live events feed the UI through SSE/WebSocket-style hooks.
- Webhooks → Event bus: publishes · Delivery outcomes are surfaced as events.
- CLI & scripts → API surface: drives · CLI and scripts exercise the same operational API surface.
- CLI & scripts → Filesystem sync: manages · Operational tooling works with local runtime and workspace state.
