openclaw-mission-control/docs/05-architecture.md

Architecture

Deep dives

• Architecture deep dive
• Gateway protocol

Mission Control is the web UI + HTTP API for operating OpenClaw. It’s where you manage boards, tasks, agents, approvals, and (optionally) gateway connections.

Auth note: Mission Control supports two auth modes: local (shared bearer token) and clerk.

Components

• Frontend: Next.js app used by humans
  • Location: frontend/
  • Routes/pages: frontend/src/app/* (Next.js App Router)
  • API client: generated + custom fetch (see frontend/src/api/*, frontend/src/lib/api-base.ts)
• Backend: FastAPI service exposing REST endpoints
  • Location: backend/
  • Entrypoint: backend/app/main.py
  • API prefix: /api/v1/*
• Database: Postgres (see compose.yml)
• Gateway integration (optional): backend may call into OpenClaw Gateways over WebSockets
  • Client/protocol list: backend/app/services/openclaw/gateway_rpc.py

Diagram (conceptual)

flowchart LR
  U[User / Browser] -->|HTTP| FE[Next.js Frontend :3000]
  FE -->|HTTP /api/v1/*| BE[FastAPI Backend :8000]

  BE -->|SQL| PG[(Postgres :5432)]

  BE -->|WebSocket (optional)| GW[OpenClaw Gateway]
  GW --> OC[OpenClaw runtime]

How requests flow

1) A human uses the UI

1. Browser loads the Next.js frontend (frontend/).
2. Frontend calls backend endpoints using NEXT_PUBLIC_API_URL.
3. Backend routes under /api/v1/* (backend/app/main.py) and reads/writes Postgres.

Common UI-driven data shapes:

• “boards/tasks” views → board/task CRUD + streams.
• “activity feed” → activity/events endpoints.

2) Authentication (local or Clerk)

• Frontend:
  • local: token entry + token storage (frontend/src/components/organisms/LocalAuthLogin.tsx, frontend/src/auth/localAuth.ts).
  • clerk: Clerk wrappers/hooks (frontend/src/auth/clerk.tsx).
• Frontend → backend:
  • API calls attach Authorization: Bearer <token> from local mode token or Clerk session token (frontend/src/api/mutator.ts).
• Backend:
  • local: validates LOCAL_AUTH_TOKEN.
  • clerk: validates Clerk request state via clerk_backend_api + CLERK_SECRET_KEY.
  • Implementation: backend/app/core/auth.py.

3) Agent automation surface (/api/v1/agent/*)

Agents can call a dedicated API surface:

• Router: backend/app/api/agent.py (prefix /agent → mounted under /api/v1/agent/*).
• Authentication: X-Agent-Token header (or agent-only Authorization bearer parsing).
  • Implementation: backend/app/core/agent_auth.py.

Typical agent flows:

• Heartbeat/presence updates
• Task comment posting (evidence)
• Board memory updates
• Lead coordination actions (if board-lead agent)

4) Streaming/feeds (server-sent events)

Some endpoints support streaming via SSE (text/event-stream). Notes:

• Uses sse-starlette in backend routes (e.g. task/activity/memory routers).

5) Gateway integration (optional)

Mission Control can coordinate with OpenClaw Gateways over WebSockets.

• Protocol methods/events list: backend/app/services/openclaw/gateway_rpc.py.
• Operator-facing protocol docs: Gateway WebSocket protocol.

Where to start reading code

• Backend entrypoint + router wiring: backend/app/main.py
• Auth dependencies + access enforcement: backend/app/api/deps.py
• User auth: backend/app/core/auth.py
• Agent auth: backend/app/core/agent_auth.py
• Agent API surface: backend/app/api/agent.py