Skip to content

FCC for Data Architects

Welcome to the For Data Architects section of the FCC Agent Team Framework documentation. This section is written for the people who decide how data moves through FCC: how entities are modelled, how vocabularies are reconciled across ecosystem projects, how federated identities resolve, and how lineage is captured end-to-end.

If you are here to integrate an application, start with For Developers. If you are deploying FCC at scale, start with For Operators. If you are evaluating compliance posture, start with For Auditors. This section assumes you have already completed the Getting Started walk-through and can run fcc validate --personas on a local checkout.

Who This Section Is For

Your role

This section assumes you are responsible for one or more of the following:

  • Designing the object model that FCC and its sister projects share
  • Curating vocabulary mappings between FCC and external ontologies (CTO, AOME, FIBO, HL7 FHIR, ACORD, DCAT, CIM)
  • Standing up federation topologies across multiple ecosystem projects and namespaces
  • Defining per-persona data_flow frontmatter to close quality gate QG-DGS-001
  • Producing data lineage evidence for audit and compliance review

If any of those fit, the four guides in this section will take you from reading the FCC object model to extending it safely for your organisation.

Overview of Data-Architect-Specific Content

Guide Primary Focus When to Read
Object Model Overview Protocol-based Repository[T] + ModelFacade + EvolutionStage Before designing a custom facade
Vocabulary Mappings 95 packaged cross-vocabulary mappings across 20 YAML files Before wiring a new ecosystem project
Federation Patterns EntityResolver + NamespaceRegistry + cross-project resolution Before onboarding a second namespace
Data Governance data_flow persona frontmatter + quality gate QG-DGS-001 Before running a compliance audit

Each guide links back to the source under src/fcc/objectmodel/, src/fcc/federation/, and src/fcc/data/objectmodel/.

Quick-Start for Data Architects

Adopting the FCC object model is a five-step process. Most data architects complete it in one working week.

Step 1: Read the Protocol Contracts

Open src/fcc/objectmodel/base.py and confirm you are comfortable with typing.Protocol and runtime_checkable. The DomainEntity and RepositoryProtocol[T] contracts are structural — any frozen dataclass with an id and a to_dict() satisfies them, without inheritance.

Step 2: Inventory Your Source Vocabulary

List the entities, attributes, and relationships in your source vocabulary. For every entity you expect to federate, capture the identifier, the human-readable name, and at least one FCC anchor (usually a persona, action, or workflow).

Step 3: Draft a Repository

Use ExampleRepository at src/fcc/objectmodel/examples.py as a reference implementation. Your repository needs add, get_by_id, get_all, count, __iter__, __len__, __contains__. That is it.

Step 4: Wire a Facade

Subclass ModelFacade and implement stats(), search(), and get_full(). A facade is how your repositories are exposed to the rest of FCC — simulations, CLI dashboards, and RAG pipelines all consume the facade, not the repository directly.

Step 5: Register a Namespace and Map Vocabularies

Add a namespace to src/fcc/data/federation/namespace_registry.yaml and draft vocabulary mappings in src/fcc/data/objectmodel/<your-project>_vocabulary_mappings.yaml following the pattern in Vocabulary Mappings.

Decision Tree: If You Need X, Go To Y

Use this tree to pick your first guide.

flowchart TD
    Start([What do you need most?]) --> Kind{What kind of work?}
    Kind -->|Design a new facade| OM[Object Model Overview]
    Kind -->|Map an external vocabulary| VM[Vocabulary Mappings]
    Kind -->|Connect two ecosystem projects| FP[Federation Patterns]
    Kind -->|Close QG-DGS-001| DG[Data Governance]

    classDef start fill:#e1f5ff,stroke:#0277bd,stroke-width:2px;
    classDef decision fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef result fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    class Start start;
    class Kind decision;
    class OM,VM,FP,DG result;

Data Architect Maturity Model

Stage Signals Typical Duration Next Investment
Exploring Reading the object model, no custom facade 1-2 weeks Draft a minimal ExampleRepository clone
Piloting 1 facade, 1 vocabulary mapping file, manual audit 2-6 weeks Wire EntityResolver across 2 namespaces
Operating 3+ facades, 5+ mapping files, automated data_flow 2-6 months Federated KG, change-tracking
Scaling Multi-project federation, cross-ecosystem lineage 6+ months Evidence graph + cross-regulation reporting

v1.4.x What's New for Data Architects

v1.4.x adds two changes you should know about. First, the Zachman 6×6 cross-cut (v1.4.1) classifies every persona into one of 36 cells; for data architects this becomes a second dimension to organise persona data_flow frontmatter (now also tied to cell affinity). Second, the ice_ext element-mapping YAML is vendored into src/fcc/data/objectmodel/, joining the 175+ existing vocabulary mappings, and ice_ext is promoted to Tier-1-Strict POLARIS in the ecosystem registry. Both changes are downstream-visible via the VDS SHA-256 drift gate.

See Also