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