beffroi-reporting/docs/vision.md

43 lines
2.4 KiB
Markdown

# 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](architecture.md) for the component boundaries and
[operations](operations.md) for the editing and publishing workflow. New
renderers follow the [Reportist plugin guide](../reporter/docs/plugins.md).