govoplan-reporting/docs/REPORTING_BOUNDARY.md

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.

Cross-module report providers

Source modules contribute aggregate or otherwise minimized reports through reporting.report_provider.<provider-id>. Core owns contract version 1.0 and the provider-neutral DTOs. A provider must declare stable report and revision IDs, typed parameters, the complete result schema, privacy transforms, retention class, export formats, and re-identification risk. It must enforce source access before listing options or producing a result and must return source revisions, effective tenant scope, applied transforms, generation time, and bounded provenance.

Reporting discovers these capabilities by prefix. It validates descriptors, rejects undeclared output fields, requires every mandatory transform, records purpose and effective audience, and persists immutable execution and export evidence. The optional policy.reporting_governance capability can tighten retention, export formats, required transforms, and high-risk handling. If Policy is absent, Reporting applies its restrictive built-in baseline and denies high-risk provider reports.

This direction is intentionally one-way: source modules import only Core's contract and remain usable when Reporting is absent. Reporting never imports the source module or reads its ORM tables.

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. The global /reports route is owned only by Reporting. /reporting is a documented compatibility path. Campaign's module-local aggregate view remains at /campaigns/reports; when both modules are enabled, the same safe aggregate projection is also contributed to the global catalogue through the provider contract.

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.