MCAF: Architecture Overview

MCAF: Architecture Overview

Output

• docs/​Architecture/​Overview.md (create or update)

Architecture Thinking (keep it a map)

This doc is the global map: boundaries, modules, and dependency rules.

• Keep it lean and structural:
  • modules/​boundaries + responsibility + dependency direction
  • Mermaid diagrams are the primary context:
    • system/​module map (blocks + dependency direction)
    • interfaces/​contracts map (how modules talk)
    • key classes/​types map (high-signal only; not exhaustive)
• Treat it as the main “start here” card for humans and AI agents:
  • diagram elements must use real names (no placeholders)
  • every diagram element must have an explicit reference link (docs/​code) so an agent can navigate without repo-wide scanning
  • keep diagrams readable; if a diagram becomes “spaghetti”, split by boundary and link out
• Keep behaviour out of the overview:
  • feature flows live in docs/​Features/​*
  • decision-specific diagrams/​invariants live in docs/​ADR/​*
• Anti-“AI slop” rule: never invent components/​services/​DBs — only document what exists (or what this change will explicitly add).

Workflow

1. Open docs/​Architecture/​Overview.md if it exists; otherwise start from docs/​templates/​Architecture-Template.md.
   • Ensure it contains a short ## Scoping (read first) section (this is how we prevent “scan everything” behaviour).
2. Identify the real top-level boundaries:
   • entry points (HTTP/​API, CLI, UI, jobs, events)
   • modules/​layers (group by folders/​namespaces, not individual files)
   • external dependencies (only those that actually exist)
3. Fill the Summary so a new engineer can orient in ~1 minute.
4. Maintain the Mermaid diagrams (the map people and agents start from):
   • system/​module map: keep it small (roughly 8–15 nodes), label arrows (calls/​events/​reads/​writes)
   • interfaces/​contracts map: show ports/​interfaces, APIs, events, queues, file formats (only what exists)
   • key classes/​types map: capture the main types that matter across modules (avoid inventories)
   • don’t invent DB/​queues/​services/​modules that aren’t present
5. Fill the module index:
   • one row per diagram node (not every internal module/​class)
   • responsibilities and “depends on” must be concrete
   • prefer a short navigation list with links over big tables/​inventories
6. Write explicit dependency rules:
   • what is allowed
   • what is forbidden
   • how integration happens (sync / async / shared lib)
7. Add a short “Key decisions (ADRs)” section:
   • link to the ADRs that define boundaries, dependencies, and major cross-cutting patterns
   • keep it link-based (no detailed flows here)
8. Link out to deeper docs:
   • ADRs for key decisions
   • Features for behaviour details
   • Testing/​Development for how to run and verify

Guardrails

• Do not list every file/​class. This is a map, not an inventory (key classes/​types only).
• Keep the document stable: update it when boundaries or interactions change.