API Boundaries¶

The FCC framework exposes six external interfaces, each with a different surface area, transport, and intended consumer. This page lays out which capability is reachable through which interface so that integrators can pick the right one without trial and error. Each interface is documented in detail elsewhere; this page is the matrix.

The diagram below contrasts the six interfaces by transport, default process model, and authentication assumption.

graph LR
    subgraph CONSUMERS["Consumers"]
        SH[Shell user]
        PY[Python client]
        BR[Browser app]
        RE[REST client]
        AG[External AI agent]
        OR[Orchestrator]
    end
    subgraph INTERFACES["FCC interfaces"]
        CLI["fcc CLI<br/>(click)"]
        SDK["Python SDK<br/>(import fcc)"]
        WS["WebSocket bridge<br/>(ws://:8765/ws/events)"]
        REST["REST endpoints<br/>(FastAPI)"]
        MCP["MCP server<br/>(model context protocol)"]
        A2A["A2A bridge<br/>(google-adk)"]
    end
    subgraph CORE["src/fcc/ subsystems"]
        SC[Scaffold + DocGen]
        SI[Simulation engine]
        EB[Event bus]
        FE[Federation]
        CO[Compliance + Audit]
        KG[Knowledge graph + RAG]
    end

    SH --> CLI
    PY --> SDK
    BR --> WS
    RE --> REST
    AG --> MCP
    OR --> A2A

    CLI --> SC
    CLI --> SI
    SDK --> SI
    SDK --> EB
    SDK --> FE
    SDK --> CO
    SDK --> KG
    WS --> EB
    REST --> SI
    REST --> FE
    MCP --> SI
    MCP --> KG
    A2A --> SI
    A2A --> CO

The same idea reappears in the capability matrix below: each row is a subsystem, each column an interface, and the cells indicate whether that combination is supported (✓), partial (◐), or out of scope (—).

Capability matrix¶

Subsystem	CLI	SDK	WebSocket	REST	MCP	A2A
Persona registry read	✓	✓	—	✓	✓	✓
Scenario load + run	✓	✓	◐ stream	✓	✓	✓
Simulation traces	✓	✓	✓ live	✓	✓	✓
Event bus pub/sub	—	✓	✓ live	—	—	—
Plugin discovery	✓	✓	—	◐ list	—	—
Vocabulary mappings	✓	✓	—	✓	—	—
Federation resolve	✓	✓	—	✓	✓	—
Compliance audit	✓	✓	—	✓	—	—
Knowledge graph queries	✓	✓	—	✓	✓	—
RAG retrieval	✓	✓	—	✓	✓	✓
Collaboration session	—	✓	✓ live	✓	—	—
Docs + scaffold generation	✓	✓	—	—	—	—
Helm/Docker deployment ops	✓	—	—	—	—	—

Legend: ✓ = supported via the interface's primary methods; ◐ = partial, e.g. only listing or only one direction; — = intentionally out of scope.

Interface summaries¶

CLI (`fcc …`)¶

Built on click. Source: src/fcc/scaffold/cli.py. Subcommands include init, add-persona, validate, generate-docs, validate-docs, sitemap, collab, dashboard, benchmark, model-card, compliance-audit, scaffold-vertical-project. The CLI is the canonical deployment-ops entry point — Helm + Docker tasks live here, not in the SDK.

Python SDK (`import fcc`)¶

Direct dataclass + class access. The SDK is the superset; everything else is a thin wrapper. New features land here first. Subsystem entry points: fcc.personas, fcc.workflow, fcc.simulation, fcc.scenarios, fcc.protocols, fcc.messaging, fcc.observability, fcc.collaboration, fcc.plugins, fcc.governance, fcc.objectmodel, fcc.search, fcc.knowledge, fcc.rag, fcc.federation, fcc.demos, fcc.evaluation, fcc.compliance. See src/fcc/__init__.py for the public re-export surface.

WebSocket bridge (`ws://localhost:8765/ws/events`)¶

Source: src/fcc/protocols/ws_bridge.py, packaged as the fcc protocol ws-bridge CLI command and as the Docker docker/Dockerfile.backend ENTRYPOINT. The bridge serves the React frontend's live event stream and any other subscriber that wants real-time event-bus access without going through the SDK. Health is exposed on the same port via the websockets process_request hook.

REST (FastAPI)¶

Source: src/fcc/protocols/rest/. Auto-generated OpenAPI at /docs. Intended for synchronous service-to-service calls. The REST surface is deliberately a subset of the SDK; long-running or streaming workloads should use the WebSocket bridge or A2A.

MCP (Model Context Protocol)¶

Source: src/fcc/protocols/mcp/. Lets external AI agents query FCC's persona registry, knowledge graph, and RAG pipeline as tools. The MCP server publishes a fixed tool catalog rather than the full SDK so that agent-side context windows stay manageable.

A2A (Agent-to-Agent)¶

Source: src/fcc/protocols/a2a/. Built on google-adk. Allows external ADK orchestrators to dispatch FCC simulations and ingest results. The A2A surface is narrower than MCP — only simulation, compliance, and RAG — because cross-orchestrator coordination needs a small contract.

Versioning¶

All six interfaces follow the same SemVer guarantees as the package:

Major: a method removal or signature change.
Minor: new methods, new endpoints, new MCP tools.
Patch: bug fixes only; no contract changes.

Every interface is gated by the same pytest -k contract suite under tests/test_protocols_*.py and tests/test_cli_*.py, so a contract drift in one interface fails CI.