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.