Skip to main content

Architecture

System Overview​

Mission Control v2 is a combined operator UI and backend service.

Main layers:

  • frontend/
    • React/Vite operator interface
  • backend/
    • FastAPI API, sync orchestration, auth, audit, and recovery service
  • pm_core/
    • shared PM/domain import, mirror, and doctor logic
  • PostgreSQL
    • persisted application state
  • external providers
    • Gitea, GitHub, GitLab, Plane, n8n, runtime webhooks, OIDC, approval callbacks

Main Components​

Frontend​

  • operator shells for:
    • Inbox
    • Today
    • Work
    • Planning
    • Delivery
    • Risks
    • Recovery
    • Settings
  • consumes backend /api/v1/* routes

Backend​

  • application bootstrap in backend/app/main.py
  • routers in backend/app/api/routers/
  • services in backend/app/services/
  • persistence in backend/app/db.py and SQLAlchemy models
  • MCP server entrypoint in backend.app.mcp.mission_control_server

Backend services may adapt SQLAlchemy state into a snapshot payload, but PM mirror and doctor rules stay in pm_core. Backend adapters must pass the snapshot through to pm_core instead of reselecting mirror fields or reimplementing doctor findings locally.

Persistence​

  • PostgreSQL-backed canonical runtime state
  • stores:
    • projects
    • tasks
    • lanes
    • agents
    • handoffs
    • planning objects
    • delivery objects
    • snapshots
    • audit events
    • integration connections and external mappings

Data Flow​

Core Operator Flow​

  1. operator uses frontend
  2. frontend calls backend REST API
  3. backend updates PostgreSQL state
  4. backend writes audit events
  5. backend optionally reconciles with provider/Plane/runtime integrations

Sync Flow​

  1. external state is discovered or pushed in through webhook/callback
  2. backend normalizes provider-specific payloads
  3. Mission Control updates local canonical task/planning state
  4. changed state may be mirrored back out to Plane or repo issues when configured

Fabric Discovery Flow​

  1. external discovery client reads:
  • /healthz
  • /readyz
  • /versionz
  • /contractz
  • /fabric-presencez
  • /fabric-compatibilityz
  • /fabric-manifest.json
  1. client can then read project-level operator surfaces over /api/v1/*

External and Internal Interfaces​

Internal:

  • frontend -> backend REST
  • MCP -> backend REST
  • backend -> PostgreSQL

External:

  • backend -> Gitea/GitHub/GitLab APIs
  • backend <-> Plane API and Plane webhook
  • backend -> n8n API/webhooks
  • backend -> runtime dispatch webhook
  • backend <- approval callback
  • backend <-> OIDC/provider OAuth callbacks

Operating Assumptions​

  • Linux container runtime is the primary deployment target
  • PostgreSQL is available
  • provider credentials and webhook secrets are configured outside the repo
  • the host deployment path uses docker-compose.v2.yml
  • Gitea remains the canonical repository history source of truth

Role In Helpifyr​

Mission Control v2 is the operator control plane, not the fabric backbone itself.

Expected relation to helpifyr-fabric:

  • Fabric should discover it first as a standalone operator service
  • Fabric should not directly own Mission Control persistence or bypass audit paths
  • later Fabric integration should stay read-first, then policy-aware, before any write/control expansion

License: AGPLv3

Helpifyr: https://helpifyr.com