How builderz-labs/mission-control works
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: api API surface · page.tsx App shell · db.ts SQLite store · proxy.ts Proxy gate
Components 21
Runtime boundary
Next.js app routes, request gating, and the browser shell
- Proxy gate · Applies authentication, CSRF, and access control before app routes.
src/proxy.ts - App shell · Single-panel browser experience that swaps operator views in place.
src/app/[[...panel]]/page.tsx - Login/setup · Dedicated authentication and onboarding entry points.
src/app/login/page.tsx - API surface · 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 · Sessions, login, user lookup, access requests, and Google OAuth.
src/lib/auth.ts - SQLite store · Local SQLite access, schema, and migrations.
src/lib/db.ts - Task system · Task routing, status, costs, queueing, comments, and outcomes.
src/lib/task-routing.ts - Agent orchestration · Agent registration, heartbeats, sync, optimization, and workspace linkage.
src/lib/agent-sync.ts - Scheduler · Cron parsing, scheduled execution, and background orchestration.
src/lib/scheduler.ts - Event bus · Normalizes and broadcasts system activity to real-time consumers.
src/lib/event-bus.ts - Memory layer · Memory search, graph, linking, and context processing.
src/lib/memory-search.ts - Security layer · Secret scanning, security events, approvals, and audit flows.
src/lib/security-scan.ts - Gateway bridge · Gateway connectivity, runtime abstraction, and session/message transport.
src/lib/gateway-runtime.ts - Adapters · OpenClaw, CrewAI, LangGraph, AutoGen, Claude SDK, and generic adapter support.
src/lib/adapters/index.ts - Filesystem sync · Discovers and syncs local agent, workspace, skill, and session state.
src/lib/local-agent-sync.ts - Webhooks · Outbound webhook delivery, retries, and verification support.
src/lib/webhooks.ts
Operator UI
Reusable console layout, dashboards, and panels
- Layout system · Global header, nav rail, live feed, banners, and shell framing.
src/components/layout/header-bar.tsx - Dashboard · Operator overview with health, activity, and fleet widgets.
src/components/dashboard/dashboard.tsx - Panels · Task, agent, memory, gateway, security, and admin panels.
src/components/panels/task-board-panel.tsx - State hooks · Shared store and server-event / smart-poll hooks for live UI updates.
src/store/index.ts
Packaging
CLI, scripts, and deployment helpers
- CLI & scripts · Standalone server, CLI, TUI, and operational scripts.
scripts/mc-cli.cjs
Connections 26
- 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.