# Architecture ```mermaid flowchart LR S[Reports: YAML and raw JSON sources] --> M[Macro: beffroi.sh and publication build] M --> C[Reportist: build.sh] C --> R[Report plugin] C --> D[Diagnostic plugin] V[Shared visual elements and themes] --> R V --> D D --> A[Normalized evidence JSON, when requested] R --> P[PDFs] D --> P P --> Z[Macro: encrypted archives and Jenkins publication] ``` ## Component contracts **Reports** stores authored YAML reports in `reports/reports/` and raw WinDiagnostics JSON captures in `reports/diagnostics/`. The raw captures are source evidence for the diagnostic renderer. It has a small syntax checker and Jenkins job, but no plugin, analyzer, or visual asset. Source provenance is documented in `reports/docs/preserved-source.md`. **Reportist** is the rendering engine. Its public entry point is `reporter/build.sh`; see its [CLI contract](../reporter/docs/build-cli.md). `reporter/plugins/report/` interprets authored reports. `reporter/plugins/diagnostics/` interprets raw captures and, separately, produces normalized evidence JSON. These plugins have independent Typst models. Both import `reporter/visual/elements.typ` and use the palettes in `reporter/visual/themes.yaml`. `reporter/tools/render-common.sh` shares shell option, path, and temporary staging rules. Each renderer stages its own Typst model and resources so it can compile without the macro repository. **The macro repository** pins both components as submodules. `beffroi.sh` provides convenient commands for editing and checking one source. `scripts/build-publication.sh` builds all stored sources into a new staged publication and replaces an existing build only after rendering succeeds. `scripts/package-reports.sh` creates AES-encrypted `Reports.zip` and `Diagnostics.zip`. The root `Jenkinsfile` tests, builds, packages, archives, and publishes those archives from `main`. ## Data and output boundaries | Input or output | Format | Owner | | --- | --- | --- | | Authored report | YAML or JSON with fields defined by the report plugin | Reports content; Reportist interpretation | | Raw capture | WinDiagnostics JSON v1/v2 | Reports content; diagnostic plugin interpretation | | Normalized diagnostic | Diagnostic evidence JSON v1 | Diagnostic analyzer and validator | | PDF | Plugin-specific layout | Reportist renderer | | Publication directory and encrypted ZIPs | Batch artifacts | Macro repository | A normalized diagnostic is an evidence artifact. The diagnostic PDF is rendered from the raw capture, not from a report-shaped intermediate representation. Neither plugin is required to conform to the other's schema. New plugin kinds are routed explicitly in `reporter/build.sh`; there is no automatic registry. ## Verification `uv run --script reports/check_sources.py` checks the YAML and JSON source syntax. Reports CI runs this check on its own repository. `./beffroi.sh test` runs the component suites, a diagnostic analysis workflow, and a full publication build. The parity checker verifies the set of 17 PDFs, recorded text hashes, and page counts. When original PDFs and Poppler are available locally, it also compares rasterized pages. New plugins should add focused input/render tests; an approved existing output needs a regression oracle before its renderer is changed.