Skip to content

Chapter 28: The Architect Playbook

New in v1.3.10. Where the developer journey focused on the individual engineer, this chapter is written for the person making platform-level decisions: should FCC own this workflow, or should an existing system own it? Should we federate or unify? How do we wire quality gates into CI without blocking everyone?

The architect's frame

An architect reads FCC's 102 core personas, 45 vertical personas, 11 plugin types, 7 workflow graphs, 21 federated namespaces, 256+ compliance requirements, and asks: "which of these do I actually need?" The honest answer is "probably 8-12 personas, 2-3 plugin types, one or two workflows, and maybe one vertical pack."

This chapter is the decision playbook for making those calls.

The four architect decisions

Every FCC adoption decomposes into four decisions, made roughly in the order below. Once they are settled, detailed engineering work falls out of the answers.

flowchart TD
    D1[Decision 1<br/>Scope: which workflows do we own?] --> D2[Decision 2<br/>Topology: monolith, star, or mesh?]
    D2 --> D3[Decision 3<br/>Governance: gates, constitutions, audit]
    D3 --> D4[Decision 4<br/>Evolution: how do we grow this safely?]

    D1 -.->|drives| D2
    D2 -.->|drives| D3
    D3 -.->|drives| D4
    D4 -.->|feeds back| D1

Decision 1 — Scope

The scope decision is "which of our workflows belong in FCC?"

FCC is well-suited to workflows that are:

  • Multi-persona — require hand-offs between distinct roles
  • Auditable — need a trace of who did what and why
  • Evolving — benefit from a quality-ratcheting model
  • Generative — produce artifacts (docs, code, reports) rather than mutations on external systems

FCC is not well-suited to workflows that are:

  • Transactional — a single synchronous operation with no review
  • Real-time — sub-second latency budgets
  • Isolated — a one-off script that never touches team state

Scope decision matrix

Workflow type Example FCC fit
Documentation pipeline "Generate ADR from design doc" High
Compliance audit "Produce evidence graph from repo" High
Research synthesis "Review 40 papers, extract findings" High
Code review "LGTM + checklist" Medium (too fast for multi-persona)
Payment processing "Charge card, send receipt" Low (transactional)
Alerting "Page on-call" Low (real-time)

Architects should write their own version of this table for their own organisation's top 20 workflows. FCC should own the "high" rows; the "medium" rows are candidates for plugin-only integration; the "low" rows should stay out.

Decision 2 — Topology

Once scope is settled, the architect picks a topology. FCC supports three:

Monolith. One FCC installation, one registry, one event bus, one CI pipeline. Simplest; works up to ~15 engineers and ~20 recurring workflows.

Star. One central FCC + N satellite ecosystem projects, each with their own plugin pack and vocabulary mappings. Central FCC holds the canonical persona registry; satellites hold domain-specific personas. Works up to ~100 engineers and multiple domains.

Mesh. Peer-to-peer federation across projects. Every node has its own registry and publishes a facade. Works for multi-org deployments and cross-company federations.

The diagram below shows when each topology is right.

quadrantChart
    title FCC Topology Decision
    x-axis Few Domains --> Many Domains
    y-axis Small Team --> Large Team
    quadrant-1 Star
    quadrant-2 Mesh
    quadrant-3 Monolith
    quadrant-4 Star

See For Data Architects — Federation Patterns for the detailed topology trade-offs.

Decision 3 — Governance

Governance is where most FCC adoptions succeed or fail. The architect's job is to pick the governance level before the first production workflow ships, not after.

FCC ships a 3-tier constitution:

  • Hard-stop — blocks execution; no override
  • Mandatory — blocks merge; can be waived with documented reason
  • Preferred — warns but allows

Every persona has a constitution entry that classifies its quality gates into these tiers. The Governance Compliance Auditor (GCA) persona's constitution, for instance, treats its 4 gates as all Mandatory by default — an architect may promote some to Hard-stop for regulated environments.

The governance playbook

  1. Start with the shipped constitutions — they are reasonable defaults.
  2. Classify your own workflows — for each custom workflow, decide which of the 30+ quality gates apply and at which tier.
  3. Wire the event bus early — observability is cheap up front and expensive to add later.
  4. Run fcc compliance audit in CI — the audit catches drift before it reaches production.

Decision 4 — Evolution

Evolution is the architect's long-horizon concern. A system that doesn't evolve gracefully becomes a liability; a system that evolves chaotically becomes unusable. FCC's evolution model rests on the same four-stage pipeline used for personas (see ch26 persona evolution): FOUNDATIONAL, STRUCTURED, SEMANTIC, FEDERATED.

Applied to an architect's system:

  • FOUNDATIONAL — FCC is installed; one workflow runs; no quality gates enforced.
  • STRUCTURED — custom personas added; fcc validate --personas green; workflow templates in version control.
  • SEMANTIC — cross-reference entries for every custom persona; discernment matrix scored; fcc dashboard quality integrated into the sprint review.
  • FEDERATED — vocabulary mappings resolve to ≥ 2 ecosystems; change tracking enabled; evidence graph published to regulators on demand.

The architect's evolution responsibility is to gate advancement. Moving from STRUCTURED to SEMANTIC is a real investment (maybe two weeks of engineering time); it should not happen by accident.

Platform vs application layering

A common architectural mistake is to treat FCC as either "a library we import" or "a platform we build on". It is both, depending on layer.

The diagram below separates the layers. The core is always library-shaped (import and use). The extensions are plugin-shaped (register at startup). The ecosystem bridges are facade-shaped (wrap and expose). Conflating these layers leads to either over-coupling (everything in one process) or over-fragmentation (everything in its own service).

flowchart TB
    subgraph "Layer 4 — Applications"
      A1[Your CLI]
      A2[Your Streamlit app]
      A3[Your web frontend]
    end
    subgraph "Layer 3 — Ecosystem bridges"
      B1[PAOM facade]
      B2[CTO bridge]
      B3[Your domain facade]
    end
    subgraph "Layer 2 — Extensions"
      E1[Custom personas]
      E2[Custom plugins]
      E3[Vocabulary providers]
    end
    subgraph "Layer 1 — Core"
      C1[PersonaRegistry]
      C2[SimulationEngine]
      C3[EventBus]
      C4[ModelFacade]
    end

    A1 --> B1
    A2 --> B2
    A3 --> B3
    B1 --> E1
    B2 --> E2
    B3 --> E3
    E1 --> C1
    E2 --> C2
    E3 --> C4

Use-case view of the four-layer model

The PlantUML use-case diagram below shows which actors interact with each layer. The architect's recurring job is to answer "which layer does this new request belong in?" — the diagram is the reference.

@startuml
left to right direction
skinparam monochrome true
skinparam shadowing false

actor "Library User" as LU
actor "Plugin Author" as PA
actor "Ecosystem Partner" as EP
actor "App Developer" as AD
actor "Operator" as OP
actor "Auditor" as AU

rectangle "Layer 1 — Core" {
  usecase "Import fcc" as UC1
  usecase "Call PersonaRegistry" as UC2
}
rectangle "Layer 2 — Extensions" {
  usecase "Register plugin" as UC3
  usecase "Author persona" as UC4
}
rectangle "Layer 3 — Bridges" {
  usecase "Publish facade" as UC5
  usecase "Map vocabulary" as UC6
}
rectangle "Layer 4 — Applications" {
  usecase "Embed in app" as UC7
  usecase "Deploy to production" as UC8
  usecase "Audit and report" as UC9
}

LU --> UC1
LU --> UC2
PA --> UC3
PA --> UC4
EP --> UC5
EP --> UC6
AD --> UC7
OP --> UC8
AU --> UC9
@enduml

Concrete layer choices

Three worked examples of layer choices an architect commonly faces:

"Our team wants LLM observability." This is a Layer 4 (Applications) concern and a Layer 2 (Extensions) concern — ship a custom event subscriber plugin (Layer 2) that exports to your observability backend, and wire a dashboard widget (Layer 4). Do not fork Layer 1.

"Our HR system needs to feed personas into FCC." Layer 3 (Ecosystem bridges). Author a facade that reads your HR system, map its vocabulary to FCC personas, and register via the ProviderRegistry. Do not add fields to Layer 1's PersonaSpec.

"We need audit reports in our format." Layer 4 (Applications). Write a Markdown-templating layer that consumes the audit JSON from Layer 1. Do not modify src/fcc/compliance/.

The ten architect questions

When consulting with a new adopter, an FCC architect asks these ten questions in this order. Answers surface the topology, governance tier, and evolution plan.

  1. How many engineers will touch FCC in the first six months?
  2. How many distinct workflows do you expect to run?
  3. What regulations apply to your outputs?
  4. Do you have an existing persona-like abstraction you need to bridge?
  5. Is your data multi-tenant?
  6. What's your observability stack?
  7. What's your CI/CD stack?
  8. Do you need air-gapped operation?
  9. What's the worst-case failure mode you want to prevent?
  10. What's the success metric a year from now?

Anti-patterns (architect edition)

Anti-pattern Consequence Remedy
Adopting all 147 personas Overwhelming; no one remembers the roster Pick 8-12; grow as needed
Skipping quality gates Quality drift compounds silently Enable gates from day one
Mesh before monolith works Premature complexity Monolith → Star → Mesh
Building a custom plugin type Duplicates the 11 shipped types Extend an existing plugin type first
Treating constitutions as optional Compliance posture crumbles Set tiers before shipping workflows

Sample-prompt cross-references

Architect work benefits from the following sample prompt collections:

Knowledge check

  1. (Short) Which of the four architect decisions feeds back into which other decision?
  2. (Short) Name two workflow types where FCC is a poor fit.
  3. (Short) What's the headcount threshold where Monolith usually breaks down?
  4. (Short) Which layer in the four-layer model contains vocabulary providers?

Answers

  1. Decision 4 (Evolution) feeds back into Decision 1 (Scope).
  2. Any two of: transactional, real-time, isolated.
  3. ~15 engineers; above that, Star starts to pay back.
  4. Layer 2 — Extensions.

See also