Architecture¶
This is the structured-architecture entry point for the FCC framework. The material here complements the narrative chapters in the Guidebook, the persona-centric Specification, and the developer-facing Plugin Architecture doc. The goal is to make every load-bearing internal contract — class hierarchy, message sequence, data flow, and audience-to-subsystem mapping — visible at a glance.
If you are looking for how to use a subsystem, the audience tiers under For Beginners, For Educators, For Scientists, and For Professionals are organised around that question. The Architecture tree, by contrast, is organised around what the structure looks like.
What's here¶
| Section | Contents | Audience |
|---|---|---|
| Site map | A single mermaid graph of every documentation section, plus the 147 personas grouped by pack | Everyone |
| API boundaries | The capability matrix of the six external interfaces (CLI, Python SDK, WebSocket, REST, MCP, A2A) and their per-feature support | Integrators |
| Plugin boundaries | One section per of the 11 plugin types: ABC signature, lifecycle, minimal example | Plugin authors |
| Federated vs individual | Side-by-side comparison of project-local object models and knowledge graphs against the federated forms that span 21 namespaces | Architects |
| Class diagrams | 5 Mermaid classDiagram documents — persona-spec hierarchy, plugin hierarchy, object-model variants, knowledge-graph variants, collaboration engine |
Maintainers |
| Sequence diagrams | 6 Mermaid sequenceDiagram documents tracing the load-bearing flows: Find → Create → Critique, federation entity resolution, compliance audit, vocabulary loading, event bus pub/sub, RAG retrieval |
Maintainers |
| Data-flow diagrams | 4 DFDs — scenario-to-trace, RAG document pipeline, compliance evidence graph, cross-project entity resolution | Maintainers |
| Use-case diagrams | 4 audience-scoped views mapping users to subsystems | Onboarding leads |
What this tree is not¶
It is not a substitute for reading the source. Every diagram cites the
specific src/fcc/ file and line range that backed it; the diagrams are
abstractions of working code, and code is the authority.
It is not stable in the sense of being version-locked. When a class signature
changes or a new plugin type ships, the corresponding diagram should change
too. The convention is: if you alter a public dataclass field or an ABC
method, update the matching diagram in the same PR. The Quarto crossref IDs
({#fig-class-diagrams_persona-spec-hierarchy-1} and similar) make the
references easy to find.
Conventions¶
All diagrams follow the publications/FIGURES.md
authoring rulebook: each one carries an HTML-comment fig-meta sentinel
above the Mermaid block (id, caption, intro marker), an HTML-comment
fig-followup immediately after, plus a one-sentence intro paragraph above
and a 1–2 sentence follow-up paragraph below. Captions surface in the
List of Figures generated by Quarto across PDF, DOCX, EPUB, and HTML.
Mermaid syntax is pymdownx.superfences-rendered on the MkDocs site and
pre-rendered to SVG/PNG by publications/scripts/render_mermaid.py for
the publication artifacts. The same source markdown supports both paths.