# rai-himanshu07/cadence-diff architecture

> Architecture diagram of the GitHub repository rai-himanshu07/cadence-diff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rai-himanshu07/cadence-diff
- Repository: https://github.com/rai-himanshu07/cadence-diff

## Overview

#### Purpose and entry points
cadence-diff is a local, read-only quality-control system for recurring Excel and PowerPoint reporting deliverables. It supports single-file preflight, baseline-versus-current cycle comparison, and Excel↔PPT final-package reconciliation. Primary entry points are CLI/server startup in `main.py`, `qc_tool/__main__.py`, and `qc_tool/cli.py`; the local NiceGUI application is `qc_tool/ui/app.py`.

#### Run orchestration and modes
`qc_tool/engine.py` coordinates mode inference, staged analysis, coverage accounting, finding production, cancellation, and report generation. `qc_tool/run_service.py` and `qc_tool/worker.py` provide run lifecycle execution, while `qc_tool/runqueue.py` manages queued UI/background work. The engine is the central boundary between loaded document models and QC-domain analyzers.

#### Input loading and safety boundary
Read-only document ingestion is centered on `qc_tool/io/loader.py` and normalized models in `qc_tool/io/model.py`. OOXML worksheet/chart/interaction parsing is separated into `qc_tool/io/ooxml_worksheet.py`, `qc_tool/io/ooxml_chart.py`, and `qc_tool/io/ooxml_interaction.py`. Decryption is isolated in `qc_tool/io/decrypt.py`. XLSB formula enrichment has platform-specific adapters (`qc_tool/io/xlsb_formula.py`, `qc_tool/io/libreoffice_formula.py`) and intentionally degrades coverage rather than asserting unsupported formula semantics.

#### Excel analysis pipeline
The Excel domain under `qc_tool/excel/` evaluates workbook integrity and cycle changes from normalized snapshots. Core stages include preflight (`qc_tool/excel/preflight.py`), region/cadence identification (`qc_tool/excel/regions.py`, `qc_tool/excel/periods.py`), shift-aware alignment (`qc_tool/excel/align.py`), formula and value comparison (`qc_tool/excel/formulas.py`, `qc_tool/excel/diff_values.py`), dependency/reference analysis (`qc_tool/excel/dependency.py`, `qc_tool/excel/references.py`), and workbook/chart/interaction risk checks (`qc_tool/excel/workbook_risks.py`, `qc_tool/excel/charts.py`, `qc_tool/excel/interaction.py`).

#### PowerPoint and package reconciliation
PowerPoint extraction, preflight, and semantic comparison are distinct from Excel logic: `qc_tool/ppt/extract.py`, `qc_tool/ppt/preflight.py`, and `qc_tool/ppt/diff.py`. Shape and chart matching use dedicated matching/model layers in `qc_tool/ppt/match.py`, `qc_tool/ppt/element_match.py`, and `qc_tool/ppt/model.py`. Final-package QC crosses this boundary through `qc_tool/crosscheck/package.py`, with numeric and source tracing in `qc_tool/crosscheck/numbers.py` and `qc_tool/crosscheck/trace.py`.

#### Findings, review state, and outputs
Atomic findings and coverage are represented in `qc_tool/findings.py`; severity classification and analyst overrides flow through `qc_tool/triage/rules.py` and `qc_tool/review.py`. Change-story synthesis is isolated in `qc_tool/story.py`. Reports are generated from reviewed state as JSON, HTML, and annotated Excel via `qc_tool/report/json_report.py`, `qc_tool/report/html_report.py`, and `qc_tool/report/excel_report.py`.

#### Persistence, security, and runtime
Per-user run history, annotations, mappings, and re-QC lineage are persisted through `qc_tool/history/store.py` and `qc_tool/history/run_state.py` (SQLite per README). The UI server defaults to loopback; temporary LAN exposure policy is managed by `qc_tool/server_config.py`. Privacy and evidence features are local-only: `qc_tool/privacy.py`, `qc_tool/fingerprint.py`, `qc_tool/attestation.py`, and `qc_tool/package_sanitize.py`. No LLMs or external services are part of the execution architecture.

Main entry points: [`qc_tool/io/loader.py`](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/loader.py) (Document loader), [`qc_tool/review.py`](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/review.py) (Review state), [`qc_tool/findings.py`](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/findings.py) (Findings and coverage), [`qc_tool/io/model.py`](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/model.py) (Normalized models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Local entry points"]
  node_cli["CLI<br/>command entry<br/>[cli.py]"]
  node_ui["NiceGUI app<br/>local UI<br/>[app.py]"]
end

subgraph group_runtime["Run orchestration"]
  node_run_service["Run service<br/>lifecycle service<br/>[run_service.py]"]
  node_run_queue["Run queue<br/>background queue<br/>[runqueue.py]"]
  node_worker["Run worker<br/>background worker<br/>[worker.py]"]
  node_engine{{"QC engine<br/>orchestrator<br/>[engine.py]"}}
end

subgraph group_ingest["Read-only ingestion"]
  node_loader["Document loader<br/>read-only loader<br/>[loader.py]"]
  node_document_model["Normalized models<br/>document model<br/>[model.py]"]
  node_ooxml_parsers["OOXML parsers<br/>worksheet/chart parser<br/>[ooxml_worksheet.py]"]
  node_decrypt["Decryption boundary<br/>decryption adapter<br/>[decrypt.py]"]
  node_xlsb_formula["XLSB formula enrichment<br/>platform adapter<br/>[xlsb_formula.py]"]
end

subgraph group_analysis["QC analysis"]
  node_excel_pipeline{{"Excel QC pipeline<br/>workbook analyzer<br/>[preflight.py]"}}
  node_ppt_pipeline{{"PowerPoint QC pipeline<br/>presentation analyzer<br/>[extract.py]"}}
  node_package_crosscheck{{"Package reconciliation<br/>cross-document analyzer<br/>[package.py]"}}
end

subgraph group_review["Review and outputs"]
  node_findings["Findings and coverage<br/>QC domain model<br/>[findings.py]"]
  node_triage["Triage rules<br/>severity policy<br/>[rules.py]"]
  node_review["Review state<br/>analyst review<br/>[review.py]"]
  node_story["Change story<br/>finding synthesis<br/>[story.py]"]
  node_reports["Reports<br/>JSON/HTML/Excel output<br/>[json_report.py]"]
end

subgraph group_state["Local state and security"]
  node_history[("Run history<br/>SQLite persistence<br/>[store.py]")]
  node_privacy["Privacy and evidence<br/>local-only controls<br/>[privacy.py]"]
  node_server_config["Server exposure policy<br/>runtime security<br/>[server_config.py]"]
end

node_cli -->|"starts run"| node_run_service
node_ui -->|"queues work"| node_run_queue
node_ui -.->|"uses policy"| node_server_config
node_run_queue -->|"dispatches"| node_worker
node_run_service -->|"executes"| node_engine
node_worker -->|"executes"| node_engine
node_engine -->|"loads inputs"| node_loader
node_loader -->|"handles protected files"| node_decrypt
node_loader -->|"parses OOXML"| node_ooxml_parsers
node_loader -->|"enriches XLSB"| node_xlsb_formula
node_loader -->|"normalizes"| node_document_model
node_document_model -->|"workbook snapshots"| node_excel_pipeline
node_document_model -->|"presentation snapshots"| node_ppt_pipeline
node_excel_pipeline -->|"Excel evidence"| node_package_crosscheck
node_ppt_pipeline -->|"PPT evidence"| node_package_crosscheck
node_excel_pipeline -->|"produces"| node_findings
node_ppt_pipeline -->|"produces"| node_findings
node_package_crosscheck -->|"produces"| node_findings
node_findings -->|"classifies"| node_triage
node_triage -->|"reviewable findings"| node_review
node_review -->|"synthesizes"| node_story
node_review -->|"renders"| node_reports
node_review -->|"persists"| node_history
node_history -.->|"restores lineage"| node_run_service
node_reports -.->|"sanitizes and attests"| node_privacy

click node_cli "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/cli.py"
click node_ui "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/ui/app.py"
click node_run_service "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/run_service.py"
click node_run_queue "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/runqueue.py"
click node_worker "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/worker.py"
click node_engine "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/engine.py"
click node_loader "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/loader.py"
click node_document_model "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/model.py"
click node_ooxml_parsers "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/ooxml_worksheet.py"
click node_decrypt "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/decrypt.py"
click node_xlsb_formula "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/xlsb_formula.py"
click node_excel_pipeline "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/excel/preflight.py"
click node_ppt_pipeline "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/ppt/extract.py"
click node_package_crosscheck "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/crosscheck/package.py"
click node_findings "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/findings.py"
click node_triage "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/triage/rules.py"
click node_review "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/review.py"
click node_story "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/story.py"
click node_reports "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/report/json_report.py"
click node_history "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/history/store.py"
click node_privacy "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/privacy.py"
click node_server_config "https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/server_config.py"

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_ui toneBlue
class node_run_service,node_run_queue,node_worker,node_engine toneAmber
class node_loader,node_document_model,node_ooxml_parsers,node_decrypt,node_xlsb_formula toneMint
class node_excel_pipeline,node_ppt_pipeline,node_package_crosscheck toneRose
class node_findings,node_triage,node_review,node_story,node_reports toneIndigo
class node_history,node_privacy,node_server_config toneTeal
```

## Components

### Local entry points

- [CLI](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/cli.py): command entry · `qc_tool/cli.py`
- [NiceGUI app](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/ui/app.py): local UI · Local interface for interactive and queued runs. · `qc_tool/ui/app.py`

### Run orchestration

- [Run service](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/run_service.py): lifecycle service · `qc_tool/run_service.py`
- [Run queue](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/runqueue.py): background queue · `qc_tool/runqueue.py`
- [Run worker](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/worker.py): background worker · `qc_tool/worker.py`
- [QC engine](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/engine.py): orchestrator · Infers mode, stages analysis, tracks coverage, and produces findings. · `qc_tool/engine.py`

### Read-only ingestion

- [Document loader](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/loader.py): read-only loader · `qc_tool/io/loader.py`
- [Normalized models](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/model.py): document model · `qc_tool/io/model.py`
- [OOXML parsers](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/ooxml_worksheet.py): worksheet/chart parser · Extracts worksheet, chart, and interaction structures. · `qc_tool/io/ooxml_worksheet.py`
- [Decryption boundary](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/decrypt.py): decryption adapter · Isolates protected-file handling before analysis. · `qc_tool/io/decrypt.py`
- [XLSB formula enrichment](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/io/xlsb_formula.py): platform adapter · Degrades coverage when formula semantics are unsupported. · `qc_tool/io/xlsb_formula.py`

### QC analysis

- [Excel QC pipeline](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/excel/preflight.py): workbook analyzer · Preflight, cadence regions, alignment, formula/value diffs, dependencies, and risk checks. · `qc_tool/excel/preflight.py`
- [PowerPoint QC pipeline](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/ppt/extract.py): presentation analyzer · Extracts, preflights, matches, and semantically compares slides. · `qc_tool/ppt/extract.py`
- [Package reconciliation](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/crosscheck/package.py): cross-document analyzer · Reconciles Excel and PowerPoint values and sources. · `qc_tool/crosscheck/package.py`

### Review and outputs

- [Findings and coverage](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/findings.py): QC domain model · `qc_tool/findings.py`
- [Triage rules](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/triage/rules.py): severity policy · Applies severity classification and analyst overrides. · `qc_tool/triage/rules.py`
- [Review state](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/review.py): analyst review · `qc_tool/review.py`
- [Change story](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/story.py): finding synthesis · `qc_tool/story.py`
- [Reports](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/report/json_report.py): JSON/HTML/Excel output · Generates reports from reviewed state. · `qc_tool/report/json_report.py`

### Local state and security

- [Run history](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/history/store.py): SQLite persistence · Stores runs, annotations, mappings, and re-QC lineage locally. · `qc_tool/history/store.py`
- [Privacy and evidence](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/privacy.py): local-only controls · Provides privacy, fingerprinting, attestation, and package sanitization. · `qc_tool/privacy.py`
- [Server exposure policy](https://github.com/rai-himanshu07/cadence-diff/blob/main/qc_tool/server_config.py): runtime security · Defaults the UI server to loopback and controls temporary LAN exposure. · `qc_tool/server_config.py`

## Connections

- CLI → Run service: starts run
- NiceGUI app → Run queue: queues work
- NiceGUI app → Server exposure policy: uses policy
- Run queue → Run worker: dispatches
- Run service → QC engine: executes
- Run worker → QC engine: executes
- QC engine → Document loader: loads inputs
- Document loader → Decryption boundary: handles protected files
- Document loader → OOXML parsers: parses OOXML
- Document loader → XLSB formula enrichment: enriches XLSB
- Document loader → Normalized models: normalizes
- Normalized models → Excel QC pipeline: workbook snapshots
- Normalized models → PowerPoint QC pipeline: presentation snapshots
- Excel QC pipeline → Package reconciliation: Excel evidence
- PowerPoint QC pipeline → Package reconciliation: PPT evidence
- Excel QC pipeline → Findings and coverage: produces
- PowerPoint QC pipeline → Findings and coverage: produces
- Package reconciliation → Findings and coverage: produces
- Findings and coverage → Triage rules: classifies
- Triage rules → Review state: reviewable findings
- Review state → Change story: synthesizes
- Review state → Reports: renders
- Review state → Run history: persists
- Run history → Run service: restores lineage
- Reports → Privacy and evidence: sanitizes and attests