Architecture Data Flow Diagram Prompts¶

This file collects six end-to-end prompts for producing and reviewing data-flow diagrams (DFDs) for FCC subsystems. Mermaid flowcharts are used because they compose well with the existing docs pipeline. Each prompt ties to a real file under docs/architecture/data-flow-diagrams/, fixes personas and R.I.S.C.E.A.R. slots, and pins the shape of the deliverable.

Table of Contents¶

Scenario to Trace Pipeline
RAG Document Pipeline
Compliance Evidence Graph Flow
Cross-Project Entity Resolution Data Paths
Event Bus Fan-Out DFD
Author a New Model Card Generation DFD

1. Scenario to Trace Pipeline¶

When to use. Teaching how a scenario JSON turns into a simulation trace.

Personas/subsystems invoked. dal, tr. R.I.S.C.E.A.R. slot: Input + Expected Output.

You are the Data Analyst Lead (dal). Technical Reviewer (tr) reviews.

Open docs/architecture/data-flow-diagrams/scenario-to-trace.md.

TASK: Produce a Mermaid flowchart (TD direction) that shows:
- Scenario JSON file (src/fcc/data/scenarios/) as an external source.
- ScenarioLoader node.
- FCCValidator.from_registry() validation step.
- SimulationEngine process, split into deterministic vs AI-powered.
- Trace JSON output (data store).
- EventBus side-channel receiving progress events.

CONSTRAINTS:
- Use distinct node shapes for processes (rect), data stores (cyl), and
  externals (stadium).
- Cite at least one of the 33 scenarios shipped.
- Show the AI provider fall-through to the mock provider.

Deliverable: flowchart block plus a 4-row table mapping each node to the
src/fcc/ module it lives in.

Expected output notes. Distinct node shapes; ties nodes to real module paths; AI-provider branch visible.

2. RAG Document Pipeline¶

When to use. Onboarding a new contributor to the RAG pipeline's chunk-to-answer path.

Personas/subsystems invoked. dal, cw. R.I.S.C.E.A.R. slot: Expected Output.

You are the Data Analyst Lead (dal). Content Writer (cw) reviews.

Open docs/architecture/data-flow-diagrams/rag-document-pipeline.md
and src/fcc/rag/.

TASK: Produce a flowchart (LR direction) that walks raw document input
through chunking, embedding, indexing, retrieval, and answer assembly.

Required nodes:
- Raw docs (markdown/pdf/html) as external.
- DocumentChunker (pick one of six strategies; label it).
- EmbeddingProvider (MockEmbeddingProvider at 384 dims).
- SearchIndex data store.
- SemanticRetriever process.
- RAGPipeline answer-assembly process.
- Answer output (external sink).

CONSTRAINTS:
- Include one feedback edge showing persona-aware re-ranking.
- Label every edge with the data type (chunks, vectors, scored passages,
  answer).

Deliverable: flowchart block plus a 1-paragraph (<=100 words) summary of
where persona context is injected.

Expected output notes. Labelled edges; one strategy named; persona re-ranking edge is explicit.

3. Compliance Evidence Graph Flow¶

When to use. Explaining how audit findings become an exportable evidence graph.

Personas/subsystems invoked. ra, dal. R.I.S.C.E.A.R. slot: Constraints + Expected Output.

You are the Risk Analyst (ra). Data Analyst Lead (dal) reviews.

Open docs/architecture/data-flow-diagrams/compliance-evidence-graph.md
and src/fcc/compliance/evidence_graph.py.

TASK: Produce a flowchart that shows:
- ComplianceAuditor output (AuditFinding, EvidenceItem lists) entering
  the process.
- build_compliance_evidence_graph() function as the main process.
- KnowledgeGraph data store.
- Serializer fan-out (OWL / RDF / SKOS / JSON-LD).
- EventBus emitting "compliance audit completed" notifications.

CONSTRAINTS:
- Do not invent serializers beyond the four shipped.
- Use a fork node to show parallel serialization.
- Reference the 256+ EU AI Act requirement count on the edge label.

Deliverable: flowchart block plus a short "retention policy" note (<=40
words) covering where findings persist.

Expected output notes. Fork for 4 serializers; retention note present; only real serializers referenced.

4. Cross-Project Entity Resolution Data Paths¶

When to use. Teaching federation mechanics across two of the 11 ecosystems.

Personas/subsystems invoked. dal, tr. R.I.S.C.E.A.R. slot: Input + Role Collaborators.

You are the Data Analyst Lead (dal). Technical Reviewer (tr) reviews.

Open docs/architecture/data-flow-diagrams/cross-project-entity-resolution.md.

TASK: Produce a flowchart that shows an entity query crossing FCC to
another named ecosystem. Include:
- EntityResolver process.
- NamespaceRegistry data store (11 ecosystems).
- VocabularyMapping lookup process.
- ChangeTracker data store.
- Return path delivering a resolved canonical entity.

CONSTRAINTS:
- Pick two of the 11 ecosystems and name them on external nodes.
- Show a miss-path that writes to ChangeTracker.

Deliverable: flowchart block plus a 3-row table of the VocabularyMapping
YAML files touched (from src/fcc/data/objectmodel/).

Expected output notes. Two real ecosystem names; miss path writes to ChangeTracker; table cites real YAML files.

5. Event Bus Fan-Out DFD¶

When to use. Visualizing which subsystems react to a simulation step event.

Personas/subsystems invoked. sre, tr. R.I.S.C.E.A.R. slot: Responsibilities.

You are the Site Reliability Engineer (sre). Technical Reviewer (tr)
reviews.

No DFD exists for this view yet (new artifact).

TASK: Produce a flowchart showing a SIMULATION_STEP_COMPLETED event
fanning out to:
- Observability tracer (src/fcc/observability/tracing.py).
- Metrics collector.
- ComplianceSubscriber.
- Any EventSubscriberPlugin (generic).
- Collaboration SessionRecorder.

CONSTRAINTS:
- Label every edge with the filter predicate applied.
- Use rect for processes and cyl for stores (tracer output file,
  metrics store, recorder JSON).

Deliverable: flowchart block plus a short "backpressure" note (<=60
words) describing what happens when a subscriber is slow.

Expected output notes. Five labelled fan-out edges with filter predicates; backpressure note present.

6. Author a New Model Card Generation DFD¶

When to use. No DFD currently covers the model-card generator; we want to teach contributors the flow.

Personas/subsystems invoked. dal, cw. R.I.S.C.E.A.R. slot: Expected Output + Role Adoption Checklist.

You are the Data Analyst Lead (dal). Content Writer (cw) reviews.

No file exists yet at docs/architecture/data-flow-diagrams/model-card-generation.md.
Author a new Markdown document.

TASK: Produce a flowchart showing how 173 model cards are generated:
- PersonaRegistry + WorkflowGraphs + Categories as inputs.
- ModelCardGenerator process (src/fcc/evaluation/card_generator.py).
- Jinja2 template directory (src/fcc/templates/docs/) as a data store.
- Output: 173 Markdown files under docs/model-cards/.

Include:
- Fan-in for the three input sources.
- One branch showing datasheet generation.
- A 3-item Role Adoption Checklist for extending the generator.

CONSTRAINTS:
- Use the real counts (102 persona + 45 vertical + 6 workflow + 20
  category = 173).
- Do not invent new inputs.

Deliverable: Markdown file body (front matter + flowchart + checklist)
ready to land as a new architecture doc.

Expected output notes. Complete new Markdown file with front matter, valid flowchart block, real card counts, 3-item checklist.