beffroi-reporting/docs/vision.md

2.4 KiB

Project vision

Beffroi Reporting turns reviewed source material into reproducible PDF reports. An authored report and a machine capture are different kinds of source; each gets a renderer that understands its own meaning and layout. They can share a visual language without sharing a forced document schema.

The three repositories

Repository Owns Does not own
Beffroi Reporting (macro) Editing workspace, pinned components, integration checks, publication staging, encrypted archives, deployment CI Report layouts or diagnostic rules
Beffroi Reports Authored YAML/JSON and raw diagnostic captures, with editorial provenance and syntax checks Executable rendering or analysis code
Reportist (reporter/ here) Standalone renderers, diagnostic analysis, validation, shared graphical elements, themes, plugin tests, and build.sh The production source collection or publication destination

A Reportist plugin owns its input format, interpretation, validation, and Typst document model. The report plugin and diagnostic plugin are peers. A future plugin may produce a document with a different structure; it should use shared visual elements where useful, but should not be translated into the report plugin's data shape simply to render.

The common surface is graphical: palettes, badges, pills, headings, panels, callouts, progress bars, and similar reusable elements in reporter/visual/. Plugin-specific composition remains in reporter/plugins/<name>/.

Working rules

  • Source content stays reviewable in text files. Generated PDFs and encrypted archives are build artifacts.
  • Typst handles structured data, interpretation, and page composition. Shell or Python handles directory traversal, input staging, hashes, atomic output, encryption, Git, and CI deployment.
  • A plugin must work from a standalone Reportist checkout. The macro checkout may call it, but must not be required by it.
  • Changes to existing renderers must preserve approved output. The current regression baseline covers seven authored reports and ten diagnostics.
  • The macro Jenkins pipeline is the publishing authority. Reportist's CI tests its own code; Reports CI checks source syntax without rendering.

See architecture for the component boundaries and operations for the editing and publishing workflow. New renderers follow the Reportist plugin guide.