Skip to content

4+1 Scenarios View

The Scenarios View is Kruchten's +1. Its job is to validate the other four views against concrete workflows: a scenario that cannot be told through the logical, process, development, and physical views together is a signal that one of those views is missing something. This page walks four representative scenarios — author a persona, run a compliance audit, add a vocabulary plugin, and federate a query — and at the end maps each scenario back to the views it exercises.

Scenario 1: author a new persona

A new persona author runs fcc add-persona from the CLI, fills in the R.I.S.C.E.A.R. prompts, and expects the resulting YAML to pass validation and show up in dashboards, docs, and model cards without further action.

Figure 1 shows the actors and subsystems involved.

@startuml
left to right direction
actor "Persona Author" as PA
actor "CI validator" as CI

rectangle "FCC framework" {
  usecase "fcc add-persona (CLI)" as UC1
  usecase "Fill RISCEAR prompts" as UC2
  usecase "Write YAML under\nsrc/fcc/data/personas/" as UC3
  usecase "FCCValidator.from_registry\nagainst JSON schema" as UC4
  usecase "PersonaRegistry.merge" as UC5
  usecase "Regenerate docs-as-code" as UC6
  usecase "Regenerate model card" as UC7
}

PA --> UC1
UC1 ..> UC2 : includes
UC2 ..> UC3 : includes
UC3 ..> UC4 : triggers
UC4 ..> UC5 : if valid
UC5 ..> UC6 : cascade
UC5 ..> UC7 : cascade
CI --> UC4 : on PR
@enduml

This scenario exercises the Logical View (PersonaSpec + RISCEARSpec shape), the Development View (CLI to registry to doc generator), and the Process View (validation events on the bus).

Scenario 2: run a compliance audit

An operator runs fcc compliance-audit to check the current persona catalog against the EU AI Act (256+ requirements) and NIST AI RMF (29 subcategories). The command emits a ComplianceReport JSON plus a dashboard-ready summary.

Figure 2 is the sequence of the audit run.

sequenceDiagram
    participant Op as Operator
    participant CLI as fcc compliance-audit
    participant Auditor as ComplianceAuditor
    participant PR as PersonaRegistry
    participant RR as RequirementRegistry
    participant Dash as Compliance Dashboard

    Op->>CLI: fcc compliance-audit --regulation eu_ai_act
    CLI->>Auditor: audit(persona_registry)
    Auditor->>PR: iter_personas()
    PR-->>Auditor: 147 personas
    Auditor->>RR: load(eu_ai_act)
    RR-->>Auditor: 256+ requirements
    loop per persona
        Auditor->>Auditor: classify(persona) → risk
        Auditor->>Auditor: evaluate applicable gates
        Auditor-->>CLI: emit compliance.persona_audited
    end
    Auditor-->>CLI: ComplianceReport
    CLI->>Dash: render_dashboard(report)
    CLI-->>Op: compliance_report.json + summary

This scenario exercises the Logical View (compliance classes), the Process View (the audit activity), and the Physical View (the dashboard running in the Streamlit container).

Scenario 3: add a vocabulary plugin

A sibling project like Athenium or Mnemosyne publishes a PyPI package declaring an fcc.vocabulary_providers entry point. The FCC user adds the package to their environment and expects their next fcc federate resolve call to pick up the new mappings.

Figure 3 shows the actors and the plugin discovery path.

@startuml
left to right direction
actor "Plugin author\n(Athenium, Mnemosyne, …)" as PA
actor "FCC user" as FU

rectangle "Plugin package" {
  usecase "Implement VocabularyProviderPlugin" as UC1
  usecase "Declare fcc.vocabulary_providers\nentry point" as UC2
  usecase "pip publish" as UC3
}

rectangle "FCC framework" {
  usecase "pip install plugin-pkg" as UC4
  usecase "PluginRegistry.load_all" as UC5
  usecase "VocabularyMappingLoader.verify\nagainst packaged schema" as UC6
  usecase "Mappings available to\nEntityResolver, RAG, KG" as UC7
}

PA --> UC1
UC1 --> UC2
UC2 --> UC3
FU --> UC4
UC4 --> UC5
UC5 --> UC6
UC6 --> UC7
@enduml

This scenario exercises the Logical View (VocabularyProviderPlugin ABC), the Development View (entry-point wiring), and the Physical View (the plugin lives in a separate wheel).

Scenario 4: federate a query across projects

A consumer (typically another persona running over MCP or A2A) asks the EntityResolver for the canonical form of a vocabulary term. The resolver walks 19 registered namespaces, collects candidates, and returns the highest-confidence match along with provenance.

Figure 4 traces the federated query end-to-end.

sequenceDiagram
    participant Consumer
    participant ER as EntityResolver
    participant NS as NamespaceRegistry
    participant VM as VocabularyMappingStore
    participant CT as ChangeTracker
    participant Bus as EventBus

    Consumer->>ER: resolve(term, hint=nil)
    ER->>NS: list_namespaces()
    NS-->>ER: 19 namespaces
    loop per namespace
        ER->>VM: lookup(namespace, term)
        VM-->>ER: 0..n candidates
    end
    ER->>ER: rank candidates by confidence
    ER->>CT: record_resolution_event
    ER->>Bus: publish(federation.query_resolved)
    ER-->>Consumer: CanonicalEntity(+provenance)

This scenario exercises the Logical View (EntityResolver, NamespaceRegistry), the Process View (the event emission), the Development View (the federation/ subpackage boundary), and the Physical View (candidates may live in sibling project endpoints from the ecosystem port map).

Mapping back to the other four views

Scenario Logical Process Development Physical
Author a new persona PersonaSpec, RISCEARSpec CLI to loader to events CLI under scaffold/, YAML under data/personas/ Local dev (no containers)
Run a compliance audit ComplianceAuditor, RequirementRegistry Activity diagram compliance/ + dashboard/ Streamlit container
Add a vocabulary plugin VocabularyProviderPlugin ABC Entry-point load at import Plugin wheel, entry points External PyPI package
Federate a query EntityResolver, NamespaceRegistry Sequence diagram federation/ subpackage 19-project port map

Every row validates at least three views; every view is exercised by at least two scenarios. That is the Scenarios-View job: proving the other four views cover the workflows that matter.

How to use this page

When adding a new capability, add a scenario here first. If writing the scenario exposes a gap in one of the other views, fix that view before you ship the capability — the Scenarios View is the integration test of the architecture docs themselves.

When deprecating a capability, remove its scenario and confirm that no other scenario relied on it transitively. A scenario with no matching capability in one of the other four views is a documentation drift signal.

See also

v1.5.0 Scenarios Impact

v1.5.0 introduced two new representative scenarios that validate the Logical / Process / Development / Physical views against concrete workflows.

Scenario 5 — Host a multi-user collaborative session. A facilitator creates a session, three users join concurrently, each edits the same text, cursors update live, and an auditor subscribes to the UX-lane event bus to observe. The scenario exercises the Logical View (MultiUserSession aggregate + CollaborativeDocument + CRDTBackend), the Process View (CRDT convergence loop, dual-bus event routing), the Development View (src/fcc/collaboration/multi_user.py + sibling CRDT module), and the Physical View (WebSocket bridge at :8765, SSE stream at :8901). See ../use-case-diagrams/multi-user-session.md for the actor-to-use-case map and ../sequence-diagrams/crdt-multi-user-merge.md for the convergence sequence.

Scenario 6 — Run a GraphRAG query with Zachman filter. A federation operator issues a query with a target Zachman cell, asks GraphRAG to expand up to three hops across the knowledge graph (optionally augmented by LYRA), and receives a ranked, persona-aware context block. The scenario exercises the Logical View (GraphRAG + GraphRAGResult + LyraBridgeProtocol), the Process View (the six-step query pipeline), the Development View (src/fcc/rag/graphrag.py + src/fcc/knowledge/lyra_bridge.py), and the Physical View (everything runs in the backend container; no new external calls unless lyra.api is installed). See ../sequence-diagrams/graphrag-zachman-filter.md for the full trace.

These two scenarios plus the existing four (author persona, compliance audit, vocabulary plugin, federate query) form the v1.5.0+ integration test matrix — every one exercises at least three of the other four views, which is the scenarios-view invariant.

v1.6.0 Impact

v1.6.0 introduces two further representative scenarios that exercise the three pillars executed in this release (A, C, and the live half of B's LYRA bridge) plus the v1.6.2 ecosystem-docs surfaces.

Scenario 7 — Ecosystem-docs navigation. A new reader lands on the top-level README, spots the ecosystem callout block, clicks through to docs/ecosystem/codename-decoder.md, finds the row for the codename they encountered in a sibling-repo commit message (say, POLARIS or SERPENS), and follows the canonical GitHub URL to the live project. The v1.6.2 addition — scripts/verify_codename_decoder.py, wired into make codename-decoder-verify and make docs-ecosystem-check — is the CI gate that guarantees every row either resolves to a real local clone path or to the explicit "not cloned locally" sentinel, with no leftover external (' placeholders. The scenario exercises the Logical View (codename-decoder is a pure-data YAML+markdown table, no new classes), the Process View (the verifier runs at CI time, not at FCC runtime), the Development View (the verifier lives under scripts/ alongside its Pillar C sibling), and the Physical View (the decoder links point at external GitHub repos and local absolute paths on the owner's dev host; no deployed service is involved).

Scenario 8 — Full make pub-all rebuild with the new mermaid diagrams. A publications operator runs make pub-all against a fresh v1.6.2 checkout. The pipeline: (a) picks up publications/scripts/puppeteer-config.json (ADR-014) so every mmdc Chromium instance starts without /dev/shm or sandbox deadlocks; (b) renders the three new v1.6.0 diagrams (pillar-a-seed-lifecycle-v160.md, pillar-c-translation-flow-v160.md, lyra-live-integration-v160.md) alongside the existing 386; (c) writes SVG/PNG twins into the processed-markdown trees that Quarto + Pandoc consume for PDF / DOCX / EPUB output; (d) emits the 27 PDF / DOCX / EPUB / HTML / PPTX artifacts under publications/_output/ including the new diagrams. The scenario exercises the Logical View (the three new diagrams document the Pillar A / Pillar C / LYRA-live runtime modules), the Process View (mmdc worker fan-out under the new puppeteer config), the Development View (the three new files under docs/architecture/ and the scripts/ CI gates), and the Physical View (the render pipeline touches only the publications container and the committed seed-canonical tree; nothing external).

These two scenarios plus the previous six (author persona, compliance audit, vocabulary plugin, federate query, multi-user session, GraphRAG + Zachman) form the v1.6.0+ integration-test matrix. Every scenario still exercises at least three of the other four views, and the new pair are the first to exercise the Pillar A artifact store, the Pillar C glossary gate, and ADR-014's puppeteer config all in a single build — a strong signal that the scenarios-view invariant holds across the v1.5.0 → v1.6.0 pillar-execution cycle.