# loudiman/mission-forge architecture

> Architecture diagram of the GitHub repository loudiman/mission-forge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/loudiman/mission-forge
- Repository: https://github.com/loudiman/mission-forge

## Overview

1. **What this repo is**
MissionForge is a Python 3.11+ toolchain centered on a deterministic mission workspace stored on disk. The core product is a Typer-based CLI, with a separate FastAPI backend for API access, plus documentation, static landing-page assets, and CI/CD automation.

2. **Primary runtime boundary: CLI vs backend**
The CLI lives under `src/missionforge/cli/` and is the main user entrypoint for mission lifecycle commands. The backend lives under `src/missionforge/backend/` and appears to expose mission data and related operations over HTTP. These are separate surfaces sharing the same core models and validation logic rather than duplicating business rules.

3. **Workspace and filesystem as the system of record**
MissionForge is file-centric. Mission state is persisted in `.missionforge/missions/<MISSION_ID>/` with `mission.yaml`, generated `plan.yaml`, `report.md`, and `sub-missions/` artifacts. The `core/workspace.py` module and the repository layer act as the main boundary between logic and the on-disk workspace layout.

4. **Mission lifecycle pipeline**
The repository is organized around a workflow: initialize a workspace, define a parent mission, decompose into sub-missions, validate sub-missions, generate an execution plan, choose the next task, capture baselines, and produce a final report. The CLI command modules map directly to these stages: `workspace`, `mission`, `decompose`, `plan`, `next`, `baseline`, `validate`, and `report`.

5. **Validation and schema enforcement layer**
`src/missionforge/models/schemas.py` and `src/missionforge/schemas/` define the structured mission and sub-mission contracts using Pydantic v2 and JSON/schema validators. `core/mission_validator.py`, `core/validation_service.py`, and `core/parent_validation_service.py` perform cross-field and cross-file checks such as ID format, parent-child linkage, allowed/forbidden path constraints, and dependency consistency.

6. **Planning and dependency resolution**
The planning subsystem resolves sub-mission dependencies into a deterministic execution order. The README states it uses topological sorting and detects cycles; this logic is implemented in the planning command and supporting core services, then written back to `plan.yaml` for later consumption by `next` and reporting flows.

7. **Baseline and validation evidence**
`core/baseline_service.py` and `core/report_generator.py` support the evidence-gathering stages around implementation. Baselines and validation artifacts are captured per sub-mission and then folded into a PR-ready Markdown report through a Jinja2 template in `src/missionforge/templates/mission_report.md.j2`.

8. **Git and subprocess are deliberately constrained**
`src/missionforge/git/operations.py` wraps system `git` commands, and `src/missionforge/utils/subprocess_utils.py` centralizes safe subprocess execution. This is a clear security boundary: external commands are used for deterministic operations, but the code avoids shell expansion and keeps command execution auditable.

9. **Extensibility via plugins**
`src/missionforge/plugins/` defines a plugin system for commands, validators, formatters, and metrics. The registry and base classes indicate the architecture expects future extension without changing the core mission workflow, which is important for architecture diagrams that need to show optional extension points.

10. **Backend API structure**
The backend has its own main app, routers, response models, cache, config, and CORS middleware. The cache layer uses file-backed storage (`backend/cache/file_cache.py`), suggesting the API is still anchored in workspace artifacts rather than an independent database. In diagrams, this should be shown as an API façade over the same mission files and core validation logic.

11. **Supporting utilities and safeguards**
Utilities in `src/missionforge/utils/` handle path matching and subprocess concerns, which are critical because the repo enforces scoped file access for sub-missions. These utilities support the repo’s boundary checks around `allowed_paths`, `forbidden_paths`, and workspace-safe output generation.

12. **Testing architecture**
The test suite is broad and maps well to the layered design: unit tests cover models, validators, workspace logic, subprocess wrappers, and git operations; integration tests cover CLI workflows and backend API behavior; manual tests exist for edge cases and parent-validation scenarios. For a diagram, this means most architectural seams are already explicitly tested.

13. **Operational and delivery surface**
GitHub Actions workflows handle CI, issue numbering, and landing-page deployment. The `landing-page/` directory is a separate static site surface, likely used for product/documentation presentation rather than core mission execution.

14. **Overall architectural shape**
The repo is best understood as a deterministic workflow engine around mission files: CLI and backend are thin orchestration layers, core services enforce rules, schemas define contracts, git/subprocess utilities interact with the environment, and outputs are persisted back into the mission workspace. The main diagram boundaries should be: user interface, core business rules, filesystem workspace, external command execution, and optional HTTP backend.

Main entry points: [`src/missionforge/core/workspace.py`](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/workspace.py) (Workspace), [`src/missionforge/cli/app.py`](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/app.py) (CLI app), [`src/missionforge/core/validation_service.py`](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/validation_service.py) (Validation core), [`src/missionforge/backend/routers/missions.py`](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/routers/missions.py) (Mission routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User surfaces"]
  node_cli_app["CLI app<br/>Typer entrypoint<br/>[app.py]"]
  node_cli_workspace["Workspace cmd<br/>CLI command<br/>[workspace.py]"]
  node_cli_mission["Mission cmd<br/>CLI command<br/>[mission.py]"]
  node_cli_decompose["Decompose cmd<br/>CLI command<br/>[decompose.py]"]
  node_cli_plan["Plan cmd<br/>CLI command<br/>[plan.py]"]
  node_cli_next["Next cmd<br/>CLI command<br/>[next.py]"]
  node_cli_validate["Validate cmd<br/>CLI command<br/>[validate.py]"]
  node_cli_baseline["Baseline cmd<br/>CLI command<br/>[baseline.py]"]
  node_cli_report["Report cmd<br/>CLI command<br/>[report.py]"]
  node_backend_app["API app<br/>[main.py]"]
  node_backend_routes["Mission routes<br/>API router<br/>[missions.py]"]
end

subgraph group_engine["Workflow engine"]
  node_validation_core["Validation core<br/>rules engine"]
  node_parent_validation["Parent checks<br/>link validation"]
  node_mission_validator["Mission validator<br/>consistency checks"]
  node_baseline_service["Baseline service<br/>evidence capture"]
  node_report_generator["Report generator<br/>Markdown renderer"]
  node_report_tpl["Report template<br/>Jinja2 template"]
  node_plan_logic["Plan logic<br/>dependency resolver<br/>[plan.py]"]
  node_next_logic["Next selection<br/>execution selector<br/>[next.py]"]
end

subgraph group_data["Contracts and storage"]
  node_workspace[("Workspace<br/>filesystem boundary<br/>[workspace.py]")]
  node_mission_store["Mission artifacts<br/>workspace artifacts<br/>[missions]"]
  node_schemas["Schemas<br/>Pydantic/JSON schema<br/>[schemas.py]"]
  node_schema_validators["Schema validators<br/>json schema rules<br/>[validators.py]"]
end

subgraph group_infra["Execution boundary"]
  node_git_ops["Git ops<br/>git wrapper<br/>[operations.py]"]
  node_subprocess_utils["Subprocess utils<br/>safe execution"]
  node_backend_cache["File cache<br/>backend cache<br/>[file_cache.py]"]
end

subgraph group_ext["Extensions"]
  node_plugin_registry["Plugin registry<br/>extension hub<br/>[registry.py]"]
end

node_cli_app -->|"dispatches"| node_cli_workspace
node_cli_app -->|"dispatches"| node_cli_mission
node_cli_app -->|"dispatches"| node_cli_decompose
node_cli_app -->|"dispatches"| node_cli_plan
node_cli_app -->|"dispatches"| node_cli_next
node_cli_app -->|"dispatches"| node_cli_validate
node_cli_app -->|"dispatches"| node_cli_baseline
node_cli_app -->|"dispatches"| node_cli_report
node_cli_workspace -->|"initializes"| node_workspace
node_cli_mission -->|"writes"| node_schemas
node_cli_mission -->|"checks"| node_schema_validators
node_cli_decompose -->|"checks"| node_validation_core
node_cli_decompose -->|"reads/writes"| node_workspace
node_cli_plan -->|"drives"| node_plan_logic
node_cli_plan -->|"persists"| node_workspace
node_cli_next -->|"uses"| node_next_logic
node_cli_next -->|"reads"| node_workspace
node_cli_validate -->|"runs"| node_validation_core
node_cli_baseline -->|"captures"| node_baseline_service
node_cli_baseline -->|"writes"| node_workspace
node_cli_report -->|"renders"| node_report_generator
node_report_generator -->|"uses"| node_report_tpl
node_report_generator -->|"reads"| node_workspace
node_validation_core -->|"includes"| node_mission_validator
node_validation_core -->|"includes"| node_parent_validation
node_validation_core -->|"relies on"| node_schemas
node_mission_validator -->|"enforces"| node_schema_validators
node_mission_validator -->|"scopes"| node_workspace
node_parent_validation -->|"scopes"| node_workspace
node_plan_logic -->|"reads/writes"| node_workspace
node_next_logic -->|"reads"| node_workspace
node_baseline_service -->|"reads"| node_workspace
node_report_generator -.->|"references"| node_git_ops
node_git_ops -->|"executes through"| node_subprocess_utils
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"serves"| node_workspace
node_backend_routes -->|"uses"| node_backend_cache
node_backend_routes -->|"serializes"| node_schemas
node_backend_routes -.->|"shares rules"| node_validation_core
node_plugin_registry -.->|"extends"| node_cli_app
node_plugin_registry -.->|"extends"| node_validation_core
node_plugin_registry -.->|"extends"| node_backend_app

click node_cli_app "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/app.py"
click node_cli_workspace "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/workspace.py"
click node_cli_mission "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/mission.py"
click node_cli_decompose "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/decompose.py"
click node_cli_plan "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/plan.py"
click node_cli_next "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/next.py"
click node_cli_validate "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/validate.py"
click node_cli_baseline "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/baseline.py"
click node_cli_report "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/report.py"
click node_backend_app "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/main.py"
click node_backend_routes "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/routers/missions.py"
click node_workspace "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/workspace.py"
click node_mission_store "https://github.com/loudiman/mission-forge/blob/main/.missionforge/missions"
click node_schemas "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/models/schemas.py"
click node_schema_validators "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/schemas/validators.py"
click node_validation_core "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/validation_service.py"
click node_parent_validation "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/parent_validation_service.py"
click node_mission_validator "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/mission_validator.py"
click node_baseline_service "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/baseline_service.py"
click node_report_generator "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/report_generator.py"
click node_report_tpl "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/templates/mission_report.md.j2"
click node_plan_logic "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/plan.py"
click node_next_logic "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/next.py"
click node_git_ops "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/git/operations.py"
click node_subprocess_utils "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/utils/subprocess_utils.py"
click node_backend_cache "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/cache/file_cache.py"
click node_plugin_registry "https://github.com/loudiman/mission-forge/blob/main/src/missionforge/plugins/registry.py"

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_cli_app,node_cli_workspace,node_cli_mission,node_cli_decompose,node_cli_plan,node_cli_next,node_cli_validate,node_cli_baseline,node_cli_report,node_backend_app,node_backend_routes toneBlue
class node_validation_core,node_parent_validation,node_mission_validator,node_baseline_service,node_report_generator,node_report_tpl,node_plan_logic,node_next_logic toneAmber
class node_workspace,node_mission_store,node_schemas,node_schema_validators toneMint
class node_git_ops,node_subprocess_utils,node_backend_cache toneRose
class node_plugin_registry toneIndigo
```

## Components

### User surfaces

Primary command-line and HTTP entrypoints.

- [CLI app](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/app.py): Typer entrypoint · Main command-line surface for mission lifecycle operations. · `src/missionforge/cli/app.py`
- [Workspace cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/workspace.py): CLI command · Initializes and manages the mission workspace. · `src/missionforge/cli/commands/workspace.py`
- [Mission cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/mission.py): CLI command · Creates and updates mission definitions. · `src/missionforge/cli/commands/mission.py`
- [Decompose cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/decompose.py): CLI command · Splits a parent mission into scoped sub-missions. · `src/missionforge/cli/commands/decompose.py`
- [Plan cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/plan.py): CLI command · Builds deterministic execution order for sub-missions. · `src/missionforge/cli/commands/plan.py`
- [Next cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/next.py): CLI command · Selects the next executable sub-mission. · `src/missionforge/cli/commands/next.py`
- [Validate cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/validate.py): CLI command · Checks mission and sub-mission correctness. · `src/missionforge/cli/commands/validate.py`
- [Baseline cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/baseline.py): CLI command · Captures implementation evidence for sub-missions. · `src/missionforge/cli/commands/baseline.py`
- [Report cmd](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/report.py): CLI command · Generates the final mission report artifact. · `src/missionforge/cli/commands/report.py`
- [API app](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/main.py): FastAPI app · HTTP façade over mission workspace data. · `src/missionforge/backend/main.py`
- [Mission routes](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/routers/missions.py): API router · Mission endpoints exposed by the backend. · `src/missionforge/backend/routers/missions.py`

### Workflow engine

Mission lifecycle, validation, planning, reporting, and workspace orchestration.

- [Validation core](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/validation_service.py): rules engine · Cross-field and cross-file mission validation. · `src/missionforge/core/validation_service.py`
- [Parent checks](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/parent_validation_service.py): link validation · Validates parent-child relationships and path scoping. · `src/missionforge/core/parent_validation_service.py`
- [Mission validator](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/mission_validator.py): consistency checks · Enforces mission identity, path, and dependency rules. · `src/missionforge/core/mission_validator.py`
- [Baseline service](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/baseline_service.py): evidence capture · Captures per-sub-mission baseline artifacts. · `src/missionforge/core/baseline_service.py`
- [Report generator](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/report_generator.py): Markdown renderer · Assembles the final report from mission evidence and template data. · `src/missionforge/core/report_generator.py`
- [Report template](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/templates/mission_report.md.j2): Jinja2 template · Markdown template for PR-ready mission reporting. · `src/missionforge/templates/mission_report.md.j2`
- [Plan logic](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/plan.py): dependency resolver · Topological ordering and cycle detection for sub-missions. · `src/missionforge/cli/commands/plan.py`
- [Next selection](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/cli/commands/next.py): execution selector · Chooses the next task from the persisted execution plan. · `src/missionforge/cli/commands/next.py`

### Contracts and storage

Shared schemas and the on-disk mission workspace.

- [Workspace](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/core/workspace.py): filesystem boundary · Deterministic on-disk mission store under .missionforge/missions. · `src/missionforge/core/workspace.py`
- [Mission artifacts](https://github.com/loudiman/mission-forge/blob/main/.missionforge/missions): workspace artifacts · Mission.yaml, plan.yaml, report.md, and sub-mission evidence files. · `.missionforge/missions`
- [Schemas](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/models/schemas.py): Pydantic/JSON schema · Structured mission and sub-mission contracts. · `src/missionforge/models/schemas.py`
- [Schema validators](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/schemas/validators.py): json schema rules · JSON-schema and structural validators for mission contracts. · `src/missionforge/schemas/validators.py`

### Execution boundary

Controlled git, subprocess, and API persistence layers.

- [Git ops](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/git/operations.py): git wrapper · Restricted wrapper around git commands. · `src/missionforge/git/operations.py`
- [Subprocess utils](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/utils/subprocess_utils.py): safe execution · Centralized non-shell subprocess execution boundary. · `src/missionforge/utils/subprocess_utils.py`
- [File cache](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/backend/cache/file_cache.py): backend cache · File-backed cache used by the API layer. · `src/missionforge/backend/cache/file_cache.py`

### Extensions

Optional plugin hooks for the core workflow.

- [Plugin registry](https://github.com/loudiman/mission-forge/blob/main/src/missionforge/plugins/registry.py): extension hub · Registers optional commands, validators, formatters, and metrics. · `src/missionforge/plugins/registry.py`

## Connections

- CLI app → Workspace cmd: dispatches · The CLI app exposes workspace lifecycle commands.
- CLI app → Mission cmd: dispatches · The CLI app exposes mission creation and update commands.
- CLI app → Decompose cmd: dispatches · The CLI app exposes decomposition commands.
- CLI app → Plan cmd: dispatches · The CLI app exposes planning commands.
- CLI app → Next cmd: dispatches · The CLI app exposes task-selection commands.
- CLI app → Validate cmd: dispatches · The CLI app exposes validation commands.
- CLI app → Baseline cmd: dispatches · The CLI app exposes baseline-capture commands.
- CLI app → Report cmd: dispatches · The CLI app exposes report-generation commands.
- Workspace cmd → Workspace: initializes · Workspace commands create and manage the on-disk mission root.
- Mission cmd → Schemas: writes · Mission commands serialize validated mission contracts.
- Mission cmd → Schema validators: checks · Mission commands validate structured inputs before persisting.
- Decompose cmd → Validation core: checks · Decomposition is constrained by validation and scoping rules.
- Decompose cmd → Workspace: reads/writes · Decomposition operates on workspace mission artifacts.
- Plan cmd → Plan logic: drives · Planning command builds deterministic execution order.
- Plan cmd → Workspace: persists · Planning writes plan.yaml back into the workspace.
- Next cmd → Next selection: uses · Next command selects the next actionable sub-mission.
- Next cmd → Workspace: reads · Next command reads the persisted plan and mission state.
- Validate cmd → Validation core: runs · Validation command invokes the core validation pipeline.
- Baseline cmd → Baseline service: captures · Baseline command records implementation evidence.
- Baseline cmd → Workspace: writes · Baseline artifacts are written into the mission workspace.
- Report cmd → Report generator: renders · Report command produces the final mission report.
- Report generator → Report template: uses · Report generation uses the Markdown Jinja2 template.
- Report generator → Workspace: reads · Report generation consumes mission artifacts and evidence.
- Validation core → Mission validator: includes · Core validation aggregates mission-level rules.
- Validation core → Parent checks: includes · Core validation aggregates parent-child checks.
- Validation core → Schemas: relies on · Validation is anchored in the shared mission schema contracts.
- Mission validator → Schema validators: enforces · Mission validator applies structural schema rules.
- Mission validator → Workspace: scopes · Validator checks workspace paths, IDs, and dependencies.
- Parent checks → Workspace: scopes · Parent validation checks allowed and forbidden paths in the workspace.
- Plan logic → Workspace: reads/writes · Planning resolves dependencies from mission files and persists plan data.
- Next selection → Workspace: reads · Next selection consumes the stored plan and mission artifacts.
- Baseline service → Workspace: reads · Baseline capture consumes per-mission artifacts.
- Report generator → Git ops: references · Reporting can summarize git-backed implementation state.
- Git ops → Subprocess utils: executes through · Git commands are run through the safe subprocess boundary.
- API app → Mission routes: mounts · The FastAPI app assembles mission routes.
- Mission routes → Workspace: serves · API responses are derived from workspace mission artifacts.
- Mission routes → File cache: uses · Routes leverage file-backed caching for API data.
- Mission routes → Schemas: serializes · API response models align with shared mission schemas.
- Mission routes → Validation core: shares rules · Backend relies on the same validation logic as the CLI.
- Plugin registry → CLI app: extends · Plugins can add or alter command surface behavior.
- Plugin registry → Validation core: extends · Plugins can contribute validators and formatters.
- Plugin registry → API app: extends · Plugins can contribute backend-facing metrics or behaviors.
