# 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.`. 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`.