beffroi-reporting/docs/architecture.md

3.3 KiB

Architecture

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/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.