# karkuak/qualgraph-scenario-lab architecture

> Architecture diagram of the GitHub repository karkuak/qualgraph-scenario-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karkuak/qualgraph-scenario-lab
- Repository: https://github.com/karkuak/qualgraph-scenario-lab

## Overview

Scenario Lab is a command-line tool for running synthetic software-quality scenarios and evaluating advisory QualGraph outputs against known ground truth. Its main workflow validates and loads a scenario pack, optionally applies an entropy profile, canonicalizes evidence, generates journey and impact/test/release analyses, then scores and writes a report. The graph preserves the major evaluation and output stages visible in the source index. Several adapter and canonical modules are present, but their runtime wiring is not established by the excerpts, so they are not connected speculatively.

Main entry points: [`scenario-lab/src/runtime/runScenario.ts`](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/runScenario.ts) (Scenario runner), [`scenario-lab/src/runtime/scoreScenario.ts`](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/scoreScenario.ts) (Scenario scoring), [`scenario-lab/src/runtime/validateScenarioPack.ts`](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/validateScenarioPack.ts) (Pack validation), [`scenario-lab/src/cli.ts`](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/cli.ts) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command Line"]
  node_cli["CLI<br/>[cli.ts]"]
  node_runner["Scenario runner<br/>[runScenario.ts]"]
end

subgraph group_scenario["Scenario Inputs"]
  node_validator["Pack validation"]
  node_loader["Pack loading"]
  node_provenance["Provenance<br/>[provenance.ts]"]
  node_filesystem["File access<br/>[fs.ts]"]
  node_entropy["Entropy profile"]
  node_packtypes["Scenario pack model<br/>[scenarioPack.ts]"]
end

subgraph group_evidence["Evidence Modeling"]
  node_canonical["Canonical evidence"]
  node_telemetry["Telemetry adapter"]
end

subgraph group_analysis["Quality Analysis"]
  node_journey["Journey quality map"]
  node_impact["Impact draft"]
  node_recommendation["Test recommendation"]
  node_validation["Deterministic validation"]
  node_clusters["Failure hypotheses"]
  node_release["Release evidence pack"]
  node_outputtypes["Analysis output model"]
end

subgraph group_evaluation["Evaluation"]
  node_score["Scenario scoring<br/>[scoreScenario.ts]"]
  node_comparison["Ground-truth comparison"]
  node_realism["Realism scoring<br/>[realismScore.ts]"]
  node_guardrails["Output guardrails"]
  node_report["Evaluation report"]
  node_evaluationtypes["Evaluation model<br/>[evaluation.ts]"]
end

node_user(("Scenario operator"))

node_user -->|"runs"| node_cli
node_cli -->|"validates pack"| node_validator
node_cli -->|"starts scenario"| node_runner
node_runner -->|"validates pack"| node_validator
node_runner -->|"loads pack"| node_loader
node_runner -->|"applies profile"| node_entropy
node_runner -->|"builds evidence"| node_canonical
node_runner -->|"uses adapter"| node_telemetry
node_runner -->|"builds map"| node_journey
node_runner -->|"generates draft"| node_impact
node_runner -->|"generates advice"| node_recommendation
node_runner -->|"checks telemetry"| node_validation
node_runner -->|"forms hypotheses"| node_clusters
node_runner -->|"builds pack"| node_release
node_runner -->|"scores outputs"| node_score
node_runner -->|"formats report"| node_report
node_score -->|"compares truth"| node_comparison
node_score -->|"scores realism"| node_realism
node_score -->|"checks language"| node_guardrails
node_loader -->|"reads files"| node_filesystem
node_loader -->|"loads provenance"| node_provenance
node_validator -->|"reads files"| node_filesystem
node_validator -->|"checks sidecars"| node_provenance

click node_cli "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/cli.ts"
click node_validator "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/validateScenarioPack.ts"
click node_loader "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/loadScenarioPack.ts"
click node_provenance "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/provenance.ts"
click node_filesystem "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/fs.ts"
click node_entropy "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/applyEntropyProfile.ts"
click node_runner "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/runScenario.ts"
click node_canonical "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/canonical/canonicalEvidence.ts"
click node_telemetry "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/adapters/telemetrytestAdapter.ts"
click node_journey "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/buildJourneyQualityMap.ts"
click node_impact "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateImpactDraft.ts"
click node_recommendation "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateAdvisoryTestRecommendation.ts"
click node_validation "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/runDeterministicValidation.ts"
click node_clusters "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateFailureClusterHypotheses.ts"
click node_release "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateReleaseEvidencePack.ts"
click node_score "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/scoreScenario.ts"
click node_comparison "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/compareToGroundTruth.ts"
click node_realism "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/evaluation/realismScore.ts"
click node_guardrails "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/guardrails/boundedLanguageCheck.ts"
click node_report "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/generateEvaluationReport.ts"
click node_packtypes "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/types/scenarioPack.ts"
click node_outputtypes "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/types/qualgraphOutputs.ts"
click node_evaluationtypes "https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/types/evaluation.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runner toneBlue
class node_validator,node_loader,node_provenance,node_filesystem,node_entropy,node_packtypes toneAmber
class node_canonical,node_telemetry toneMint
class node_journey,node_impact,node_recommendation,node_validation,node_clusters,node_release,node_outputtypes toneRose
class node_score,node_comparison,node_realism,node_guardrails,node_report,node_evaluationtypes,node_user toneIndigo
```

## Components

### Command Line

- [CLI](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/cli.ts): `scenario-lab/src/cli.ts`
- [Scenario runner](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/runScenario.ts): `scenario-lab/src/runtime/runScenario.ts`

### Scenario Inputs

- [Pack validation](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/validateScenarioPack.ts): `scenario-lab/src/runtime/validateScenarioPack.ts`
- [Pack loading](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/loadScenarioPack.ts): `scenario-lab/src/runtime/loadScenarioPack.ts`
- [Provenance](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/provenance.ts): `scenario-lab/src/runtime/provenance.ts`
- [File access](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/fs.ts): `scenario-lab/src/runtime/fs.ts`
- [Entropy profile](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/applyEntropyProfile.ts): `scenario-lab/src/runtime/applyEntropyProfile.ts`
- [Scenario pack model](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/types/scenarioPack.ts): `scenario-lab/src/types/scenarioPack.ts`

### Evidence Modeling

- [Canonical evidence](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/canonical/canonicalEvidence.ts): `scenario-lab/src/canonical/canonicalEvidence.ts`
- [Telemetry adapter](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/adapters/telemetrytestAdapter.ts): `scenario-lab/src/adapters/telemetrytestAdapter.ts`

### Quality Analysis

- [Journey quality map](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/buildJourneyQualityMap.ts): `scenario-lab/src/simulatedQualGraph/buildJourneyQualityMap.ts`
- [Impact draft](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateImpactDraft.ts): `scenario-lab/src/simulatedQualGraph/generateImpactDraft.ts`
- [Test recommendation](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateAdvisoryTestRecommendation.ts): `scenario-lab/src/simulatedQualGraph/generateAdvisoryTestRecommendation.ts`
- [Deterministic validation](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/runDeterministicValidation.ts): `scenario-lab/src/simulatedQualGraph/runDeterministicValidation.ts`
- [Failure hypotheses](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateFailureClusterHypotheses.ts): `scenario-lab/src/simulatedQualGraph/generateFailureClusterHypotheses.ts`
- [Release evidence pack](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/simulatedQualGraph/generateReleaseEvidencePack.ts): `scenario-lab/src/simulatedQualGraph/generateReleaseEvidencePack.ts`
- [Analysis output model](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/types/qualgraphOutputs.ts): `scenario-lab/src/types/qualgraphOutputs.ts`

### Evaluation

- [Scenario scoring](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/scoreScenario.ts): `scenario-lab/src/runtime/scoreScenario.ts`
- [Ground-truth comparison](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/compareToGroundTruth.ts): `scenario-lab/src/runtime/compareToGroundTruth.ts`
- [Realism scoring](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/evaluation/realismScore.ts): `scenario-lab/src/evaluation/realismScore.ts`
- [Output guardrails](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/guardrails/boundedLanguageCheck.ts): `scenario-lab/src/guardrails/boundedLanguageCheck.ts`
- [Evaluation report](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/runtime/generateEvaluationReport.ts): `scenario-lab/src/runtime/generateEvaluationReport.ts`
- [Evaluation model](https://github.com/karkuak/qualgraph-scenario-lab/blob/main/scenario-lab/src/types/evaluation.ts): `scenario-lab/src/types/evaluation.ts`

### Other components

- **Scenario operator**

## Connections

- Scenario operator → CLI: runs (evidence: `scenario-lab/src/cli.ts`)
- CLI → Pack validation: validates pack (evidence: `scenario-lab/src/cli.ts`)
- CLI → Scenario runner: starts scenario (evidence: `scenario-lab/src/cli.ts`)
- Scenario runner → Pack validation: validates pack (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Pack loading: loads pack (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Entropy profile: applies profile (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Canonical evidence: builds evidence (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Telemetry adapter: uses adapter (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Journey quality map: builds map (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Impact draft: generates draft (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Test recommendation: generates advice (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Deterministic validation: checks telemetry (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Failure hypotheses: forms hypotheses (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Release evidence pack: builds pack (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Scenario scoring: scores outputs (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario runner → Evaluation report: formats report (evidence: `scenario-lab/src/runtime/runScenario.ts`)
- Scenario scoring → Ground-truth comparison: compares truth (evidence: `scenario-lab/src/runtime/scoreScenario.ts`)
- Scenario scoring → Realism scoring: scores realism (evidence: `scenario-lab/src/runtime/scoreScenario.ts`)
- Scenario scoring → Output guardrails: checks language (evidence: `scenario-lab/src/runtime/scoreScenario.ts`)
- Pack loading → File access: reads files (evidence: `scenario-lab/src/runtime/loadScenarioPack.ts`)
- Pack loading → Provenance: loads provenance (evidence: `scenario-lab/src/runtime/loadScenarioPack.ts`)
- Pack validation → File access: reads files (evidence: `scenario-lab/src/runtime/validateScenarioPack.ts`)
- Pack validation → Provenance: checks sidecars (evidence: `scenario-lab/src/runtime/validateScenarioPack.ts`)
