Skip to content

System Architecture

The FCC Agent Team Framework follows a layered architecture where declarative data files drive Python models, which in turn power simulation, documentation generation, and governance scoring. There are no runtime databases -- everything is file-based, version-controlled, and deterministic.

Data Flow: YAML to Simulation

The primary data flow transforms persona definitions into executable simulations:

graph LR
    subgraph Data Layer
        YAML["Persona YAML<br/>data/personas/"]
        WF["Workflow JSON<br/>data/workflows/"]
        SCEN["Scenarios<br/>data/scenarios/"]
    end

    subgraph Model Layer
        REG["PersonaRegistry"]
        GRAPH["WorkflowGraph"]
        SMOD["ScenarioModel"]
    end

    subgraph Engine Layer
        SIM["SimulationEngine"]
        AI["AIClient"]
        PROMPT["PersonaPrompts"]
    end

    subgraph Output Layer
        TRACE["Traces JSON"]
    end

    YAML --> REG
    WF --> GRAPH
    SCEN --> SMOD

    REG --> SIM
    GRAPH --> SIM
    SMOD --> SIM
    REG --> PROMPT
    AI --> SIM
    PROMPT --> SIM

    SIM --> TRACE
  1. Data Layer -- YAML persona definitions and JSON workflow graphs are loaded from data/.
  2. Model Layer -- PersonaRegistry loads all persona specs, WorkflowGraph builds adjacency lists, and scenario models define simulation parameters.
  3. Engine Layer -- The simulation engine traverses the workflow graph, using persona-aware prompts and either a mock or real AI client.
  4. Output Layer -- Traces are written as JSON, capturing every step, message, and AI call.

Data Flow: Registry to Documentation

The docs-as-code pipeline transforms persona registries into publishable documentation:

graph LR
    subgraph Data Layer
        YAML2["Persona YAML"]
        TMPL["Jinja2 Templates<br/>src/fcc/templates/docs/"]
        TOPICS["Topic YAML<br/>data/docs/"]
    end

    subgraph Generator
        REG2["PersonaRegistry"]
        DGEN["DocGenerator"]
    end

    subgraph Output
        DOCS["1,348 Doc Files<br/>tutorials, prompts, workflows"]
        SITE["SITEMAP.md"]
    end

    YAML2 --> REG2
    REG2 --> DGEN
    TMPL --> DGEN
    TOPICS --> DGEN

    DGEN --> DOCS
    DGEN --> SITE

The DocGenerator produces 56 files per persona (tutorials, prompts, workflows) plus cross-reference pages and a sitemap. With 24 personas, this generates 1,348 documentation files.

Module Walkthrough

src/fcc/personas/

The personas module is the foundation of the framework.

File Key Classes Purpose
models.py PersonaSpec, RISCEARSpec, DiscernmentTrait, DesignTargetFactor, RatingDimensions, Deliverable, Collaboration Frozen dataclasses defining the complete persona data model
registry.py PersonaRegistry Multi-file YAML loading, lookup by ID/category, champion filtering, registry merging
dimensions.py DimensionAttribute, PersonaDimension, PersonaDimensionProfile, DimensionRegistry 56-dimension profiling system with category-based organization
cross_reference.py CrossReferenceEntry, CrossReferenceMatrix Queryable persona-to-persona interaction map (upstream, downstream, peers, by_type)

Design decisions:

  • All model classes are frozen=True dataclasses, ensuring immutability after construction.
  • No Pydantic dependency -- validation is handled through explicit from_dict classmethods.
  • The registry supports merging, allowing downstream projects to add custom personas.

src/fcc/workflow/

File Key Classes Purpose
models.py WorkflowNode, WorkflowEdge, WorkflowMeta Data model for graph nodes, edges, and metadata
graph.py WorkflowGraph In-memory graph with adjacency lists, BFS traversal, topological sort, and query methods

Design decisions:

  • Graphs are loaded from JSON, validated against data/schemas/workflow.schema.json.
  • Topological sort excludes feedback edges to break cycles.
  • BFS follows all edges for simulation traversal.

src/fcc/simulation/

File Key Classes Purpose
engine.py SimulationEngine Deterministic mock simulation with step tracking
ai_engine.py AISimulationEngine AI-powered simulation with LLM calls at each node
ai_client.py AIClient, AIProvider Abstraction over Anthropic and OpenAI APIs with mock provider
prompts.py Prompt functions Persona-aware system prompt generation from R.I.S.C.E.A.R. specs
messages.py SimulationMessage Typed message passing between personas
traces.py SimulationTrace Serializable trace records for simulation audit

Design decisions:

  • Two engine modes: deterministic (mock) for testing, AI-powered for production.
  • Persona-aware prompts inject the full R.I.S.C.E.A.R. specification into the system prompt.
  • Traces are JSON-serializable for post-simulation analysis.

src/fcc/scenarios/

File Key Classes Purpose
models.py Scenario, ScenarioStep Scenario definitions with steps, expected outcomes, and validation rules
loader.py ScenarioLoader Load scenarios from JSON files
validators.py FCCValidator Dynamic validation using FCCValidator.from_registry() for registry-aware checks

src/fcc/scaffold/

File Key Classes Purpose
cli.py Click commands The fcc CLI: init, add-persona, validate, simulate, generate-docs, validate-docs, sitemap
doc_generator.py DocGenerator Jinja2-based docs-as-code generator producing 56 files per persona
engine.py TemplateEngine Jinja2 template rendering with persona context
project.py init_project, add_persona Project scaffolding and persona addition
config.py FCCConfig Project configuration model

src/fcc/governance/

File Key Classes Purpose
quality_gates.py QualityGate, GateResult Gate definitions, threshold evaluation, check execution
tags.py CapabilityTag, TagRegistry Three-level tag taxonomy, coverage scoring
compliance.py ComplianceScorer Aggregate governance scoring across gates and tags

Schema Validation

JSON Schema files under data/schemas/ validate all data files:

  • persona.schema.json -- Validates persona YAML structure
  • workflow.schema.json -- Validates workflow graph JSON
  • cross_reference.schema.json -- Validates cross-reference YAML
  • traces.schema.json -- Validates simulation trace output

The WorkflowGraph.from_json_validated() method demonstrates schema validation at load time.