Reporting Module Boundary

govoplan-reporting owns report definitions, execution, dashboards, BI views, scheduled outputs, and report exports. It may use templates for formatted outputs, but it owns the report data and publication semantics.

The core boundary decision register is in /mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md.

Ownership

Reporting owns:

report definitions, parameters, saved views, and dashboard cards
curated query/view inputs from modules, connectors, datasources, or configuration packages
report execution history, generated output evidence, and scheduled runs
institutional question, goal/obligation, owner, calculation-version, freshness/quality, and decision/action-consumption references for each material report or indicator
report permissions and sharing rules
export targets such as file, DMS, mail, API, RSS/Atom publication, and downstream connector handoff
BI-style summaries where GovOPlaN owns the underlying process evidence

Source Inputs

Initial source categories:

module-owned read models and summary DTOs
curated SQL/query views exposed through a controlled capability
connector-staged datasets and external references
generated file/csv/xlsx inputs from files/connectors
governed govoplan-datasources catalogue entries and immutable materializations
versioned govoplan-dataflow outputs and run lineage

Reporting should not reach into module ORM internals directly. Module-owned data must be exposed through capabilities, DTOs, events, read models, or controlled query views.

Every reproducible report definition should retain or resolve:

the institutional question, obligation, goal, or service measure it serves;
owner and responsible organization/function;
datasource/materialization and Dataflow definition/run revisions;
source freshness, quality state, known limitations, and calculation version;
purpose, visibility, privacy, retention, and publication decisions;
reports, decisions, controls, projects, or actions that consumed the result.

Reporting owns execution and presentation of the measure. Mandates, Services, Projects, Risk Compliance, Decisions, and other domains retain ownership of the referenced institutional concepts.

Output Targets

dashboard/widget view
API result
downloadable file
stored file/DMS evidence
email attachment or link through mail
scheduled export
RSS/Atom/open-data publication through connectors
workflow/task notification when a report run needs review

Boundaries

Reporting does not own:

reusable template rendering; that belongs to govoplan-templates
DMS lifecycle, collaborative editing, legal hold, or records management
raw file/blob storage and provider connectors
ingestion, governed source identity, staging, or transformation pipeline ownership; those belong to Connectors, Datasources, and Dataflow
cross-module search indexing; that belongs to govoplan-search

Capability Contracts

reporting.registry owns immutable definition registration and lookup.
reporting.runner executes exact report graphs and returns governed result evidence.
reporting.scheduler claims due schedules and preserves run/publication outcomes.
reporting.chart_renderer renders provider-neutral visual models with an accessible table fallback.
reporting.read_model:* capabilities can expose bounded source-owned rows.
reporting.publication_target:* capabilities can accept immutable result payloads without Reporting importing the target module.

Implemented Vertical

The first complete vertical persists datasets, semantic models, reports, quality plans, grants, executions, saved views, schedules, publications, quality results, and import assessments. Each definition update creates an immutable revision and requires optimistic concurrency. Active child definitions require the exact pinned parent revision to be active.

Execution resolves the report, semantic model, and dataset graph before reading data. Static fixtures, Dataflow output, and provider-owned read models share one bounded read contract. Source fingerprints, freshness, schema, row-policy provenance, blocking quality plans, definition hashes, executor version, output hash, diagnostics, and authorized rows are retained with the execution. Failed runs also retain evidence.

The query engine deliberately implements a typed expression and semantic query language rather than eval, arbitrary SQL, stored procedures, or runtime scripts. It supports detail, grouped summary, pivot, dimensions, hierarchies, common aggregates, calculated measures, filters, sorting, pagination, totals, and a provider-neutral visualization model. A saved chart that is incompatible with an ad-hoc query degrades to its mandatory table fallback instead of failing a valid report run.

Direct export supports UTF-8 CSV and JSON. CSV cells that spreadsheet software could interpret as formulas are escaped. Additional formats and delivery destinations use an optional publication capability and preserve idempotent evidence. Import assessments classify exact, approximated, and unsupported semantics and block activation until every approximation is accepted and no unsupported executable behavior remains.

The WebUI uses the platform module loader and common controls. It exposes a report catalogue, parameter and semantic-query controls, result visualization and table views, history/provenance, saved views, schedules, and downloads.

Remaining Product Depth

The architecture boundary is implemented. Further work is additive product depth: richer visualization providers, drill-through navigation, packaged domain report catalogues, XLSX/PDF formatting through optional providers, and target-environment evidence for a maturity claim above vertical_slice.

5.7 KiB Raw Blame History