Skip to content

4+1 Reference for Architects

FCC's architecture documentation follows Philippe Kruchten's 4+1 view model. Five views live under docs/architecture/uml/, each answering a different structural question. This page is the architect's pointer into that tree: which view to consult for which task, with the cross-references already wired.

The five views at a glance

View Question it answers Primary artifact
Logical What does FCC know? logical-view.md
Process How does FCC run? process-view.md
Development How is FCC packaged? development-view.md
Physical Where does FCC deploy? physical-view.md
Scenarios Does the model actually work? scenarios-view.md

Which view for which task

Task — evaluating the persona catalog

Start with the Logical View. The three class diagrams there capture the PersonaSpec / RISCEARSpec composition, the 11-type plugin taxonomy, and the compliance + governance stack. If you are deciding whether FCC's persona abstraction matches your team topology, this is the right starting point.

Task — planning a production deployment

Start with the Physical View. It shows the Docker images (four of them), the Helm chart layout (charts/fcc/), the kind-based smoke test topology, and the ports claimed at each tier. For Tier 1 and Tier 2 integrations this is the page your SRE will want open.

Task — reading the package boundaries

Start with the Development View. The three diagrams there show the 22 top-level subpackages under src/fcc/, their allowed dependency arrows, and the build pipeline from pip install -e . to a working CLI. Read this page before you fork, before you embed, and before you re-implement.

Task — tracing a single workflow

Start with the Process View. It shows what happens between fcc run and a completed trace — the engine, event bus, and protocol servers as runtime objects. Pair this with the sequence diagrams for specific flows such as compliance audit, collaboration session, or federation handshake.

Task — validating the architecture against a use case

Start with the Scenarios View (the +1). It walks the four views above through concrete use cases (agent developer onboards, compliance officer audits, patent counsel generates model cards). If you cannot trace your use case end-to-end through the four views, the Scenarios View is where you discover the gap.

How the views cross-reference

The five views cite each other constantly. The Logical View names the classes; the Process View shows them at runtime; the Development View shows them on disk; the Physical View shows them on infrastructure; and the Scenarios View stitches them back together under a use case. An architect's first pass is usually Logical → Development → Physical; the second pass (once you have committed to an integration) is Process → Scenarios.

Pairing 4+1 with C4

FCC ships both notations. The 4+1 UML views live under docs/architecture/uml/; the single Level 1 C4 diagram lives at context-diagram.md. The two are complementary: the C4 diagram says who FCC talks to, the 4+1 views say how FCC is structured internally. An architect should have both open in adjacent tabs during the evaluation.

Additional architecture artifacts

Beyond the five 4+1 views and the C4 context diagram, FCC ships:

  • Class diagrams — docs/architecture/class-diagrams/ (five deep-dives into specific subsystem class models).
  • Sequence diagrams — docs/architecture/sequence-diagrams/ (six runtime flows).
  • Data-flow diagrams — docs/architecture/data-flow-diagrams/ (four DFDs including the compliance evidence graph).
  • Use-case diagrams — docs/architecture/use-case-diagrams/ (four audience-specific use-case maps).
  • ADRs — docs/decisions/ (five adopted architecture decision records).
  • Sitemap — sitemap.md (browsable index of the full architecture tree).