From 720959536bc9e11443d09b89c28391525ff090c1 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 30 Jul 2026 18:19:22 +0200 Subject: [PATCH] docs(reporting): assess SuperX capability parity --- README.md | 4 +- docs/SUPERX_CAPABILITY_ASSESSMENT.md | 146 +++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 docs/SUPERX_CAPABILITY_ASSESSMENT.md diff --git a/README.md b/README.md index 9d3479d..300fb12 100644 --- a/README.md +++ b/README.md @@ -13,4 +13,6 @@ metadata and module manifests only after the first backend or WebUI slice is designed. See [docs/REPORTING_BOUNDARY.md](docs/REPORTING_BOUNDARY.md) for the boundary -decision. +decision. The behavior-level comparison with the supplied SuperX module set is +recorded in +[docs/SUPERX_CAPABILITY_ASSESSMENT.md](docs/SUPERX_CAPABILITY_ASSESSMENT.md). diff --git a/docs/SUPERX_CAPABILITY_ASSESSMENT.md b/docs/SUPERX_CAPABILITY_ASSESSMENT.md new file mode 100644 index 0000000..5cbeb80 --- /dev/null +++ b/docs/SUPERX_CAPABILITY_ASSESSMENT.md @@ -0,0 +1,146 @@ +# SuperX Capability Assessment + +## Scope + +The supplied SuperX directory contains 22 PostgreSQL module archives: + +`bau`, `cob`, `costage`, `erfolg`, `etl`, `fin`, `gang`, `gxstage`, `ivs`, +`kenn`, `kern`, `lm`, `man`, `msg`, `qa`, `rpta`, `sos`, `sva`, `sxc`, `viz`, +`xcube`, and `zul`. + +This is a behavior and architecture assessment. It uses archive metadata and +representative definitions to identify product capabilities; no SuperX source +code or visual assets are copied. + +## Functional Model + +The supplied modules collectively provide five relevant layers: + +1. **ETL orchestration:** parameterized jobs, ordered steps, dependencies, + load/select/native actions, continuation policy, and execution metadata. +2. **Domain data marts:** higher-education, finance, personnel, buildings, + applications, courses, success, and benchmark datasets with curated + reports. +3. **Semantic BI model:** cubes, dimensions, measures, hierarchies, totals, + labels, virtual calculated columns, and row/column arrangements. +4. **Presentation:** parameter masks, tables, pivots, charts, saved + visualizations, dashboard tabs, and formatted report products. +5. **Quality and operations:** assertions, comparison profiles, grouped + controls, execution logs, projects/issues, installation, and updates. + +## GovOPlaN Coverage + +| Capability | GovOPlaN state | Primary owner | +| --- | --- | --- | +| Governed source identity and frozen snapshots | Strong foundation | Datasources | +| External acquisition and credentials | Strong foundation | Connectors | +| Graph and SQL transformations | Strong foundation | Dataflow | +| Calculations, joins, ranking, aggregates | Available | Dataflow | +| Quality rules and keyed reconciliation | Available foundation | Dataflow | +| Durable scheduled/event/user runs | Available foundation | Dataflow/Core | +| Resumable approval and correction steps | Available foundation | Workflow | +| Scope inheritance and provenance | Available foundation | Policy/Core | +| Configurable dashboard widgets | Available foundation | Dashboard | +| Reusable parameterized subflows | Available foundation | Dataflow | +| BI dimensions, measures, and hierarchies | Missing | Reporting | +| Pivot/drill-down analytical view | Missing | Reporting | +| Parameterized report masks and saved views | Missing | Reporting | +| Chart renderer/provider contract | Missing | Reporting | +| Scheduled report publication/export | Partially modelled, not integrated | Reporting | +| Report-specific access explanations | Missing | Reporting/Policy | +| Data-quality test plans and evidence UI | Partial | Dataflow/Reporting | +| Packaged domain report catalogues | Missing | Reporting plus domain modules | + +GovOPlaN already has most platform primitives below the BI layer. The largest +gap is not another execution engine; it is a governed Reporting semantic layer +that turns curated Dataflow outputs and module read models into dimensions, +measures, parameterized views, pivots, charts, and publishable reports. + +## Recommended Architecture + +Reporting should consume only capability-published datasets or module read +models. It must not query another module's ORM tables directly. + +The minimum durable contracts are: + +- **Analytical dataset:** stable reference, schema, freshness, provenance, + scope, row-level policy hook, and supported query operations. +- **Semantic model:** dimensions, levels/hierarchies, measures, calculations, + labels, formats, totals, and default filters. +- **Report definition:** semantic-model revision, parameters, layout, + visualization, sort/filter state, and access policy. +- **Execution:** immutable definition revision, bound parameters, source + fingerprints, effective authorization, result summary, and diagnostics. +- **Publication:** target capability, format profile, retention, schedule, + delivery evidence, and idempotency key. +- **Contribution:** modules may announce report sources, semantic fragments, + templates, and dashboard widgets without Reporting importing them. + +PostgreSQL should remain the first execution target. Optional analytical or +search engines can be adapters later; report definitions must not depend on +one engine's private syntax. + +## Import Boundary + +A future SuperX importer may read declarative metadata for sources, +parameters, dimensions, measures, hierarchies, layouts, and report catalogues. +It must produce native GovOPlaN definitions, never retain executable SQL or +stored procedures as an unchecked runtime escape hatch. + +Every import result needs a machine-readable mapping report: + +- source object and stable source identifier +- generated GovOPlaN object and revision +- exact, approximated, omitted, and unsupported semantics +- required manual bindings or Policy decisions +- source dialect/provider assumptions +- warnings for custom functions, procedural code, implicit authorization, and + presentation behavior that has no native equivalent + +Unsupported semantics must block activation unless an administrator explicitly +accepts a documented approximation. Imported definitions remain ordinary +versioned GovOPlaN definitions after migration; the runtime must not depend on +the original SuperX installation. + +## Delivery Plan + +### Phase 1: Semantic Core + +- scaffold the Reporting module and manifest +- define analytical dataset, dimension, hierarchy, measure, parameter, and + report-definition schemas +- consume one Dataflow-published dataset through a capability +- enforce scope, Policy provenance, and source freshness + +### Phase 2: Interactive BI + +- parameter panel and saved views +- table, pivot, drill-down, totals, calculated measures, and export of the + currently authorized result +- stable URL/reference contract for report state +- dashboard contribution for saved reports + +### Phase 3: Visualization And Publication + +- chart renderer provider contract with an initial bounded chart catalogue +- scheduled runs and publication through Files, Mail, or another declared + target capability +- accessible tabular fallback and report-specific access explanations + +### Phase 4: Quality And Domain Packs + +- reusable report assertions and dataset comparison plans +- execution evidence and trend views +- versioned domain report packages owned by the relevant domain modules +- import tooling for metadata where licensing and semantic mapping permit it + +## Product Boundary + +Dataflow remains responsible for producing governed tabular datasets. +Reporting owns analytical semantics and presentation. Dashboard arranges +widgets but does not become the report engine. Workflow coordinates human +handoffs but does not own report execution. Templates format documents but do +not own report data or query semantics. + +The assessment and its implementation split are tracked by +[`govoplan-reporting#3`](https://git.add-ideas.de/GovOPlaN/govoplan-reporting/issues/3).