Skip to content

System Context for Architects

This page is a short-form orientation to FCC's system context. The authoritative artifact is docs/architecture/context-diagram.md, a C4 Level 1 diagram introduced in v1.3.7 that enumerates every actor, neighbour, and integration surface in the 19-project ecosystem. This page distils the information that is most relevant when an architect is doing the first-pass evaluation: who talks to FCC, across which surface, and at what trust tier.

The 19-project ecosystem at a glance

FCC sits between two upstream authorities, seven direct consumers, two L2 JV libraries, one visualization partner, and ten constellation verticals. The full map is in docs/architecture/context-diagram.md; the summary below is enough for an initial decision.

Group Projects Trust tier Surface
Upstream authorities NEXUS, PHOENIX (authority) Vendored YAML, quality gates
Direct consumers PAOM, AOME, CONSTEL, Distiller, CTO Tier 1/2/3 MCP, A2A, plugin
JV libraries Athenium, Mnemosyne Tier 2 fcc.vocabulary_providers entry points
Visualization partner AURORA Tier 2 WebSocket :8765
Constellation verticals Ophiuchus, Serpens, Libra, Crater, Scutum, Norma, Pyxis, Vela, Columba, Caelum Tier 3 Plugin wheels

The canonical list lives at docs/ecosystem/alignment-status.md; it is updated per release and is the source of truth when the table above drifts.

Trust tiers

Trust tier is the single most load-bearing architectural concept when integrating with FCC. It determines what breaks when either side ships a new version, and therefore drives your CI gating, your deployment cadence, and your on-call surface.

Tier 1 — Strict. Your CI breaks when FCC's contracts drift. AOME / CRUCIBLE and CONSTEL / PRISM are the two current Tier 1 consumers; both pin the FCC version explicitly and run contract tests against the live FCC schemas. Choose this tier when FCC-level bugs are production-critical for your application.

Tier 2 — Active. Your project is version-pinned to FCC but survives most FCC releases without changes. PAOM, PHOENIX, AURORA, Distiller, Athenium, and Mnemosyne all live here. Choose this tier when you are actively integrating, shipping production code against FCC, and willing to track releases.

Tier 3 — Minimal. FCC is optional in your runtime; your application still works without it installed. CTO and the ten constellation verticals live here. Choose this tier when FCC is one of several optional ecosystem integrations.

The eight integration surfaces

FCC exposes eight distinct integration contracts. Each is a contract boundary, and each is owned by a specific entry in docs/decisions/ when it changes.

Surface Purpose Source
fcc.plugins entry points Plugin discovery at import time pyproject.toml, src/fcc/plugins/registry.py
fcc.vocabulary_providers entry points Cross-project entity resolution (v1.2.1+) src/fcc/plugins/base.py:226
MCP (port 9001) JSON-RPC tools for LLM clients src/fcc/protocols/mcp/server.py
A2A (port 9002) Bidirectional agent messaging src/fcc/protocols/a2a/server.py
WebSocket bridge (port 8765) Event stream push fcc protocol ws-bridge
Vendored YAML Port + ecosystem registries src/fcc/data/ecosystem/*.yaml
ObjectModel bridge CTO object-model adapter src/fcc/objectmodel/cto_bridge.py
Python SDK + CLI Everything else src/fcc/scaffold/cli.py

When deciding which surfaces to adopt, read the Decision Checklist — it walks through the twelve questions that pin down the minimum viable integration surface for your use case.

Data flow — Level 0

At the system boundary FCC has three inbound flows (plugin wheels, vendored YAML, scenario configs) and four outbound flows (WebSocket events, MCP responses, A2A responses, and written artifacts under /out and /publications). The full DFD is at the bottom of context-diagram.md; it is the starting point for privacy, audit, and network-zone placement decisions.

Version cadence and the moving picture

FCC follows a 4-part PEP 440 scheme (MAJOR.MINOR.PATCH.HOTFIX). The current v1.3.5.x series closes in v1.3.5.3 (2026-04-13); v1.4.0 introduces the ecosystem pivot that promotes the ten constellation verticals from internal plugin wheels to independent GitHub repos. Architectural evaluations started today should target v1.4.0 or later unless you have a specific reason to pin to v1.3.x.