Architecture

Documentation Map

• Overview

• Quick Start

• Installation

• Configuration

• Operations

• Troubleshooting

• Release Notes

• Compatibility

• Architecture

• API Reference

• Security

• Integrations

• Capabilities

• Data Model

• Roadmap

• Project Plan

• OSS Inventory

• Channel: latest

• Source repo: JaddaHelpifyr/jhf-pattern

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 and mirror 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

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

2. 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