hledger-web-reports/docs/architecture.md

Architecture

The web reads saved reports. Explicit requests go through a private job queue to the worker, which runs hledger and saves the results.

Prepare request → journal check → hledger reports → complete saved set
Browse request  → one selected saved set → public page data
Live query      → worker → hledger → requested result

Hledger owns accounting. The adapter preserves exact values; storage publishes complete sets; the web exposes only the fields each page needs. Journal paths, source locations and other private metadata stay on the server.

A request keeps one saved set so navigation and page data agree. Recorded journal checks are separate from financial publication. Neither saved results nor a passed check proves that the journal has not changed.

Web and worker share configuration and private storage. The job queue and saved report generations use separate SQLite databases. Financial browsing does not depend on a running worker. Startup does not request preparation, though previously requested jobs can resume.

See development for commands and principles for how we change the code.