4+1 Development View¶

The Development View captures what FCC looks like to a developer. It answers: which subpackages exist, which ones import from which, and what happens between pip install -e . and a functioning CLI. Where the Logical View names the classes and the Process View traces their interactions, this page is the map of the repository on disk.

The three diagrams below show the package layout of src/fcc/, the allowed dependency layers, and the build pipeline from source to runnable CLI.

Package layout¶

src/fcc/ is a flat-ish namespace package with 22 top-level subpackages in v1.3.7. Each subpackage is a single responsibility: the personas/ package knows nothing about protocols, the protocols/ package holds no compliance logic, and so on. Cross-cutting concerns (events, tracing, metrics) live in their own packages so any other package may import them.

Figure 1 shows the top-level subpackage map with the primary dependency arrows.

flowchart TD
    subgraph Core["Core contracts"]
        personas[personas/]
        workflow[workflow/]
        scenarios[scenarios/]
    end

    subgraph Runtime["Runtime"]
        simulation[simulation/]
        protocols[protocols/]
        collaboration[collaboration/]
    end

    subgraph CrossCutting["Cross-cutting"]
        messaging[messaging/]
        observability[observability/]
    end

    subgraph Capabilities["Capabilities"]
        search[search/]
        knowledge[knowledge/]
        rag[rag/]
        federation[federation/]
        objectmodel[objectmodel/]
    end

    subgraph Governance["Governance and evaluation"]
        governance[governance/]
        compliance[compliance/]
        evaluation[evaluation/]
    end

    subgraph UserFacing["User-facing"]
        scaffold[scaffold/]
        dashboard[dashboard/]
        demos[demos/]
        tutorials[tutorials/]
        audit[audit/ -- v1.3.6]
        admin[admin/ -- v1.3.6]
    end

    personas --> workflow
    workflow --> scenarios
    scenarios --> simulation
    simulation --> protocols
    simulation --> collaboration
    messaging --> simulation
    messaging --> compliance
    observability --> simulation
    objectmodel --> federation
    search --> rag
    knowledge --> rag
    governance --> compliance
    evaluation --> compliance
    personas --> scaffold
    personas --> dashboard
    personas --> demos
    personas --> audit
    personas --> admin
    audit --> compliance
    admin --> dashboard

The v1.3.6-new audit/ and admin/ packages consume the vendored ecosystem registries at src/fcc/data/ecosystem/ directly, which is why they sit at the outer layer: they aggregate lower layers into operator-facing surfaces.

Dependency layers¶

The subpackages above fall into four dependency tiers. Core contracts sit at the bottom; cross-cutting concerns and capabilities sit in the middle; user-facing tools sit on top. No tier imports upward.

Figure 2 makes the layer invariant explicit and shows where audit/ and admin/ land.

@startuml
package "Tier 0 — Core contracts" as T0 {
  [personas]
  [workflow]
  [scenarios]
}

package "Tier 1 — Runtime" as T1 {
  [simulation]
  [action_engine]
}

package "Tier 2 — Cross-cutting + Capabilities" as T2 {
  [messaging]
  [observability]
  [search]
  [knowledge]
  [rag]
  [federation]
  [objectmodel]
  [governance]
  [compliance]
  [evaluation]
}

package "Tier 3 — Protocols + User-facing" as T3 {
  [protocols]
  [collaboration]
  [scaffold]
  [dashboard]
  [demos]
  [tutorials]
  [audit]
  [admin]
}

T1 ..> T0 : depends on
T2 ..> T0 : depends on
T2 ..> T1 : depends on
T3 ..> T0 : depends on
T3 ..> T1 : depends on
T3 ..> T2 : depends on

note right of T3
  audit/ and admin/ (v1.3.6+) are top-level
  consumers of the vendored ecosystem
  registries under src/fcc/data/ecosystem/
end note
@enduml

Violations of this layering fail CI before they reach main. The tier boundary is deliberately wide at Tier 2 so that capabilities like RAG or semantic search can share cross-cutting messaging and observability without creating a cycle with governance.

Build pipeline¶

From a fresh checkout, pip install -e . runs setuptools which reads pyproject.toml, wires entry points, and installs the wheel metadata. At import time PersonaRegistry.load_directory() scans src/fcc/data/personas/ for YAML files and PluginRegistry.load_all() enumerates the fcc.plugins entry-point group declared by installed packages. The CLI bootstraps from there.

Figure 3 traces the pipeline from source to fcc --help.

flowchart LR
    A[pip install -e .] --> B[setuptools reads pyproject.toml]
    B --> C[Install wheel metadata]
    C --> D[Register entry points]
    D --> E[import fcc]
    E --> F[PersonaRegistry.load_directory]
    F --> G[WorkflowActionRegistry.load]
    G --> H[PluginRegistry.load_all via entry_points]
    H --> I[VocabularyProviderPlugin probes]
    I --> J[click CLI bootstrap]
    J --> K[fcc --help ready]

The whole boot sequence is typically under 400 ms on a warm cache, which is fast enough that the CLI feels like a native tool rather than a Python application.

Dependency rules in practice¶

Always allowed: importing from Tier 0 (personas, workflow, scenarios) from any other tier; importing from messaging/ or observability/ from anywhere; importing from fcc._resources for path resolution instead of computing paths from __file__.

Conditionally allowed: Tier 2 packages may import from each other as long as the resulting import graph remains acyclic — for instance, rag/ imports from both search/ and knowledge/, which is fine because neither imports from rag/.

Never allowed: any Tier 0 module importing from Tier 1, 2, or 3; any direct Path(__file__) manipulation; any import of a protocol or user-facing subpackage from a compliance or evaluation module.

The entry-point section of pyproject.toml is the integration contract: plugins and vocabulary providers declare themselves under fcc.plugins and fcc.vocabulary_providers respectively, and the PluginRegistry honours only those entry points. That means a third party can ship an FCC plugin without modifying this repository at all.

4+1 Development View¶

Package layout¶

Dependency layers¶

Build pipeline¶

Dependency rules in practice¶

See also¶