Design goals
- Make operational state explainable to reviewers.
- Keep the app deployable without external vendors.
- Show software, platform, data, and governance concerns together.
- Allow future LLM augmentation without making it mandatory.
Core layers
- Scenario layer — deterministic service, contract, and incident snapshots.
- Scoring layer — risk, health, and release gate computation.
- Narrative layer — deterministic executive and incident summaries.
- LLM augmentation layer — optional OpenAI-powered brief generation and grounded Q&A.
- Export layer — markdown and JSON review packs.
- Evidence layer — event extraction, owner scorecards, and comparison views.
- Bundle layer — signed zip bundles with manifest and tabular artifacts.
- Presentation layer — Streamlit multipage command surfaces.
Why deterministic narratives first
Deterministic narratives keep the project portable, debuggable, and interview-friendly. They also prove that the system can produce useful operational guidance even when no external model is available.
Extension path
A future adapter can replace or augment the narrative layer:
DeterministicNarrativeEngine(today)OpenAI response-backed assist layer(now optional)
The presentation layer does not need to change as long as the engine contract stays stable.
Review bundle contract
The bundle exporter packages:
- review-pack markdown
- review-pack JSON
- services / contracts / incidents / gates CSVs
- action-board CSV
- evidence timeline CSV
- manifest with SHA256 checksums