GovOPlaN/govoplan
2
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Sync wiki from project files

zemion
2026-08-05 16:48:43 +02:00
parent a82e9dad01
commit 32866ad768
30 changed files with 2824 additions and 1078 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Codex-Project-Index.md
+13
@@ -5,25 +5,38 @@
This page is generated from repository and product-directory project files.
- [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan/README.md`
- [Repo-docs-ASSISTED-AND-NON-DIGITAL-CHANNELS](Repo-docs-ASSISTED-AND-NON-DIGITAL-CHANNELS) - `/mnt/DATA/git/govoplan/docs/ASSISTED_AND_NON_DIGITAL_CHANNELS.md`
- [Repo-docs-BACKUP-AND-RESTORE-EVIDENCE](Repo-docs-BACKUP-AND-RESTORE-EVIDENCE) - `/mnt/DATA/git/govoplan/docs/BACKUP_AND_RESTORE_EVIDENCE.md`
- [Repo-docs-CAPABILITY-AND-INFRASTRUCTURE-FIT](Repo-docs-CAPABILITY-AND-INFRASTRUCTURE-FIT) - `/mnt/DATA/git/govoplan/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`
- [Repo-docs-CONNECTED-GOVERNANCE-PLATFORM-ROADMAP](Repo-docs-CONNECTED-GOVERNANCE-PLATFORM-ROADMAP) - `/mnt/DATA/git/govoplan/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md`
- [Repo-docs-DATASOURCE-AND-DEFINITION-GRAPH-ARCHITECTURE](Repo-docs-DATASOURCE-AND-DEFINITION-GRAPH-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md`
- [Repo-docs-FEDERATED-GOVOPLAN-ARCHITECTURE](Repo-docs-FEDERATED-GOVOPLAN-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/FEDERATED_GOVOPLAN_ARCHITECTURE.md`
- [Repo-docs-FRONTEND-LAYOUT-PRINCIPLES](Repo-docs-FRONTEND-LAYOUT-PRINCIPLES) - `/mnt/DATA/git/govoplan/docs/FRONTEND_LAYOUT_PRINCIPLES.md`
- [Repo-docs-GITEA-ISSUES](Repo-docs-GITEA-ISSUES) - `/mnt/DATA/git/govoplan/docs/GITEA_ISSUES.md`
- [Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE](Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md`
- [Repo-docs-INSTITUTIONAL-DIGITAL-TWIN](Repo-docs-INSTITUTIONAL-DIGITAL-TWIN) - `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_DIGITAL_TWIN.md`
- [Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE](Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`
- [Repo-docs-INTERFACE-PATTERN-LANGUAGE](Repo-docs-INTERFACE-PATTERN-LANGUAGE) - `/mnt/DATA/git/govoplan/docs/INTERFACE_PATTERN_LANGUAGE.md`
- [Repo-docs-INTERFACE-SURFACE-INVENTORY](Repo-docs-INTERFACE-SURFACE-INVENTORY) - `/mnt/DATA/git/govoplan/docs/INTERFACE_SURFACE_INVENTORY.md`
- [Repo-docs-META-REPO-SCAN](Repo-docs-META-REPO-SCAN) - `/mnt/DATA/git/govoplan/docs/META_REPO_SCAN.md`
- [Repo-docs-META-REPOSITORY-MIGRATION-AUDIT](Repo-docs-META-REPOSITORY-MIGRATION-AUDIT) - `/mnt/DATA/git/govoplan/docs/META_REPOSITORY_MIGRATION_AUDIT.md`
- [Repo-docs-MODULE-CONTRACTS-AND-INSTALLS](Repo-docs-MODULE-CONTRACTS-AND-INSTALLS) - `/mnt/DATA/git/govoplan/docs/MODULE_CONTRACTS_AND_INSTALLS.md`
- [Repo-docs-PACKAGE-REGISTRY-RELEASES](Repo-docs-PACKAGE-REGISTRY-RELEASES) - `/mnt/DATA/git/govoplan/docs/PACKAGE_REGISTRY_RELEASES.md`
- [Repo-docs-PLATFORM-CONTROL-PLANE](Repo-docs-PLATFORM-CONTROL-PLANE) - `/mnt/DATA/git/govoplan/docs/PLATFORM_CONTROL_PLANE.md`
- [Repo-docs-PLATFORM-CORE-IDEAS](Repo-docs-PLATFORM-CORE-IDEAS) - `/mnt/DATA/git/govoplan/docs/PLATFORM_CORE_IDEAS.md`
- [Repo-docs-PRODUCT-EXPERIENCE-AND-MODULE-BOUNDARIES](Repo-docs-PRODUCT-EXPERIENCE-AND-MODULE-BOUNDARIES) - `/mnt/DATA/git/govoplan/docs/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md`
- [Repo-docs-PRODUCTION-TARGET-HANDOFF](Repo-docs-PRODUCTION-TARGET-HANDOFF) - `/mnt/DATA/git/govoplan/docs/PRODUCTION_TARGET_HANDOFF.md`
- [Repo-docs-README](Repo-docs-README) - `/mnt/DATA/git/govoplan/docs/README.md`
- [Repo-docs-RECOVERY-AND-ROLLBACK-GUARANTEES](Repo-docs-RECOVERY-AND-ROLLBACK-GUARANTEES) - `/mnt/DATA/git/govoplan/docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md`
- [Repo-docs-RECOVERY-LEDGER-ADOPTION](Repo-docs-RECOVERY-LEDGER-ADOPTION) - `/mnt/DATA/git/govoplan/docs/RECOVERY_LEDGER_ADOPTION.md`
- [Repo-docs-REFERENCE-JOURNEY-PROGRAM](Repo-docs-REFERENCE-JOURNEY-PROGRAM) - `/mnt/DATA/git/govoplan/docs/REFERENCE_JOURNEY_PROGRAM.md`
- [Repo-docs-RELEASE-CONSOLE](Repo-docs-RELEASE-CONSOLE) - `/mnt/DATA/git/govoplan/docs/RELEASE_CONSOLE.md`
- [Repo-docs-REPOSITORY-INDEX](Repo-docs-REPOSITORY-INDEX) - `/mnt/DATA/git/govoplan/docs/REPOSITORY_INDEX.md`
- [Repo-docs-REPOSITORY-STRUCTURE](Repo-docs-REPOSITORY-STRUCTURE) - `/mnt/DATA/git/govoplan/docs/REPOSITORY_STRUCTURE.md`
- [Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT](Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT) - `/mnt/DATA/git/govoplan/docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md`
- [Repo-docs-SECURITY-AUDIT](Repo-docs-SECURITY-AUDIT) - `/mnt/DATA/git/govoplan/docs/SECURITY_AUDIT.md`
- [Repo-docs-STRATEGIC-REVIEW-2026-08-05](Repo-docs-STRATEGIC-REVIEW-2026-08-05) - `/mnt/DATA/git/govoplan/docs/STRATEGIC_REVIEW_2026-08-05.md`
- [Repo-docs-STRATEGY-STATUS](Repo-docs-STRATEGY-STATUS) - `/mnt/DATA/git/govoplan/docs/STRATEGY_STATUS.md`
- [Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY](Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY) - `/mnt/DATA/git/govoplan/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md`
- [Repo-docs-TARGET-MATURITY-EVIDENCE-RUNBOOK](Repo-docs-TARGET-MATURITY-EVIDENCE-RUNBOOK) - `/mnt/DATA/git/govoplan/docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md`
- [Repo-docs-VIEWS-ARCHITECTURE](Repo-docs-VIEWS-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/VIEWS_ARCHITECTURE.md`
Repo-README.-.md
-241
@@ -1,241 +0,0 @@
<!-- codex-wiki-sync:28496fdfb2db07160032de9f -->
> Mirrored from `/mnt/DATA/git/govoplan/README.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# GovOPlaN
<!-- govoplan-repository-type:start -->
**Repository type:** system (meta).
<!-- govoplan-repository-type:end -->
[![Module Matrix](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/module-matrix.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=module-matrix.yml&actor=0&status=0)
[![Release Integration](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/release-integration.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=release-integration.yml&actor=0&status=0)
[![Deployment Installer](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/deployment-installer.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=deployment-installer.yml&actor=0&status=0)
[![Dependency Audit](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/dependency-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=dependency-audit.yml&actor=0&status=0)
[![Security Audit](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/security-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=security-audit.yml&actor=0&status=0)
This is the GovOPlaN meta repository. It is the operator entry point for
whole-product development, release orchestration, repository bootstrap, and
system-level Docker composition.
It is not a runtime module. Runtime behavior belongs to `govoplan-core` and the
installed modules/connectors discovered by core.
## Common Commands
Create the whole-product development virtualenv in this meta repository:
```sh
python3 -m venv .venv
./.venv/bin/python tools/repo/sync-python-environment.py --requirements requirements-dev.txt --python ./.venv/bin/python --upgrade-pip
```
The meta venv is the default Python environment for launch, check, release, and
Gitea tooling. `GOVOPLAN_VENV_ROOT` or `PYTHON` can override it for special
cases.
Start the development stack through the meta repository:
```sh
./tools/launch/launch-dev.sh
```
Open the WebUI in a browser after launch only when explicitly requested:
```sh
GOVOPLAN_OPEN_BROWSER=1 ./tools/launch/launch-dev.sh
```
Limit backend reload triggers during focused module work without changing the
enabled module graph:
```sh
GOVOPLAN_BACKEND_RELOAD_MODULES=calendar,campaign ./tools/launch/launch-dev.sh
```
Set `GOVOPLAN_BACKEND_RELOAD_MODULES=none` to watch only core/config sources.
Leaving it unset keeps the broad default and watches all enabled modules.
Start the shared development PostgreSQL service:
```sh
./tools/launch/start-dev-postgres.sh
```
Check which GovOPlaN repositories are present and dirty:
```sh
./tools/repo/repo-status.sh
```
Clone missing repositories listed in `repositories.json`:
```sh
./tools/repo/bootstrap-repositories.py
```
Update generated repository type notes in all READMEs:
```sh
./tools/repo/update-repository-type-notes.py
```
Regenerate the human-readable repository link index:
```sh
./tools/repo/generate-repository-index.py
```
Synchronize the Python environment after package metadata changes:
```sh
./.venv/bin/python tools/repo/sync-python-environment.py --requirements requirements-dev.txt --python ./.venv/bin/python
```
Run the static cross-repository module contract check:
```sh
./tools/checks/check-contracts.sh
```
Require backend, manifest, frontend, lockfile, and release-composition versions
to agree before a release:
```sh
./.venv/bin/python tools/checks/check-version-alignment.py --release-composition
```
Generate the CycloneDX dependency inventory from a resolved release environment:
```sh
./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python
```
For reproducible release artifacts, set `SOURCE_DATE_EPOCH` to the release
commit timestamp (or pass an explicit timezone-qualified `--timestamp`):
```sh
SOURCE_DATE_EPOCH="$(git -C ../govoplan-core show -s --format=%ct HEAD)" \
./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python
```
Run the consolidated focused verification suite:
```sh
./tools/checks/check-focused.sh
```
Run the cross-repository dependency boundary gate:
```sh
./tools/checks/check_dependency_boundaries.py
```
Run installer rollback drills:
```sh
./tools/checks/module-installer-rollback-drill.py --format json
```
Release, catalog, Gitea, security-audit, and cross-repository maintenance
commands should also be called from this repository through `tools/`.
Start the local release console:
```sh
./.venv/bin/python tools/release/release-console.py
```
Create and validate a private, declarative installation bundle:
```sh
./.venv/bin/python tools/deployment/govoplan-deploy.py init \
--directory ~/.local/share/govoplan/installations/default
./.venv/bin/python tools/deployment/govoplan-deploy.py doctor \
--directory ~/.local/share/govoplan/installations/default
```
The current executable slice and remaining production gates are documented in
[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md).
Same-host replica balancing and the multi-host promotion boundary are documented
in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md).
The recovery state machine, migration rollback boundary, and required restore
drills are documented in
[Recovery and Rollback Guarantees](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md).
## Configuration
The repository root `.env.example` is the self-hosted operator template for a
full GovOPlaN installation. Development profile examples live below `dev/`, for
example `dev/postgres/.env.example` and `dev/production-like/.env.example`.
Do not commit populated `.env` files. Gitea tokens should stay in a local file
such as `~/.config/gitea/gitea.env` and be passed with `--env-file`.
## Structure
The repository categories are documented in
`docs/REPOSITORY_STRUCTURE.md`. The machine-readable list lives in
`repositories.json`; the clickable human-readable index is
`docs/REPOSITORY_INDEX.md`.
Meta ownership and module install/contract boundaries are documented in
`docs/META_REPO_SCAN.md` and `docs/MODULE_CONTRACTS_AND_INSTALLS.md`.
Frontend layout principles for module pages are documented in
`docs/FRONTEND_LAYOUT_PRINCIPLES.md`.
The provider-neutral datasource boundary and reusable Dataflow/Workflow graph
contract are documented in
`docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md`.
The cross-product destination, stakeholder visions, configuration archetypes,
connected outcome stories, and capability horizons are documented in
the [Connected Governance Platform Roadmap](docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md).
The reconciled institutional semantics, source-authority modes, module layers,
candidate Mandates/Services/Parties/Decisions boundaries, and migration
sequence are documented in the
[Institutional Governance Target Architecture](docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
The selected Campaign-to-Postbox-to-data-to-collaboration implementation path,
including stage gates and shared documentation expectations, is in the
[Reference Journey Program](docs/REFERENCE_JOURNEY_PROGRAM.md).
The administrator journey from Core-only bootstrap through online module
installation, scale-out, and reversible environment promotion is defined in
[System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md).
The corresponding host deployment compiler, managed/external component choices,
reconfiguration semantics, and safe Web update boundary are defined in
[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md).
The concrete replica, worker-node, load-balancer, and shared-state topology is
defined in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md).
Durable deployment journals, Core recovery evidence, and the distinction
between pre-migration configuration restore and post-migration forward recovery
are defined in
[Recovery and Rollback Guarantees](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md).
The first Campaign-centric capability and infrastructure fit assessment is in
`docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. Its rerun tooling can collect and
verify a bounded installed composition; target, provider and production claims
remain separate, expiring attestations signed by independently scoped proof
authorities.
# GovOPlaN Docker
Whole-product Docker composition belongs in this meta repository.
Current module-specific Docker test beds remain in their owning repositories
until they are migrated or wrapped here:
- `govoplan/dev/postgres`
- `govoplan/dev/production-like`
- `govoplan-campaign/dev/mail-testbed`
- `govoplan-files/dev/connectors`
The target shape is:
- `govoplan/dev/postgres`: shared local development PostgreSQL service.
- `govoplan/dev/production-like`: production-like validation composition.
- module repositories keep only narrow connector or protocol test beds.
What doesn't belong here:
- `addideas-govoplan-website/docker-compose.yml`: public website serving
profile; this one stays with the website repository.
Repo-README.md
+22 -2
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:28496fdfb2db07160032de9f -->
<!-- codex-wiki-sync:30b3fe88cdb697b19a734447 -->
> Mirrored from `/mnt/DATA/git/govoplan/README.md`.
> Origin: `repository`.
@@ -77,6 +77,12 @@ Clone missing repositories listed in `repositories.json`:
./tools/repo/bootstrap-repositories.py
```
Gitea Actions jobs bootstrap the registered repositories over HTTPS and reuse
only the checkout job's short-lived authentication header. If registered
modules are private, allow the meta repository read access under
`GovOPlaN -> Settings -> Actions -> General -> Cross-Repository Access`; no
long-lived personal token is stored by the workflow or bootstrap tool.
Update generated repository type notes in all READMEs:
```sh
@@ -114,6 +120,18 @@ Generate the CycloneDX dependency inventory from a resolved release environment:
./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python
```
Synchronize module package workflows and inspect the registry release contract:
```sh
./.venv/bin/python tools/repo/sync-module-package-workflows.py --check
./.venv/bin/python tools/release/generate-release-package-set.py \
--output /tmp/govoplan-release-packages.json
```
Package publication, exact artifact locking, and the optional `govoplan`
developer meta-package are documented in
[Package Registry Releases](docs/PACKAGE_REGISTRY_RELEASES.md).
For reproducible release artifacts, set `SOURCE_DATE_EPOCH` to the release
commit timestamp (or pass an explicit timezone-qualified `--timestamp`):
@@ -215,7 +233,9 @@ The first Campaign-centric capability and infrastructure fit assessment is in
`docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. Its rerun tooling can collect and
verify a bounded installed composition; target, provider and production claims
remain separate, expiring attestations signed by independently scoped proof
authorities.
authorities. The operational issuance, target-run, recovery-measurement, key
custody, and promotion-gate procedure is in
[Target Maturity Evidence Runbook](docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md).
# GovOPlaN Docker
Repo-docs-ASSISTED-AND-NON-DIGITAL-CHANNELS.md
+174
@@ -0,0 +1,174 @@
<!-- codex-wiki-sync:e56a4f536cec72ce4b6382f1 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/ASSISTED_AND_NON_DIGITAL_CHANNELS.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Assisted and Non-Digital Channels
## Purpose
GovOPlaN must support people who cannot or do not use a self-service portal.
Telephone, paper, in-person service, authorized representation, mobile staff,
interpreters, and temporary offline work are not exceptional side systems.
They are governed channels into the same service, case, workflow, record, and
decision.
The goal is equivalent institutional treatment, not forced channel identity.
The system preserves which channel was used and which evidence is available
without giving digitally confident users stronger substantive rights.
The first end-to-end journey is tracked in
[GovOPlaN #42](https://git.add-ideas.de/GovOPlaN/govoplan/issues/42).
## Actor Model
Every assisted interaction distinguishes:
- the affected person or organization;
- the real staff member or external helper entering information;
- the represented party and representation basis;
- an interpreter, witness, guardian, or support person where relevant;
- the responsible institutional function;
- the channel and location;
- the person who reviewed or confirmed the captured information.
"Entered by" is not "declared by". "Declared by" is not "verified by".
Authentication assurance, representation authority, and evidence quality are
separate fields.
## Channel-Neutral Intake Contract
All channels create the same versioned service/form submission contract with
additional provenance:
- service, form, schema, language, and accessibility version;
- valid and recorded time;
- channel (`portal`, `counter`, `telephone`, `paper`, `email`, `mobile`,
`representative`, `offline_import`, or configured extension);
- affected and represented parties;
- capture actor and responsible function;
- consent, notice, purpose, legal basis, and information source;
- field-level source and confidence where staff transcribed or inferred data;
- attachments, scans, originals, signatures, recordings, and attestations as
governed evidence references;
- read-back/confirmation result and correction path;
- receipt and chosen return channels;
- duplicate/matching assessment and any manual resolution.
Forms Runtime owns the submission lifecycle. Parties owns procedural capacity
and representation. Identity/Addresses own subject and contact references.
Cases owns the matter. Records owns filing and retention. Audit preserves the
action/effect evidence.
## Assisted Session
An assisted session is a resumable work item, not a privileged bypass. It:
1. selects service, language, channel, affected party, and represented capacity;
2. shows the staff member only fields and evidence relevant to the service;
3. explains why sensitive data is requested and what evidence quality is
required;
4. records source per value when information comes from speech, paper, an
existing register, or staff observation;
5. validates and previews consequences before submission;
6. supports read-back, correction, confirmation, and a second-person check
where policy requires it;
7. generates an accessible receipt through the requested channel;
8. creates follow-up tasks when original documents, signatures, translation,
or verification remain outstanding.
The helper's normal account and represented function remain in the audit
chain. Assistance never grants access to unrelated records about the person.
## Paper And Scanning
- Register receipt before scanning so custody and deadlines do not depend on
successful OCR.
- Store the original scan or external archive reference with digest, pages,
capture device/provider, time, operator, and quality assessment.
- Treat OCR and extracted fields as derived data with confidence and source
coordinates. A person confirms consequential values.
- Support separation, ordering, missing-page, duplicate, malware, and
readability review.
- File the resulting document and submission into the appropriate eAkte;
retain or return the physical original according to policy.
- Produce cover sheets, barcodes, and return instructions through Templates,
not a separate print domain.
## Telephone And In-Person Handling
- Show a scripted but adaptable interview from the same Form definition.
- Record how identity and representation were checked; do not equate caller ID
with identity proof.
- Require explicit confirmation of consequential declarations and capture the
method (read-back, signed summary, one-time code, witness, later letter).
- Record call audio only when a lawful, declared profile permits it; an
interaction note is the default.
- Make interrupted sessions resumable without exposing prior answers to an
unauthorized caller or visitor.
## Offline And Mobile Work
Offline packages are encrypted, device-bound, time-limited, purpose-limited,
and contain only the required forms/reference data. Synchronization uses
idempotent intents and exposes conflicts rather than last-write-wins. Device
loss, expiry, revocation, duplicate submission, clock drift, and outcome
unknown have explicit recovery paths.
## Outbound Non-Digital Delivery
Campaign and Postbox model one delivery intent with channel choices and policy:
- portal/postbox delivery;
- email;
- print and postal fulfillment through a managed provider or local handoff;
- in-person collection;
- telephone notification followed by durable confirmation;
- accessible or language-specific variants.
Distribution preferences are purpose- and service-specific, effective-dated,
and may be overridden only by a documented legal or urgent-delivery rule. A
fallback occurs only before a channel has accepted the effect unless policy
explicitly authorizes duplicate delivery. Receipts distinguish creation,
provider acceptance, dispatch, delivery, return, and acknowledgement.
## Accessibility And Equality
- The person can request language, easy-language, large-print, screen-reader,
sign-language, relay, interpreter, or representative support without those
preferences becoming a general-purpose profile visible everywhere.
- Staff interfaces support keyboard-only capture, clear focus, error summary,
read-back, and printable/offline alternatives.
- Channel choice and need for assistance must not be used as an adverse risk
signal.
- Reports compare completion, wait, correction, abandonment, and outcome by
channel only under a declared equality/service-quality purpose and with
privacy thresholds.
## Security And Abuse Controls
- purpose-aware field access and session timeout;
- current authority checks for every read and effect;
- dual control for high-risk identity, payment, address, or representation
changes;
- immutable source/attestation evidence and correction history;
- rate and anomaly controls that do not silently reject a person;
- explicit safe handling of domestic-abuse, protected-address, witness, or
sealed-record cases;
- no secret answers or full documents in ordinary operational logs.
## First Reference Journey
Implement the permit-to-payment/service-to-decision journey through three
equivalent starts:
1. self-service portal submission;
2. staff-assisted counter/telephone submission;
3. paper receipt, scan, extraction, confirmation, and filing.
All three must create the same Case and Workflow contract, preserve different
provenance, support correction, produce a receipt, file an eAkte, reach the same
decision rules, and prove accessibility, privacy, recovery, and channel
fallback in browser and operator tests.
Repo-docs-BACKUP-AND-RESTORE-EVIDENCE.md
+140
@@ -0,0 +1,140 @@
<!-- codex-wiki-sync:c747fa4a6d3bc25195a0c00b -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/BACKUP_AND_RESTORE_EVIDENCE.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Backup And Restore Evidence
## Boundary
`govoplan-deploy` verifies backup and restore evidence; it does not receive
database, object-store, KMS, or orchestrator administration credentials and it
does not create the backup. A provider-owned backup controller creates one
coordinated recovery point, a separate drill runner restores it into an
isolated target, and an evidence authority signs the resulting receipt.
The application containers receive only a sanitized projection: evidence,
recovery-point and drill identifiers, hashes, timestamps, component count, and
measured RPO/RTO. Artifact locations, provider credentials, encryption-key
references, the public trust keyring, and private signing keys remain in the
deployment/evidence boundary.
The machine-readable contracts are:
- [`backup-evidence.schema.json`](backup-evidence.schema.json);
- [`backup-evidence-keyring.schema.json`](backup-evidence-keyring.schema.json).
One evidence document is bound to the installation id, deployment profile,
topology subject, exact signed release manifest, image digests, and composition
digest. It covers PostgreSQL, objects, protected configuration, and recoverable
key custody at one recovery point. It contains references, never key material.
## Production Sequence
1. Establish the provider snapshot, application quiesce, or transaction
boundary and retain a hash of its fencing token.
2. Capture PostgreSQL, object storage, protected deployment configuration, and
key-custody state within five minutes of that recovery point.
3. Restore all four components into a target isolated from production write
endpoints and production queues.
4. Start the exact immutable release named in the evidence, verify migration
heads, verify a deterministic manifest of representative object hashes, and
execute the documented semantic journey checks.
5. Record actual data loss and elapsed recovery as measured RPO and RTO. A
measured RPO above the declared objective invalidates the evidence.
6. Sign the canonical receipt using an evidence-authority Ed25519 key held
outside the application and deployment host. During key rotation, include
both accepted signatures.
7. Transfer the evidence SHA-256 through an independent approved channel, then
verify and adopt it on the deployment host.
Provider automation can sign and validate an unsigned receipt with:
```sh
python tools/deployment/sign-backup-evidence.py \
--input unsigned-backup-evidence.json \
--output backup-evidence.json \
--trusted-keyring backup-evidence-keyring.json \
--signing-key backup-authority-2026=/run/keys/backup-authority.pem
```
The private key file must be owner-only. The tool refuses an unexpected key
type, an inactive/untrusted signer, malformed or partial evidence, stale
recovery points, failed drill checks, mismatched releases, and non-canonical
output.
Adopt the result using the independently obtained digest:
```sh
python3 govoplan-deploy.pyz verify-backup \
--directory /srv/govoplan/default \
--evidence ./backup-evidence.json \
--evidence-sha256 "$APPROVED_BACKUP_EVIDENCE_SHA256" \
--trusted-keyring ./backup-evidence-keyring.json \
--adopt
```
Evidence is fresh for at most 24 hours and may declare an earlier expiry. Every
self-hosted release identity change is conservatively treated as a migration
boundary. `doctor`, Compose `apply`, and `render-kubernetes` fail closed when
fresh evidence for the previously applied immutable release is unavailable.
Compose verifies once before changing runtime state and again after API/worker
quiescing immediately before migration. The exported Kubernetes migration Job
is generated only after verification and is annotated with the sanitized
evidence digest, recovery-point id, and drill id.
## Provider Runbooks
### PostgreSQL
Use a managed transaction-consistent snapshot or a base backup plus retained
WAL sufficient to reconstruct the declared point. Record the provider,
protected artifact reference and digest, snapshot identity, and PostgreSQL LSN.
The restore drill must connect only to the isolated database and must compare
the resulting migration-head digest with the release expectation.
### Object Storage
Use provider snapshots/versioning or an immutable object copy. Build a sorted
manifest containing object key, version, size, and content digest, then record
its digest, object count, total bytes, provider version identity, and protected
artifact reference. Verify representative objects from every owning module
after restore. Single-node managed Garage is persistent but not highly
available; copy its coordinated recovery material to an independent failure
domain.
### Configuration And Key Custody
Back up the private installation bundle and external secret-manager bindings as
an encrypted artifact. Record only its reference and digest. For KMS/HSM/vault
state, record the provider keyset reference, version, and a successful
recoverability assertion. Never put a key, recovery share, token, password, or
credential-bearing URL in evidence. The isolated drill must prove that the
restored release can decrypt representative protected content without
exporting the key material into the report.
## Ownership And Retention
The deployment owner approves the RPO/RTO objectives. State-service owners
operate backup capture and restoration. Module owners define representative
objects and semantic checks. Security owns evidence-authority keys and
revocation. Operations schedules drills and retains sanitized status.
Retain backup artifacts for the approved legal/operational period and at least
through the release's rollback window. Retain signed evidence, drill reports,
and deletion receipts for the audit period. Disposal must remove every backup
copy and provider version according to policy, then revoke or retire references
without deleting the audit receipt. Cryptographic erasure is valid only when
key-destruction evidence and provider-copy coverage are independently proven.
## Failure Handling
Missing components, component-time skew, stale or expired evidence, revocation,
signature/key mismatch, changed stored files, release mismatch, failed semantic
checks, or an RPO breach block migration. The deployment journal records the
rejection without private provider details. If migration has not started, the
operator may supply fresh evidence and retry. Once migration starts, recovery
is explicitly forward-only until the verified coordinated recovery point is
restored with its matching release.
Repo-docs-CAPABILITY-AND-INFRASTRUCTURE-FIT.md
+31 -3
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:e4b2c1763e740cebf64cba2a -->
<!-- codex-wiki-sync:05dd9f01bfdccdd1013720cc -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`.
> Origin: `repository`.
@@ -7,6 +7,12 @@
---
# GovOPlaN Capability and IT-Infrastructure Fit Assessment
> **Pinned historical evidence:** This document assesses the exact 2026-07-22
> Campaign composition below. It is intentionally not updated to describe later
> main-branch work. Use [Strategy Status](STRATEGY_STATUS.md) for the current
> cross-product reconciliation and create a new dated fit assessment for a new
> target composition.
## Assessment record
| Field | Value |
@@ -26,8 +32,8 @@
Datasources, Dataflow, Search, encryption contracts, and other later main-branch
work must not be inferred into this evidence record. The current product
direction and implemented-state reconciliation are documented separately in
the
[Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
the [Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md)
and [Strategy Status](STRATEGY_STATUS.md).
This is a fit assessment, not a production approval or security certification.
It deliberately does not infer implementation from a repository, issue, or
@@ -510,6 +516,20 @@ Signatures cover UTF-8 JSON with the `signatures` member omitted, object keys
sorted, compact `,`/`:` separators and non-ASCII characters escaped, matching
the tool's deterministic canonicalization.
`tools/assessments/boundary-evidence.py` is the bounded issuance path. It
accepts a private target-run manifest conforming to
[`capability-fit-boundary-run.schema.json`](capability-fit-boundary-run.schema.json),
hashes each retained result file without following a final-component symlink,
and excludes all paths and raw results from the signed receipt. Issuance is
refused unless an independently trusted catalog, exact installed payload,
signed installer receipt, and role-scoped installer authority already pass.
Every claim must be covered by a supplied Ed25519 private key whose public key
is authorized for the full proof interval; catalog and installer key reuse is
rejected. The command immediately verifies its own result and atomically writes
both the proof and a sanitized review. The complete operator procedure and
recovery measurement definition are in
[`TARGET_MATURITY_EVIDENCE_RUNBOOK.md`](TARGET_MATURITY_EVIDENCE_RUNBOOK.md).
```bash
./.venv/bin/python tools/assessments/capability-fit.py \
--public \
@@ -520,6 +540,14 @@ the tool's deterministic canonicalization.
--expected-external-provider-subject provider-production
```
Promotion automation must opt into its required boundaries. Add
`--require-reference-readiness` to require all six target scopes,
`--require-external-provider-proof` when the product depends on a provider, and
`--require-production-approval` for production admission. These switches turn
missing, expired, revoked, mismatched, negative, or otherwise unchecked claims
into a blocking exit status rather than merely reporting them as an unproven
boundary.
With `--installed-evidence`, this command performs comparison and proof-binding
diagnostics. Without an installer receipt, the imported document remains
unsigned, so neither it nor the boundary claim becomes accepted proof. Direct
Repo-docs-CONNECTED-GOVERNANCE-PLATFORM-ROADMAP.md
+12 -72
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:10ef9837ec50eeee66215092 -->
<!-- codex-wiki-sync:d16e5c0b80ce3e913a3710bd -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md`.
> Origin: `repository`.
@@ -25,7 +25,8 @@ Read it together with:
- the [institutional governance target architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md)
- the [selected reference-journey program](REFERENCE_JOURNEY_PROGRAM.md)
- the [current capability and infrastructure fit assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md)
- the [current strategy status](STRATEGY_STATUS.md)
- the [pinned Campaign capability and infrastructure fit assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md)
- the [interface pattern language](INTERFACE_PATTERN_LANGUAGE.md)
- the [interface surface inventory](INTERFACE_SURFACE_INVENTORY.md)
- the [module contract and install model](MODULE_CONTRACTS_AND_INSTALLS.md)
@@ -48,8 +49,8 @@ Read it together with:
- Use [Near-term portfolio order](#near-term-portfolio-order) for the bridge to
implementation and [Product decisions](#product-decisions-to-make-progressively)
for choices that can remain deferred.
- Use the [dated snapshot appendix](#snapshot-appendix-2026-07-20) only to
understand which live backlog and release facts informed this revision.
- Use the [dated strategic review](STRATEGIC_REVIEW_2026-08-05.md) to understand
why the current convergence and reference-journey order was chosen.
### Planning ownership
@@ -57,7 +58,7 @@ Read it together with:
| --- | --- |
| What product should GovOPlaN become, for whom, in which configurations, and through which outcome horizons? | This meta roadmap |
| Which module owns a capability, which technical wave should deliver it, and what implementation gates apply? | The Core master roadmap and owning-module concepts |
| What is actively planned, blocked, implemented, or closed now? | Gitea issues |
| What is actively planned, blocked, implemented, or closed now? | Gitea issues and the dated reconciliation in `STRATEGY_STATUS.md` |
| What can a named composition credibly claim in a target environment? | A dated capability/infrastructure fit assessment |
The horizons and near-term order below express product outcomes and portfolio
@@ -1358,71 +1359,10 @@ language, what service it configured, who can act, which systems participate,
what happens when they fail, how a decision can be reviewed, and where the
evidence remains—and the product can prove that explanation at runtime.
## Snapshot appendix: 2026-07-20
## Dated Context
This appendix records volatile facts that informed this revision. It is not a
second source of truth and should be refreshed or removed when a later roadmap
review uses a new release/backlog snapshot.
### Composition and release snapshot
The cross-repository contract scan found 43 module manifest contracts, 29
provided interface names, 16 requirements, and no contract error across 65
scanned repositories. That is meaningful composition evidence, but the release
metadata trailed the integrated code: Core, Policy, Poll, and Scheduling
declared `0.1.9` while the whole-product release requirements remained on
module tag `v0.1.8`; the root self-hosted `.env.example` and release smoke
composition did not yet exercise all installed release modules. Other
development compositions already included some of those modules. This was a
release/composition gap, not evidence that the underlying slices did not exist.
### Backlog snapshot
The Gitea audit found 206 open issues across 36 of 66 catalogued repositories
and 362 closed issues. Campaign had 51 open issues and Core 44; together they
held 46% of current work. This reflected substantial completed kernel,
security, and platform work and a deliberate concentration on the first usable
vertical, but also risked crowding out production evidence and the shared
process spine.
The issue workflow needed a reconciliation pass before another delivery
program could be inferred from labels: 119 open issues remained in triage, 116
had no milestone, and several recently pushed Calendar, Scheduling, Poll,
Campaign, and Files slices still described themselves as local or awaiting
integration. Conversely, 30 repositories had no open issue; for many
later-wave modules this meant no implementation program had been opened, not
that the capability was complete.
[Poll #2](https://git.add-ideas.de/GovOPlaN/govoplan-poll/issues/2) was a clear
tracker-drift example: its configurable transition engine, agreed transition
matrix/history, idempotent keyed retries, re-decision audit, archive/unarchive,
and preservation behavior were implemented and pushed while the issue still
reported `needs-info`.
Issue anchors that informed the bridge from the baseline into this roadmap:
- [Meta #10](https://git.add-ideas.de/GovOPlaN/govoplan/issues/10) for the
capability/infrastructure assessment and its target proof;
- [Meta #11](https://git.add-ideas.de/GovOPlaN/govoplan/issues/11) for the
universal interface and focused-view direction;
- [Core #225](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/225) for
guided, safe configuration;
- [Core #29](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/29) for the
backup/restore production gate;
- [Core #263](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/263) and
[Campaign #63](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/63),
[#62](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/62),
[#65](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/65), and
[#69](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/69) for the
reference interface/delivery vocabulary and behavior;
- [Poll #1](https://git.add-ideas.de/GovOPlaN/govoplan-poll/issues/1) for the
database-enforced respondent invariant exposed by Scheduling;
- [Connectors #6](https://git.add-ideas.de/GovOPlaN/govoplan-connectors/issues/6)
for the governed connector configuration/simulation foundation;
- [Meta #9](https://git.add-ideas.de/GovOPlaN/govoplan/issues/9) for the first
permit-to-payment reference process; and
- [Meta #12](https://git.add-ideas.de/GovOPlaN/govoplan/issues/12) for the
deliberately deferred, consumer-independent export-control story.
Live Gitea issue state remains canonical. These dated facts explain the roadmap
sequence only.
The volatile release and backlog appendix that originally accompanied this
roadmap has been removed so the durable direction cannot become a competing
status source. The [Strategic Review 2026-08-05](STRATEGIC_REVIEW_2026-08-05.md)
retains the dated assessment and reasoning. Current reconciliation belongs in
[Strategy Status](STRATEGY_STATUS.md), and live work state belongs in Gitea.
Repo-docs-FEDERATED-GOVOPLAN-ARCHITECTURE.md
+162
@@ -0,0 +1,162 @@
<!-- codex-wiki-sync:6447a5bdd9594a6ea951e1a9 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/FEDERATED_GOVOPLAN_ARCHITECTURE.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Federated GovOPlaN Architecture
## Purpose
Federation lets autonomous GovOPlaN installations exchange data,
configuration, work, messages, records, and evidence without sharing a database
or surrendering local policy. It is institution-to-institution cooperation,
not multi-tenancy across an untrusted network.
The first implementation should prove a bounded exchange between two
installations. A new federation module is not justified until the shared
protocol has at least two independent consumers. Core owns neutral envelopes
and trust contracts; Connectors owns transport providers; domain modules own
the objects and effects they exchange.
Implementation is tracked in
[GovOPlaN #41](https://git.add-ideas.de/GovOPlaN/govoplan/issues/41).
## Invariants
1. Every installation remains authoritative for its tenants, identities,
policies, keys, records, and local mappings.
2. A remote identity or permission never becomes a local authorization claim.
3. Every exchange declares purpose, legal/organizational basis, classification,
minimization, retention expectation, and permitted onward use.
4. Every object reference identifies origin instance, owner tenant, object type,
object ID, exact revision, and source-authority mode.
5. Payloads and receipts are signed; sensitive transports use mutually
authenticated encrypted channels.
6. Acceptance, rejection, outcome unknown, retry, revocation, correction, and
reconciliation are durable states.
7. Local policy may reject or narrow a remote request. It cannot silently claim
to have accepted an effect that did not occur.
8. Federation works asynchronously and can exchange signed offline bundles
where continuous connectivity is unavailable.
## Trust Domains
An instance publishes a signed, versioned federation descriptor containing:
- stable instance and operator identity;
- supported protocol and schema versions;
- signing and transport key identifiers with rotation history;
- accepted object and exchange profiles;
- endpoint locations and size/rate limits;
- support, incident, revocation, and data-protection contacts;
- evidence and conformance references.
Pairing is a two-sided administrative workflow. Each side verifies the other,
maps the remote institution to a local trusted-party record, selects permitted
profiles and purposes, sets policy ceilings, and records approvals. Trust is
directional and profile-specific; trusting signed Postbox delivery does not
automatically permit case transfer or configuration import.
## Exchange Envelope
Every request, response, receipt, correction, and revocation uses one neutral
envelope with:
- message ID, correlation ID, causation ID, creation and expiry;
- origin and destination instance/institution/tenant references;
- real actor and represented institutional capacity where disclosure is
permitted;
- exchange profile and semantic schema version;
- exact domain object references and content digests;
- purpose, legal basis, classification, data categories, retention expectation,
onward-transfer constraint, and subject notice status;
- requested action and idempotency key;
- encryption recipients and signature chain;
- attachment/object manifests rather than unbounded embedded blobs;
- previous-envelope references for correction, replacement, or revocation.
The envelope is evidence, not a universal domain object. Each owner validates
and imports or links its own payload.
## Exchange Profiles
| Profile | First owners | Behavior |
| --- | --- | --- |
| Postbox delivery | Postbox, Campaign, Notifications | Address or derive a remote function-bound postbox, obtain acceptance receipt, and track acknowledgement where permitted |
| Case handoff | Cases, Parties, Services, Workflow Engine | Offer exact context and evidence; destination accepts into a new local case and returns the mapping |
| Record transfer | Records, Files, DMS, Audit | Transfer or offer a signed record package with file-plan, metadata, content digests, holds, and disposition constraints |
| Decision/evidence reference | Decisions, Committee, Audit | Publish a protected exact outcome or verifiable reference without transferring unrelated case content |
| Data product publication | Datasources, Dataflow, Reporting | Publish immutable governed materializations with schema, quality, freshness, lineage, and use constraints |
| Configuration package | Core, Policy, Views, Workflow, Forms, Templates | Exchange signed definitions; destination assesses compatibility, maps values, derives locally, and never imports secrets |
| Search discovery | Search and domain providers | Return permission-filtered metadata or a handoff link; never expose raw remote indexes as local authority |
## State Machine
```text
draft -> authorized -> queued -> transmitted -> received
| |
v v
outcome_unknown rejected
|
received -> validating -> accepted -> applied -> acknowledged
| | |
v v v
rejected accepted_ reconciled
pending
```
Acceptance means the destination durably owns the received intent. It does not
mean the requested domain effect completed. Receipts distinguish transport,
validation, acceptance, application, and human acknowledgement.
## Conflict And Autonomy
- Incoming native objects become local references, mirrors, or newly owned
objects according to the profile. They do not overwrite local authority by
ID coincidence.
- Local mappings are effective-dated and auditable.
- Corrections create a linked revision. They do not erase what the destination
previously observed.
- Revocation is a request and evidence event; the destination applies its own
legal and retention rules.
- Configuration imports use assessment and derivation. A remote package cannot
weaken local policy or install code implicitly.
- A disconnected partner remains a visible pending/failed state; work can be
rerouted through an approved alternative channel.
## Security And Privacy
- Use mTLS for paired online transports and signed envelopes for end-to-end
origin evidence.
- Encrypt payload objects for the destination, with key rotation and outcome-
unknown recovery; transport encryption alone is insufficient for queued
bundles.
- Do not put bearer credentials, local permission scopes, or reusable secrets
in an exchange.
- Rate-limit and size-bound discovery and transfer; quarantine unknown schemas
and active content.
- Evaluate current local authorization at every effect even when the envelope
describes historical authority.
- Log metadata separately from protected content so operators can reconcile
without broad content access.
- Subject access, correction, restriction, legal hold, and deletion requests
become federated workflows with local decisions and receipts, not remote
direct database operations.
## First Reference Proof
1. Pair two disposable installations with independent tenants, keys, and
policies.
2. Exchange signed descriptors and approve only the Postbox delivery profile.
3. Deliver one Campaign message to a remote function-bound Postbox.
4. Prove replay safety, rejection, timeout/outcome unknown, retry,
acknowledgement, correction, key rotation, and revoked trust.
5. Export the complete evidence bundle and restore both sides from backup.
6. Add configuration-package exchange only after the delivery proof passes.
The result is a provider-neutral federation contract. A future dedicated
module becomes appropriate only when pairing, trust administration, exchange
queues, and evidence have a lifecycle independent of Connectors and the first
domain owner.
Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md
+204 -36
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:1e4a0a14da7f197bb96cac2c -->
<!-- codex-wiki-sync:73c59ee131999a55b03ed4c0 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md`.
> Origin: `repository`.
@@ -98,8 +98,15 @@ The private installation directory contains:
| `compose.json` | Deterministic generated Compose definition |
| `garage.toml` | Non-secret managed Garage server configuration |
| `load-balancer.cfg` | Non-secret HAProxy WebUI/API discovery configuration |
| `Caddyfile` | Non-secret managed-ingress route and ACME policy |
| `existing-proxy.json` | Exact upstream, trusted-source, header, and health contract for an operator-owned proxy |
| `plan.json` | Latest desired-state diff and readiness findings |
| `receipt.json` | Last successfully applied immutable identities |
| `distribution-manifest.json` | Canonical signed runtime/image selection adopted by the installer |
| `distribution-keyring.json` | Explicitly installed public trust anchor for runtime releases |
| `backup-evidence.json` | Signed provider-neutral coordinated backup and isolated-restore receipt |
| `backup-keyring.json` | Explicit public trust anchor for backup evidence authorities |
| `backup-verification.json` | Sanitized local verification/adoption receipt |
| `applied-state/` | Checksum-verified snapshot of the last healthy deployment bundle |
| `operations/<id>/` | Private hash-chained deployment progress and recovery evidence |
| `kubernetes.json` | Optional stateless multi-host Kubernetes export |
@@ -135,30 +142,125 @@ Those images must already contain the selected module set. The override exists
only to exercise local orchestration before release artifacts exist; it is
rejected for `self-hosted`.
## Runtime Distribution Boundary
The protected `Runtime Distribution` workflow builds GovOPlaN wheels first,
resolves architecture-specific third-party wheels into offline wheelhouses, and
then assembles the API images with `pip --no-index`. The target host never
clones Git repositories and neither runtime image performs network package
installation. Separate amd64/arm64 API and WebUI images are joined into OCI
indexes and run as non-root identities. The release assets include CycloneDX
application SBOMs, SLSA-style provenance, exact composition evidence, the
single-file deployer, its detached Ed25519 signature, and a signed, expiring
distribution manifest. Evidence generation and signing run through the
workflow's isolated release Python environment so their cryptographic tooling
is explicit and independent of packages preinstalled in the Actions runner.
The API image points Core at the migration scripts installed from the verified
wheel under `/opt/govoplan/runtime/govoplan_core_runtime`; migrations therefore
do not depend on a source checkout or the build host's Python installation
scheme.
Before publication, the exact amd64 and arm64 image manifests each run release
migrations against the pinned PostgreSQL image, reach API and WebUI readiness
as non-root/read-only processes, and complete a task through the pinned Redis
image and packaged worker. Sanitized per-platform smoke receipts are retained
as immutable release assets.
PostgreSQL and Redis indexes are resolved to untagged platform-child digests
before each smoke run. This keeps the evidence architecture-specific and
avoids retargeting one local Docker tag between incompatible platforms.
The CI host registers arm64 execution with an explicitly supplied,
digest-pinned `tonistiigi/binfmt` image immediately before the smoke. This
privileged helper is confined to the release runner and is never part of a
GovOPlaN target deployment or its runtime image set.
Because QEMU user-mode execution triggers Redis's arm64 host-kernel COW guard,
the arm64 smoke suppresses only `ARM64-COW-BUG` while persistence, snapshots,
and append-only files are disabled. Target Redis services never inherit this
test-only option.
The smoke also proves a bounded post-migration table contract and aborts as
soon as a required container exits, rather than allowing a dead process to
consume the full readiness timeout.
Ingress acceptance streams generated configuration into Docker-managed
volumes before starting the read-only containers. It therefore also works when
an Actions job reaches a host or remote Docker daemon through a mounted socket;
the drill never assumes that a job-container path is visible to that daemon.
The drill allocates explicit loopback-only host ports and verifies Docker's
host binding configuration, avoiding daemon-specific random-port shorthand
behavior. Because an Actions job and deployment containers may be Docker
siblings, functional HTTP/TLS checks run from the digest-pinned API image on
the deployment network instead of assuming the Docker host is job-local.
The dispatch-only `Runtime Ingress Drill` workflow exposes the same bounded
check independently so ingress changes can be diagnosed before an immutable
runtime publication; it accepts only digest-pinned Caddy, HAProxy, and API
images and has no push trigger.
The official Caddy binary carries the `NET_BIND_SERVICE` file capability. The
managed-ingress container therefore drops every capability and adds back only
`NET_BIND_SERVICE`; otherwise Linux rejects the binary at `execve` before its
high-port configuration can start. `no-new-privileges`, a read-only root
filesystem, and non-privileged container ports remain enforced.
The bounded setup helper writes only generated public configuration as root so
it can initialize a new volume; the actual HAProxy process retains the image's
non-root identity and runs read-only with all capabilities dropped.
The manifest contract is
[`runtime-distribution-manifest.schema.json`](runtime-distribution-manifest.schema.json),
and its separately distributed trust-anchor contract is
[`runtime-distribution-keyring.schema.json`](runtime-distribution-keyring.schema.json).
Publication is immutable: an existing Gitea release asset must have the same
size and SHA-256 digest or publication fails.
Adopt a downloaded or prefetched release only after obtaining the manifest
digest and trusted keyring through the documented independent channel:
```sh
python3 govoplan-deploy.pyz verify-release \
--directory /srv/govoplan/installation \
--manifest ./distribution-manifest.json \
--manifest-sha256 "$(cut -d' ' -f1 distribution-manifest.json.sha256)" \
--trusted-keyring ./distribution-keyring.json \
--adopt
```
`doctor` and `apply` rehash both stored files, re-run OpenSSL Ed25519
verification, enforce channel/expiry/revocation, compare every selected image,
and prove that all enabled module ids occur in the signed image composition.
An offline image index can bind prefetched OCI archives to the same exact image
references and archive hashes; mutable tags or incomplete bundles are rejected.
## Current Production Gates
The tool deliberately reports blockers instead of pretending the source tree is
a production distribution:
The first immutable production-distribution baseline is published as
[`v0.1.14`](https://git.add-ideas.de/GovOPlaN/govoplan/releases/tag/v0.1.14)
from source commit `1f039dd39c1ce2672f4978c8abc6dff862ef1445`. Runtime
Distribution [run #459](https://git.add-ideas.de/GovOPlaN/govoplan/actions/runs/459)
proved migrations, schema compatibility, non-root API/Web readiness, and worker
delivery/shutdown on both `linux/amd64` and `linux/arm64`. Its signed manifest
has SHA-256
`d703267e01855dee63200cb20921c91c3f95fbff550c8ca76e9a35cba3f69109`
and pins these runtime indexes:
1. **OCI release artifacts.** The release pipeline does not yet publish pinned
multi-architecture API and WebUI images.
2. **Signed distribution manifest.** A channel manifest must bind exact image
digests, Compose compatibility, SBOM/provenance references, and revocation
state. Recording a URL and checksum is not signature verification.
3. **First administrator.** Production needs a one-time, restricted enrollment
- API: `git.add-ideas.de/govoplan/runtime-api@sha256:197ed01790986f2bc927eaa5d8348fa118702e5d2dc05feb851fc2643c23764a`
- WebUI: `git.add-ideas.de/govoplan/runtime-web@sha256:e936cca124f1fad29a067834cf17627d4c236410fdc3fa129e0ccb26b8193812`
The signed bootstrap has SHA-256
`1ff946fba82b0895d153b23352d06e30fe18388450dfd37fed6fb9912310efc5`
and key id `runtime-distribution-2026-01`. The managed-ingress boundary passed
the same publication run and the independently dispatchable Runtime Ingress
Drill [run #458](https://git.add-ideas.de/GovOPlaN/govoplan/actions/runs/458).
Every later release must renew this evidence; the following target-specific
gates remain:
1. **First administrator.** Production needs a one-time, restricted enrollment
identity. The development bootstrap must not be enabled in production.
4. **Image/module composition.** The selected module set must be proven present
in the exact image or installed from verified offline artifacts before it is
2. **Image/module composition.** The deployer enforces the signed
composition. A selected module not shipped by that release cannot be
enabled.
5. **Deployment agent.** Web updates need a separate privileged reconciler with
3. **Deployment agent.** Web updates need a separate privileged reconciler with
a typed command allowlist. The API and browser must never receive the Docker
socket or arbitrary shell access.
6. **Ingress and certificates.** The managed HAProxy service provides HTTP
load balancing inside the deployment boundary; it does not issue or renew
certificates. A self-hosted profile still needs an explicit choice
between an existing reverse proxy and a supported managed ingress, including
trusted-proxy boundaries, TLS certificate issuance, renewal, and health
probing through the public route.
4. **Target reachability evidence.** Managed Caddy ingress and the
existing-proxy contract are implemented. A production claim still requires
running `doctor` from the target host after public DNS/firewall changes and
retaining public TLS/readiness evidence for that deployment.
`apply --allow-unverified-images` is therefore restricted to the evaluation
profile. It explicitly acknowledges both mutable image identities and
@@ -232,7 +334,9 @@ must use a tested multi-node Garage cluster or another external S3 service.
### Load Balancing And Replicas
The generated Compose topology publishes only `load-balancer`. HAProxy uses
The generated Compose topology publishes only `load-balancer` for local or
existing-proxy profiles. With managed ingress, only Caddy publishes host ports
and HAProxy remains private. HAProxy uses
Docker DNS service discovery to distribute public traffic across WebUI replicas
and WebUI API proxy traffic across API replicas. The WebUI and API services do
not publish host ports. HAProxy has no Docker socket and discovers only the
@@ -256,6 +360,49 @@ PostgreSQL advisory lock. The Celery scheduler is run under a renewable,
fencing-token lease. Multiple API replicas are rejected when Redis is disabled
because distributed throttling and queued work cannot then be shared correctly.
### Public Ingress And TLS
A self-hosted installation is fail-closed until one of these boundaries is
selected:
- `existing-proxy` publishes HAProxy at `listen.address:listen.port` and emits
`existing-proxy.json`. The operator-owned proxy must use the recorded host,
upstream, and health paths. Only the exact CIDRs listed with repeated
`--trusted-proxy-cidr` values may supply `X-Forwarded-*` headers. Public
proxy addresses must be `/32` or `/128`; private ranges are limited to `/24`
or narrower for IPv4 and `/64` or narrower for IPv6.
- `managed` publishes Caddy on the selected HTTP/HTTPS ports, redirects HTTP to
HTTPS, obtains and renews certificates through ACME, and keeps certificate
material exclusively in the private `caddy-data` and `caddy-config` volumes.
The application containers receive no ACME account or TLS private keys.
Example existing-proxy configuration:
```sh
python govoplan-deploy.py configure \
--directory /srv/govoplan \
--ingress existing-proxy \
--trusted-proxy-cidr 172.20.0.7/32
```
Example managed configuration:
```sh
python govoplan-deploy.py configure \
--directory /srv/govoplan \
--ingress managed \
--acme-email operator@example.org
```
Before managed ingress starts, public A/AAAA records must resolve to the target
and inbound TCP 80/443 must reach it. Existing-proxy mode additionally requires
the public proxy and valid certificate to be reachable before apply. After a
successful receipt, `doctor` reports DNS resolution, certificate validity and
remaining lifetime, public `/health/ready`, and the private HAProxy/WebUI path
as separate checks. Reconfiguration retains the certificate volumes; bundle
rollback never deletes or exposes their contents. Include both Caddy volumes
in coordinated backup and restore evidence.
This is same-host scaling. Docker Compose uses a bridge network and does not
place containers on another machine. See
[Scaling And Multi-Host Deployment](SCALING_AND_MULTI_HOST_DEPLOYMENT.md) for
@@ -292,10 +439,12 @@ starts, recovery is forward-only unless an independently verified database
backup is restored. See
[Recovery And Rollback Guarantees](RECOVERY_AND_ROLLBACK_GUARANTEES.md).
Production updates still need an operator-provided database backup/restore
gate, database compatibility declaration, image signature verification, and
deployment-specific drain policy. The deployment journal proves its own
actions; it does not manufacture backup evidence.
Production updates still need operator/provider-created coordinated backup and
restore evidence, a database compatibility declaration, and a
deployment-specific drain policy. The deployer now verifies and enforces the
signed evidence before migration, but does not manufacture backups or receive
provider administration credentials. See
[Backup And Restore Evidence](BACKUP_AND_RESTORE_EVIDENCE.md).
## Stateless Kubernetes Runtime
@@ -314,7 +463,9 @@ The output includes a release-specific migration Job, database-head wait init
containers, API readiness/liveness probes, rolling Deployments, Services, Pod
disruption budgets, a tokenless ServiceAccount, and one fenced scheduler. Apply
the named Secret through the cluster's secret manager and review ingress proxy
CIDRs before deployment. Detailed rollout and scaling rules live in
CIDRs before deployment. A release-changing export requires adopted backup
evidence and carries only its sanitized digest and identifiers as Job
annotations. Detailed rollout and scaling rules live in
[Scaling And Multi-Host Deployment](SCALING_AND_MULTI_HOST_DEPLOYMENT.md).
## Recovery Commands
@@ -360,22 +511,37 @@ of the reviewed update recipe instead of a non-functional update button.
## Distribution Workflow
The downloadable entry point should eventually be:
The downloadable entry point is a reproducible release asset: sorted source
paths, fixed ZIP metadata, fixed compression settings, and identical source
bytes produce an identical zipapp regardless of checkout timestamps. Obtain the
zipapp, detached signature, checksum, and trusted public keyring through
independently authenticated paths before execution:
```sh
curl --proto '=https' --tlsv1.2 --fail --location \
https://govoplan.add-ideas.de/install/v1/bootstrap.pyz \
--output govoplan-bootstrap.pyz
python3 govoplan-bootstrap.pyz init
https://git.add-ideas.de/GovOPlaN/govoplan/releases/download/vX.Y.Z/govoplan-deploy.pyz \
--output govoplan-deploy.pyz
sha256sum --check govoplan-deploy.pyz.sha256
python3 - <<'PY'
import json
from pathlib import Path
keyring = json.loads(Path("distribution-keyring.json").read_text())
active = [key for key in keyring["keys"] if key["status"] == "active"]
if len(active) != 1:
raise SystemExit("expected exactly one active runtime release key")
Path("runtime-release-public.pem").write_text(active[0]["public_key_pem"])
PY
openssl pkeyutl -verify -pubin -inkey runtime-release-public.pem -rawin \
-in govoplan-deploy.pyz -sigfile govoplan-deploy.pyz.sig
python3 govoplan-deploy.pyz init
```
The published documentation must include an independent checksum/signature
verification command before execution. The zipapp then downloads only a signed
distribution manifest, verifies it against an embedded or explicitly installed
keyring, and renders the same installation contract implemented here.
The source-tree script is the test harness for that future zipapp. It is not yet
the internet bootstrap artifact.
The zipapp has no GovOPlaN package dependency. It accepts a bounded HTTPS
manifest or a prefetched file, requires an independently supplied SHA-256
digest and explicit trusted keyring, and executes OpenSSL with a fixed argument
vector for Ed25519 verification. It never evaluates downloaded shell text or
accepts an arbitrary command string.
## Verification
@@ -385,7 +551,9 @@ Run the focused tests:
./.venv/bin/python -m unittest -v tests.test_deployment_installer
```
The tests cover profile restrictions, secret persistence, external endpoint
The tests cover signed release adoption, tamper/expiry/revocation/unknown-key
rejection, architecture composition, offline image integrity, profile
restrictions, secret persistence, external endpoint
requirements, managed Garage bootstrap, S3 policy, replica validation, HAProxy
discovery configuration, Compose service selection, secret non-disclosure,
service-specific environment isolation, private file modes, external endpoint
Repo-docs-INSTITUTIONAL-DIGITAL-TWIN.md
+156
@@ -0,0 +1,156 @@
<!-- codex-wiki-sync:40444c768c20ac47e231bd79 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_DIGITAL_TWIN.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Institutional Digital Twin
## Definition
The institutional digital twin is a governed, time-aware projection of how an
institution is constituted and operates. It connects structure, authority,
services, work, information, technology, obligations, controls, evidence, and
outcomes without becoming a second source of truth.
The twin is not one editable graph database and not an employee-surveillance
system. Domain modules and external systems keep ownership. The twin stores or
materializes exact references, declared relationships, provenance, confidence,
and projection versions. Changes flow through owner actions.
Implementation is tracked in
[GovOPlaN #43](https://git.add-ideas.de/GovOPlaN/govoplan/issues/43).
## Questions It Should Answer
- Which unit and function is responsible for a service, decision, record,
system, dataset, control, or risk at a given valid and recorded time?
- Which mandates and policies permit or constrain an action?
- Which processes, providers, staff capacities, data sources, and records are
required to deliver a service?
- What is affected if a system, provider, organizational unit, role, package,
or legal rule changes?
- Where are responsibilities missing, conflicting, expired, or concentrated?
- Which controls are evidenced, stale, failed, or dependent on an unverified
assertion?
- How do actual process traces differ from defined workflows?
- Which public outcomes can be explained from protected internal evidence?
## Projection Planes
| Plane | Meaning |
| --- | --- |
| Current | Valid now, reconstructed from owner projections and current provider state |
| Historical | Valid at and recorded by selected instants, with present-day security enforced |
| Planned | Approved or proposed future structures, services, policies, projects, and package changes |
| Observed | Events, process traces, service measures, incidents, effects, and evidence actually recorded |
| Scenario | Non-authoritative simulation of a proposed change and its estimated consequences |
The UI must label these planes unambiguously. Scenario output never becomes an
institutional fact until an authorized owner action accepts it.
## Canonical Graph
Nodes are stable institutional references, including institution, tenant,
unit, function, assignment, mandate, jurisdiction, service, case, party, task,
workflow, approval, decision, record, file, message, appointment, dataset,
report, provider, system, control, risk, project, asset, and configuration
package.
Edges have:
- owner and source authority;
- relationship type and direction;
- valid-from/valid-to and recorded/superseded times;
- exact source revision and evidence digest;
- institution/tenant boundary;
- purpose and visibility classification;
- confidence and derivation method for inferred relationships;
- correction and replacement references.
Inferred edges are never displayed as owner assertions. They remain
explainable analytical products with source lineage.
## Ownership And Implementation
- Core owns neutral institutional references, temporal context, provider
registration, and graph projection contracts.
- Domain modules publish bounded nodes and edges through provider interfaces.
- Search indexes discoverable identities and links.
- Reporting materializes governed analytical projections.
- Dataflow computes derived relationships, quality checks, and scenarios.
- Policy evaluates visibility, purpose, retention, and allowed scenario/action
transitions.
- Audit supplies observed events and evidence references.
- Projects supplies planned change and benefit relationships.
- Views renders role- and task-focused twin perspectives.
- Workflow Engine coordinates accepted changes but does not edit owner tables.
No new digital-twin module is required for the first slice. A dedicated owner
is justified later if persisted scenario models, graph revisions, and
cross-domain projection lifecycle become independent product objects.
## Beyond The Current Platform
### Continuous assurance
Controls become versioned assertions with evidence requirements, evaluation
frequency, responsible function, exception workflow, and freshness. Dataflow
and provider checks evaluate them continuously; Policy decides whether a stale
or failed control advises, requires review, or blocks an effect.
### Process mining and conformance
Governed event histories can derive actual paths, wait times, rework, and
exceptions. Comparison to Workflow definitions should improve procedures, not
rank individuals. Access to personal or small-cohort detail is purpose-limited
and separately governed.
### Change-impact simulation
A proposed organizational, provider, policy, or package change can be assessed
against dependencies, mandates, open work, records, controls, capacity, and
recovery plans before activation. Results identify uncertainty rather than
inventing precision.
### Federated institutional models
Installations can exchange signed public or partner-specific subsets of their
service, mandate, provider, and evidence graph. Every side maps the references
locally and retains autonomy. Federation does not create one supranational
master graph.
### Accountable assistance
Assistance may summarize context, identify missing evidence, draft a decision
or workflow, propose mappings, and explain policy. Every output records model,
inputs, constraints, uncertainty, human review, and accepted edits. Assistance
does not become the acting authority.
### Public evidence chains
Transparency packages can publish a minimized chain from rule and aggregate
facts to decision and observed outcome, with digests proving relation to
protected evidence. Public verification does not require disclosure of the
underlying personal data.
## Guardrails
- Do not infer competence, misconduct, intent, or personal performance from
graph proximity or incomplete events.
- Do not centralize protected content merely to make graph queries easier.
- Do not use historical authorization to expose data now prohibited.
- Do not let a scenario engine write domain state directly.
- Do not hide source authority, freshness, uncertainty, or missing evidence.
- Do not retain analytical detail longer than the declared purpose requires.
## Delivery Slices
1. Publish exact institutional reference/edge providers for the service-to-
decision and monthly-data journeys.
2. Build a current/historical dependency explorer with source and access
explanations.
3. Add planned Project/package changes and bounded impact reports.
4. Add control evidence/freshness and process conformance for one journey.
5. Prove a minimized federated projection and a public evidence package.
Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE.-.md
-563
@@ -1,563 +0,0 @@
<!-- codex-wiki-sync:1e54e3b798a328f70566a24a -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Institutional Governance Target Architecture
## Status and sources
This document is the accepted architectural reconciliation of two product
concepts prepared outside the repositories:
- `govoplan_concept_dev.md`
- `software_big_picture.md`
The source concepts describe GovOPlaN as an operational governance platform for
public institutions. This document merges that direction with the implemented
platform state as of 2026-08-01. It is the canonical repository version of the
direction. Gitea issues remain the source of truth for delivery state.
Read this together with:
- [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md)
- [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md)
- [Module Contracts and Install Boundaries](MODULE_CONTRACTS_AND_INSTALLS.md)
- [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md)
- [Capability and Infrastructure Fit](CAPABILITY_AND_INFRASTRUCTURE_FIT.md)
- [Core Module Architecture](../../govoplan-core/docs/MODULE_ARCHITECTURE.md)
- [Core External References and Integration Maturity](../../govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md)
- [Core Action, Effect, and Automation Layer](../../govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md)
## Decision
GovOPlaN is a configurable **institutional governance and operations layer** for
public institutions. It should model the institution, coordinate its work,
connect its specialist systems, and preserve why and under whose authority an
action occurred.
GovOPlaN is not intended to become one universal ERP, DMS, groupware suite,
workflow editor, or specialist procedure. It should own the governance concepts
that must remain understandable across those systems and support native,
external, mirrored, synchronized, overlay, and link-only operation explicitly.
This changes product emphasis, not the modular architecture:
1. The current kernel and optional-module model remains.
2. Existing domain owners keep their data and behavior.
3. Cross-module semantics become explicit, versioned contracts.
4. Successful compositions become product and sector packages, not forks or
monolithic replacement applications.
5. Repository creation follows a proof threshold; a noun in the information
model does not automatically require a module.
## What recent work already supersedes
The source concepts predate several implemented foundations. These items are
accepted as the current baseline and must not be reopened as greenfield work.
| Concept requirement | Reconciled current state |
| --- | --- |
| Slim kernel plus installable modules | Implemented through entry-point discovery, `ModuleManifest`, migrations, capabilities, interfaces, WebUI contributions, and permutation checks. |
| Versioned cross-module contracts | Implemented through named interface ranges, capability protocols, static workspace graph checks, activation validation, and release checks. |
| Separate headless workflow runtime and editor | Implemented as `govoplan-workflow-engine` and optional `govoplan-workflow`. Module-owned workflow baselines are versioned and reconciled without replacing local overrides. |
| Provider-neutral external references | Implemented in Core with stable external identity and cumulative integration maturity from discovery through replacement. |
| Governed asynchronous effects | Implemented foundations include the action/effect contract, transactional platform event outbox, module outboxes, idempotency, outcome-unknown states, reconciliation, and worker health. Coverage still varies by provider. |
| Acting identity, function assignment, mandate, and ownership recovery | Implemented foundations span Identity, Organizations, IDM, Access, Mandates, generic ownership transfer/recovery, and audit provenance. Effective competence now resolves through a tenant-bound Mandate capability. |
| Governed data foundations | Connectors, Datasources, Dataflow, Reporting, and Search now exist. Datasources already provides live/cached/static modes, staging, immutable materializations, and publication contracts. |
| Task-focused projections and configured documentation | Views, view-surface declarations, configurable dashboards, and manifest-driven user/admin documentation exist. Rollout and content depth remain incremental. |
| Encryption as an optional capability | `govoplan-encryption` now defines key-vault, content-protection, recovery, and disable-preflight boundaries. It is not a reason to move domain ownership into Core. |
| Search without mandatory OpenSearch | PostgreSQL-backed, permission-aware search and module provider contracts exist; OpenSearch remains an optional adapter. |
| Scale-out and recovery architecture | Stateless API/worker, shared database/object storage, event delivery, deployment, and recovery contracts are documented and partly exercised. Production profiles and drills remain active work. |
The institutional semantics, provider declaration gate, and first product
compositions described here are now implemented. Subsequent work is
**product depth and stronger maturity evidence**, not another runtime rewrite
or an unimplemented architecture boundary.
## Implementation status (2026-08-01)
The architecture contract is implemented as a bounded, executable vertical
slice. The portfolio declarations and provider governance gates apply to the
whole workspace, while the four semantic domains whose repository thresholds
were proven now have independent persistent owners:
| Area | Implemented state | Remaining rollout |
| --- | --- | --- |
| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for all 62 source manifests. Focused and release checks enforce `--require-architecture`; a new module cannot enter the workspace without truthful declaration and repository-local evidence. |
| External providers | Core validates provider objects/field groups, operations, integration maturity, source authority, bounded reads, freshness/health, idempotency, conflicts, outcome-unknown handling, evidence, correction, reconciliation, outage, classification, purpose, retention, and secret handling. Addresses/CardDAV, Files remote storage, Mail SMTP/IMAP, Calendar CalDAV/ICS/Graph/EWS, and Connectors tabular/sanctions providers declare the contract and tenant-bounded secret-free runtime state. | Registry validation rejects any declared external provider without a sanitized state provider. Future adapters must cross the same gate before activation. |
| Institutional context | Core provides versioned temporal, actor/representation, institution/unit/function/task/mandate/jurisdiction/service/case/party/work-item/workflow/approval/decision/record, legal-basis, evidence, information-governance, external-source, presentation, and geographic references. Events, automation actions, audit records, and the transactional Audit outbox preserve the envelope. | Owning modules must progressively require the relevant subset for consequential operations. |
| Semantic provider contracts | Provider-neutral DTOs and protocols cover Mandate resolution, versioned Service definitions, procedure Parties/representation, and formal Decisions. `govoplan-mandates`, `govoplan-services`, `govoplan-parties`, and `govoplan-decisions` now persist immutable revisions behind those contracts with tenant isolation, bounded reads, replay safety, OCC, migrations, uninstall guards, permissions, APIs, capability documentation, and recovery documentation. | The owners are deliberately headless. Procedure-specific UI remains with consuming modules. |
| Formal-outcome proof | Committee persists bodies, meetings, agenda items, votes, minutes, lifecycle events, and an optional protected local Decision projection. It resolves effective Mandate authority and records reconstructable formal Decisions through `decisions.registry` when installed. OCC, replay safety, tenant isolation, bounded reads, closure guards, and a full-height body/meeting/agenda/vote/minutes WebUI cover the aggregate. Provider-bound external or secret ballots use dynamic adapter capabilities; Committee validates and retains only aggregate counts, receipt/hash, and evidence, and rejects generic manual closure. | Concrete ballot-provider packages remain integration work because their protocol, custody, credentials, and operator evidence depend on the selected provider. This does not leave a Committee-owned ballot contract unspecified. |
| Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Forms owns immutable form schemas and Forms Runtime owns definition-aware drafts, validation, submission receipts, status/evidence history, and handoff references. Portal exposes a tenant-scoped service-directory WebUI whose audiences derive from trusted principal/function state, re-fetches the exact Service revision, and delegates URL, Case, Form, or Workflow launch to an installed owner. Cases and Forms Runtime retain exact Service and binding provenance, enforce tenant isolation, replay safety and OCC, and expose bounded owner/manager APIs and WebUI. | Anonymous intake, concrete attachment/signature adapters, conditional multi-page authoring, and automatic domain handoff execution are product depth on established contracts. Portal still fails closed and explains any absent launcher or runtime prerequisite. |
| Procedure-party proof | Parties persists effective procedure roles, frozen contact snapshots, and representation powers. Existing powers cannot disappear or be silently rewritten; explicit OCC-guarded revocation is required. Cases resolves the provider capability and excludes expired/revoked authority from downstream delivery. | Procedure modules still decide which contextual fields and actions to present. |
| Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Cases, Parties, Mandates, Committee, and Decisions providers. It carries one exact Service version through persisted Case intake, representation and frozen delivery authority, effective Mandate resolution, a body/meeting/agendum/vote/minute sequence, a persisted formal Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. A second executable path proves Portal to exact Form revision, persisted submission, and idempotent replay. | This is architecture and composition evidence. Signed, release-bound target accessibility, privacy, security, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
| Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. Reporting now persists immutable dataset, semantic-model, report, quality-plan, saved-view, and schedule revisions; executes typed semantic queries with quality gates, access checks, replay, pivoting, export/import assessment, and provenance; and exposes the governed analytical WebUI. | Rich dependency/impact traversal, additional expression functions, and policy-specific field visibility can grow on the established contracts without moving connector, transformation, or source ownership. |
| Portfolio and change governance | Projects now persists tenant-safe, immutable portfolio/project/milestone revisions with OCC, replay, lifecycle rules, restricted memberships, Search ACL indexing, outcomes, benefits, dependencies, capacity assumptions, change impact, and institutional references. Its WebUI exposes the planning catalogue and core planning fields. | Advanced planning structures already accepted by the API can receive deeper specialized editors without creating a second Policy, Reporting, Resources, or Goals owner. |
| Product/package governance | Signed configuration packages distinguish reference, product, sector, deployment, and integration classes; preserve parent/evidence provenance; prevent derived packages from loosening constraints; and preflight provider authority, maturity, exact binding, health, freshness, and recovery expectations. Executable product manifests now exist for governed communication and governed data/assurance and are checked in the module matrix. | Both artifacts deliberately remain product-class until target, accessibility, privacy, security, operations, and recovery evidence justifies reference readiness. |
| Projection and release | Platform metadata, signed module catalogs, release synthesis, Ops, and role-aware Docs retain and display architecture/provider declarations. Module-owned state providers add bounded configured/active, authority, health, freshness, conflict, recovery, and observation state; ordinary-user Docs omits binding detail. Static checks validate evidence paths, and the WebUI build verifies consuming types. | Runtime-state adoption and broader portfolio presentation follow truthful provider declaration rollout. |
The implementation deliberately keeps shared reference contracts in Core and
domain tables in their owners. It does not claim unsupported release maturity:
the four extracted owners and package remain `vertical_slice`/`product` until
target evidence supports a stronger claim. Gitea remains authoritative for
feature depth beyond this architecture contract.
## Target capability layers
The layers describe ownership and dependency direction. They are not navigation
groups and do not imply that every installation exposes every module.
| Layer | Responsibility | Current owners and declared directions |
| --- | --- | --- |
| 0. Runtime and meta | Composition, release, migrations, shared contracts, operations, deployment | Core, meta repository, Admin, Ops |
| 1. Institutional foundation | Institution, tenant, identity, organization, function, authority, access, trust | Tenancy, Identity, Organizations, IDM, Access, Identity Trust, Encryption, Mandates |
| 2. Governance and accountability | Policy, audit, risk, control, explainability, configured projection | Policy, Audit, Risk Compliance, Docs, Views, Search, Decisions |
| 3. Human work and procedure | Intake, cases, tasks, approvals, process execution and editing | Services, Forms, Forms Runtime, Cases, Parties, Tasks, Approvals, Workflow Engine, Workflow, Tickets |
| 4. Communication and participation | Delivery, participation, scheduling, channels, consultation | Portal, Postbox, Notifications, Mail, Campaign, Calendar, Scheduling, Poll, Appointments, Booking, Consultation, Committee, Addresses, Distribution Lists |
| 5. Content, records, and evidence | Managed content, templates, records, knowledge, disclosure | Files, Templates, DMS, Records, Wiki, Transparency, Certificates |
| 6. Data, reporting, and integration | Source access, staging, transformation, search, analytics, protocols | Connectors, Datasources, Dataflow, Reporting, Dashboard, REST, SOAP, XOE/V, XTA/OSCI, FIT-Connect, XRechnung, ERP adapters |
| 7. Domain capabilities | Reusable public-sector subject matter | Projects, Procurement, Contracts, Grants, Resources, Assets, Facilities, Learning, Payments, Ledger, Permits, Inspections, Evaluation, Helpdesk |
| 8. Product and sector packages | Versioned compositions, terminology, forms, processes, controls, reports, integration profiles | Signed configuration packages and reference packages; not runtime modules by default |
## Canonical institutional semantics
The connected model must keep these concepts distinct even where one UI
combines them.
| Concept | Canonical answer | Owner or direction |
| --- | --- | --- |
| Institution and tenant | In which governed installation and tenant does work occur? | Tenancy and Organizations |
| Organization and unit | Where is responsibility situated? | Organizations |
| Function | Which named organizational responsibility can an incumbent hold? | Organizations |
| Identity and account | Who is the person or machine, and through which account do they act? | Identity and Access |
| Function assignment | Who holds or represents a function, for which interval and source? | IDM |
| Role and permission | What application behavior may the acting principal perform? | Access, constrained by Policy |
| Mandate and jurisdiction | Why is an institution, unit, or function competent to act on this subject, territory, population, or interval? | Mandates |
| Service | What governed promise can an institution offer, to whom, under which prerequisites, evidence, channel, deadline, and responsibility? | Services; Portal presents it |
| Case | Which concrete administrative matter is being handled? | Cases |
| Party | In what procedural capacity does a person or organization participate, and who may represent or receive for it? | Parties; Identity/Organizations remain the subject owners |
| Work item | What must a responsible actor do next? | Tasks and domain modules |
| Workflow | How is work coordinated, including waits, human hand-offs, and governed actions? | Workflow Engine; Workflow is the optional editor |
| Approval | Has a proposed action passed a configured review or separation-of-duties gate? | Approvals |
| Decision | What formal institutional outcome was reached, by which competent authority, on which facts, rules, evidence, reasoning, and review path? | Decisions |
| Evidence and record | What proves the input, state, action, effect, correction, and retained institutional memory? | Domain owner, Files/DMS/Records, and Audit |
### Extracted semantic modules
Four horizontal concepts passed the repository proof threshold. Their Core
DTOs and provider protocols remain neutral; their persistent data, lifecycle,
security, APIs, migrations, and recovery behavior now live in independent
repositories.
#### Mandates
Mandates should own public or internal tasks, jurisdiction, responsibility,
decision/signature authority, legal or organizational basis, and effective
history. Organizations continues to own structures and functions; IDM owns
incumbency; Access owns permissions; Policy owns constraints.
`govoplan-mandates` answers: *Was this function competent to act for this case
at the relevant time, and on what basis?* Its resolver evaluates effective
time, task, authority, unit, function, jurisdiction, subject, conflicts, legal
basis, and evidence deterministically. Missing or ambiguous authority fails
closed.
#### Services
Services should own versioned service definitions: audience, prerequisites,
legal basis, evidence, fees, deadlines, channels, responsible unit/function,
jurisdiction, forms, case/workflow/result bindings, remedies, service levels,
and publication status. Portal presents and starts services but should not own
their institutional definition.
`govoplan-services` now owns those exact versioned definitions. Portal is the
first presentation consumer and Cases freezes the selected revision into its
intake context. Availability is an independent capability so publication does
not imply that all runtime prerequisites are satisfied.
#### Parties
Parties should own procedure-local roles and relationships: applicant,
respondent, beneficiary, representative, joint applicant, delivery recipient,
power or authority to represent, and permitted/preferred channels for the
matter. Identity answers who the subject is; Organizations answers which
institutional unit it is; Addresses owns contact points; Parties answers how
the subject participates here.
`govoplan-parties` owns the shared effective-dated lifecycle. Cases retains a
bounded compatibility projection only when the module is absent; that fallback
contains no representation lifecycle and cannot silently become a second
authority source.
#### Decisions
Decisions should own formal outcomes: subject, type, competent authority,
facts, evidence, applicable rule versions, reasoning, operative result,
conditions, effect, delivery/publication, remedy/review, correction, revocation,
and links to observed effects. Approvals own review gates; Poll owns response
collection; Committee owns deliberation, meetings, and votes; Workflow owns
coordination.
`govoplan-decisions` owns the persistent lifecycle and protected reconstruction
surface. Committee supplies deliberation context and records through the
provider capability. Consumers retain exact Decision references without
gaining table access.
## Source authority and integration maturity
Two independent dimensions must be recorded. They must not be collapsed into a
single `sync` flag.
### Source-authority mode
| Mode | Meaning |
| --- | --- |
| `native_authoritative` | GovOPlaN owns the authoritative object and lifecycle. |
| `external_authoritative` | The external system owns the object; GovOPlaN reads or acts through it. |
| `external_mirror` | The external system is authoritative and GovOPlaN keeps a governed local projection or immutable snapshots. |
| `governed_sync` | Both sides may change supported fields under explicit conflict and reconciliation rules. |
| `governance_overlay` | GovOPlaN owns policy, responsibility, evidence, or coordination around an externally executed object. |
| `linked_reference` | GovOPlaN keeps only a stable link and minimal display/provenance metadata. |
Authority may be declared per tenant, organization, service, object type,
object, field group, or process step. A broad default must not hide a narrower
override.
### Integration maturity
The implemented maturity ladder remains `discover`, `link`, `search`, `read`,
`publish`, `synchronize`, `migrate`, and `replace`. Maturity says what an
adapter can do. Source-authority mode says who owns truth in a particular
configuration. For example, a connector may support `synchronize`, while a
tenant deliberately configures it as `external_mirror`.
### Provider declaration
Every provider that reads or causes external effects must declare:
- owned object and field groups;
- supported source-authority modes and integration maturity;
- read, write, delete, search, preview, and dry-run operations;
- revision/concurrency tokens, freshness, health, and bounded-read limits;
- idempotency, retry, timeout, conflict, and outcome-unknown behavior;
- evidence, audit, correction, rollback/compensation, and reconciliation paths;
- degraded and outage behavior;
- classification, purpose, retention, and secret-handling requirements.
The common provider declaration composes the external-reference, action/effect,
connector-lifecycle, capability, operational-check, and documentation
contracts. Core, release tooling, Ops, Docs, and configuration-package
preflight validate it; Registry refuses to activate a declared external
provider without bounded, sanitized runtime state.
## Cross-cutting contracts
The following contracts are mandatory for consequential domain objects. They
should be shared reference DTOs and provider protocols, not shared domain
tables in Core.
1. **Time and history:** valid-from/to, recorded-at, superseded-at, revision,
change reason, and stable identity.
2. **Actor and representation:** real account/identity, system or service
account, represented account/function/party, delegation or power, and
mandate reference.
3. **Institutional context:** tenant, institution, organization unit, function,
task/mandate, jurisdiction, service, case, and decision references.
4. **Legal and policy basis:** typed, versioned references to rules,
obligations, policies, exceptions, and the effective decision source.
5. **Requested and observed effect:** intent, approval, dispatch, possible
execution, confirmation, reconciliation, correction, and terminal evidence.
6. **Evidence and provenance:** source, version, checksum, derivation,
responsible actor, timestamps, and inspection links.
7. **Information governance:** classification, purpose, legal basis, retention,
hold, minimization, and disclosure state.
8. **External source:** system/profile/object identity, authority mode,
maturity, version, freshness, health, and conflict state.
9. **Presentation:** language, accessibility, channel, explanation, and
configured availability.
Existing contracts already cover substantial parts of items 1, 2, 5, 6, 8,
and 9. New work should extend those contracts instead of creating parallel DTO
families.
## Existing module direction changes
### Datasources becomes the governed data and register catalogue
The implemented live/cached/static, staging, immutable materialization, and
publication model includes typed governance metadata for owner/steward,
authoritative source and authority mode, legal basis and purpose, semantic
definition, quality and freshness policy, classification, transfer agreement,
correction process, affected services/processes, and dependent flows,
reports, controls, and decisions. Connector credentials and protocol behavior
remain outside Datasources.
### Projects grows into portfolio and change governance
The Projects boundary already includes portfolios and goals. Extend it through
versioned objectives/outcomes, dependencies, capacity, benefits, change impact,
and links to mandates, services, risks, contracts, resources, and indicators.
Do not create a separate Goals module before more than one domain proves an
independent goal lifecycle.
### Reporting becomes evidence-backed institutional measurement
Every report, measure, and indicator should explain the institutional question
or obligation it serves, owner, source/materialization and flow revision,
freshness/quality, calculation version, visibility/purpose limits, publication,
and decisions or actions that consumed it. Reporting owns presentation and
execution; source and transformation owners retain their domains.
### Risk Compliance becomes the horizontal assurance model
Sanctions screening remains a complete vertical slice. The broader reusable
model is:
```text
Obligation -> governed object -> risk -> control -> evidence -> finding -> measure -> effectiveness review
```
Risk Compliance now persists that effective-dated, immutable-revision assurance
graph, exposes bounded tenant-safe traversal/search/editing, and projects each
completed sanctions run into it idempotently. Policy
owns enforceable rules and decisions; Audit owns immutable event evidence;
domain modules own the governed objects and corrective actions.
### Connectors exposes authority and effect behavior
Connector direction (`consume`, `publish`, `bidirectional`) remains useful but
is not enough. Profiles and bindings need the source-authority mode and
provider declaration above. ERP remains an integration family: finance,
workforce, procurement, asset, or other domain modules own semantics while
connectors own transport and source interaction.
### Geography starts as a reference contract
Before adding a `govoplan-geo` module, define a common reference shape for
coordinates, geometry, administrative area, address/location, CRS, source,
accuracy, validity, and external GIS identity. Create a repository only when
GovOPlaN must own spatial datasets, topology, or independent geospatial
lifecycles rather than link to an external GIS.
## Product and sector packages
A module says what capability can exist. A product package says how capabilities
work together for a bounded outcome. A sector package specializes vocabulary,
forms, rules, process baselines, controls, reports, and integration profiles
without forking the platform.
The signed configuration-package mechanism distinguishes:
- **reference package:** tested composition proving a journey and its recovery
behavior;
- **product package:** reusable operating capability such as governed
communication, service-to-decision, procurement/contracts, or governed BI;
- **sector package:** institutional specialization such as municipality,
university/research, ministry/program, regulator, grants authority, or
committee/council;
- **deployment profile:** supported infrastructure and operational topology;
- **integration profile:** supported set of external systems, authority modes,
bindings, and health expectations.
Packages may require modules and capabilities, but package definitions remain
configuration and evidence. They do not gain access to module-owned tables.
## Module portfolio metadata
Repository category is not capability maturity. The runtime manifest, release
catalog, Docs projection, and meta repository inventory use one
machine-readable declaration with at least:
- architecture layer and module kind;
- lifecycle/maturity claim: `concept`, `scaffold`, `vertical_slice`,
`reference_ready`, `supported`, or `lts`;
- evidence supporting the claim and known limits;
- supported source-authority modes;
- owned and explicitly non-owned concepts;
- provided/required capabilities and interfaces;
- reference packages and target-tested providers;
- migration, upgrade, recovery, security, and operations documentation.
Maturity is a release claim and must be checked against evidence. A manifest
must not become “supported” merely because a maintainer changes one string.
Create a repository only when the capability has distinct data ownership,
independent installability, technical assets, a security/lifecycle profile, a
release reason, more than one consumer or a proven reference process, and tests
that justify the boundary. Otherwise use a shared DTO, provider capability,
submodule, configuration fragment, package, or profile.
## Implemented migration sequence
### 0. Align the portfolio and contracts - complete
- This reconciliation is canonical in the meta repository and mirrored to the
Gitea wiki.
- All 62 source manifests carry validated evidence-based architecture metadata.
- External-reference, action/effect, operational-health, ownership, policy,
audit, and documentation primitives compose into one enforced provider
declaration and sanitized runtime-state contract.
- Institutional context, legal basis, evidence, presentation, external source,
information governance, temporal revision, and geo references are shared
Core DTOs rather than shared domain tables.
### 1. Prove responsibility and formal outcome - complete
- Mandate and Decision contracts, deterministic resolution, lifecycle
transitions, persistence providers, APIs, permissions, migrations, recovery,
and tests are implemented.
- Committee and the SQL-backed institutional fixture prove effective-time
authority, persisted meeting/agendum/vote/minute context, approval context,
reasoning, evidence, observed effect, correction/revision rules, protected
reconstruction, and review references.
- The independent Mandates and Decisions repositories were created only after
persistence and reuse passed the repository threshold.
### 2. Separate service and party semantics - complete
- Portal remains the presentation surface while Services owns reusable,
versioned definitions and explainable availability.
- Parties owns procedure roles, contact snapshots, and append-only
representation/revocation authority; Cases consumes the common resolver.
- `product.service-to-decision` proves both through a portable administrative
service composition.
- Forms owns immutable, versioned schemas while Forms Runtime owns drafts,
server validation, submission receipts, status/evidence history, and exact
Service/Form provenance. Portal delegates Form launch through the runtime
capability and fails closed when it is unavailable.
### 3. Complete governed data, portfolio, and assurance - vertical slices complete
- Datasources carries typed governance through staging and immutable
materializations, with bounded catalogue filters and dependency references.
- Reporting owns immutable semantic definitions, safe execution, quality gates,
provenance, schedules, saved views, pivoting, and export/import assessment
without taking source or transformation ownership.
- Risk Compliance persists the horizontal obligation/risk/control/evidence/
finding/measure graph and projects sanctions runs idempotently.
- Projects persists portfolio/outcome/change-governance revisions as a
consuming domain without becoming a second policy or reporting engine.
### 4. Package repeatable public-sector outcomes - complete at product maturity
- Governed communication, governed data/assurance, and service-to-decision are
portable product package manifests with repository-local evidence.
- Package preflight enforces module, capability, provider authority, health,
freshness, and recovery expectations without cross-module table access.
- Sector and `reference_ready` claims remain gated on target-environment,
recovery, accessibility, privacy, security, and operator evidence. This is a
maturity gate, not missing architecture implementation.
## What remains after the executable architecture slice
The remaining work is not another Core or cross-module architecture rewrite.
It falls into two explicitly different categories, neither of which can be
truthfully completed by adding generic platform code:
1. **Concrete provider packages:** the Committee ballot adapter contract is
complete, but a real secret/electronic ballot provider requires a selected
protocol and product decisions for voter eligibility, custody, secrecy,
recount, challenge, retention, and operational assurance. Equivalent future
adapters must satisfy the declared provider and recovery gates.
Provider selection and certification are tracked in
[Committee #1](https://git.add-ideas.de/GovOPlaN/govoplan-committee/issues/1).
2. **Target-produced maturity evidence:** `reference_ready`, `supported`, and
`lts` cannot be generated from source code. An exact release and deployment
must produce signed, expiring accessibility, privacy, security, operator,
provider, backup/restore, rollback, and recovery-drill evidence. The verifier
and schemas are implemented; the actual claims require those real runs.
The pinned-release evidence run is tracked in
[GovOPlaN #37](https://git.add-ideas.de/GovOPlaN/govoplan/issues/37).
Forms and Forms Runtime no longer constitute an architecture gap. Remaining
depth includes anonymous/public identity profiles, concrete file and signature
providers, conditional multi-page/localized authoring, and automatic handoff
adapters. Those additions use the implemented immutable definition, runtime,
policy, evidence, service-launch, and domain-owner boundaries rather than
requiring another platform split. They are tracked as
[Forms #3](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/3) and
Forms Runtime [#2](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/2),
[#3](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/3), and
[#4](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/4).
Everything else described as architecture in this document now has a
repository owner, versioned contract, bounded implementation, migration and
recovery boundary where state exists, documentation, and executable evidence.
Further work in those modules is product breadth, UX depth, provider adoption,
and evidence renewal.
## Delivery tracking
The completed cross-repository architecture epic is
[GovOPlaN #29](https://git.add-ideas.de/GovOPlaN/govoplan/issues/29).
Its implementation work packages and resulting owners are:
- [Core #279](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/279):
validated module architecture and provider authority declarations;
- [Core #280](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/280):
shared institutional-context and governed reference primitives;
- [GovOPlaN #30](https://git.add-ideas.de/GovOPlaN/govoplan/issues/30) and
[govoplan-mandates](https://git.add-ideas.de/GovOPlaN/govoplan-mandates):
Mandates semantics and persistent resolver;
- [GovOPlaN #31](https://git.add-ideas.de/GovOPlaN/govoplan/issues/31) and
[govoplan-services](https://git.add-ideas.de/GovOPlaN/govoplan-services):
Services semantics, catalogue, and availability;
- [GovOPlaN #32](https://git.add-ideas.de/GovOPlaN/govoplan/issues/32) and
[govoplan-parties](https://git.add-ideas.de/GovOPlaN/govoplan-parties):
Parties and representation semantics and resolver;
- [GovOPlaN #33](https://git.add-ideas.de/GovOPlaN/govoplan/issues/33) and
[govoplan-decisions](https://git.add-ideas.de/GovOPlaN/govoplan-decisions):
formal Decisions semantics and registry;
- [Datasources #6](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/6):
governed data/register catalogue;
- [Risk Compliance #7](https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance/issues/7):
horizontal assurance graph;
- [GovOPlaN #34](https://git.add-ideas.de/GovOPlaN/govoplan/issues/34):
product and sector package classes; and
- [Docs #19](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/19):
configured architecture, maturity, and source-authority explanations;
- [Forms #2](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/2):
immutable reusable definitions and the designer surface; and
- [Forms Runtime #1](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/1):
definition-aware submissions and Portal service launch.
Existing Projects #1, Reporting #4, Portal #1, Cases #1, Datasources #1,
Risk Compliance #2, GovOPlaN #14, and GovOPlaN #19 carry product-depth and
reference-readiness work instead of duplicating the completed architecture
contract.
## Completion evidence
The architecture direction is established by the following executable and
machine-enforced evidence:
- the `product.service-to-decision` composition and SQL-backed golden fixture
retain institutional context from service entry through a persisted case,
party, authority/work context, committee deliberation, decision, observed
communication effect, minute/record, and review references;
- the Portal/Form journey retains the exact published Service and Form
revisions through persisted draft state, validates on the server, and returns
the same submission on an idempotent launch replay;
- the system can answer who acted, for whom, in which function, under which
mandate and jurisdiction, using which rule and evidence versions;
- every implemented external binding declares authority mode, maturity,
operations, health, freshness, conflict, and recovery behavior, and Registry
rejects a declaration without sanitized runtime state;
- every material report or decision can be reconstructed from governed source
and transformation versions;
- product/package manifests are portable without cross-module table access or
code forks, while future sector packages inherit the same signed-package
constraints; and
- documentation and Ops explain the configured composition and its limits to
users, administrators, operators, and auditors.
These criteria complete the architecture contract at `vertical_slice` and
`product` maturity. They do not waive the separately enforced evidence needed
for a module or package to claim `reference_ready`, `supported`, or `lts`.
The capability-fit verifier now computes that cumulative readiness gate from
independently signed, expiring claims bound to the exact assessed release,
installed payload, deployment subject, controls, and artifact hashes. Actual
target runs and recovery drills remain operator-produced evidence.
Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE.md
+104 -25
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:7b1befe1315b504d421507a4 -->
<!-- codex-wiki-sync:08de72dda4fa5170dc6e4572 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`.
> Origin: `repository`.
@@ -16,13 +16,17 @@ concepts prepared outside the repositories:
- `software_big_picture.md`
The source concepts describe GovOPlaN as an operational governance platform for
public institutions. This document merges that direction with the implemented
platform state as of 2026-07-31. It is the canonical repository version of the
direction. Gitea issues remain the source of truth for delivery state.
public institutions. This document is the canonical repository version of that
durable architectural direction. Its implementation table records the accepted
2026-08-01 baseline; it is not a rolling status report. Current reconciliation
lives in [Strategy Status](STRATEGY_STATUS.md), and Gitea issues remain the
source of truth for delivery state.
Read this together with:
- [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md)
- [Platform Core Ideas](PLATFORM_CORE_IDEAS.md)
- [Strategy Status](STRATEGY_STATUS.md)
- [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md)
- [Module Contracts and Install Boundaries](MODULE_CONTRACTS_AND_INSTALLS.md)
- [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md)
@@ -68,7 +72,7 @@ accepted as the current baseline and must not be reopened as greenfield work.
| Acting identity, function assignment, mandate, and ownership recovery | Implemented foundations span Identity, Organizations, IDM, Access, Mandates, generic ownership transfer/recovery, and audit provenance. Effective competence now resolves through a tenant-bound Mandate capability. |
| Governed data foundations | Connectors, Datasources, Dataflow, Reporting, and Search now exist. Datasources already provides live/cached/static modes, staging, immutable materializations, and publication contracts. |
| Task-focused projections and configured documentation | Views, view-surface declarations, configurable dashboards, and manifest-driven user/admin documentation exist. Rollout and content depth remain incremental. |
| Encryption as an optional capability | `govoplan-encryption` now defines key-vault, content-protection, recovery, and disable-preflight boundaries. It is not a reason to move domain ownership into Core. |
| Encryption as an optional capability | Core defines provider-neutral contracts; `govoplan-identity-trust` persists public device keys, key epochs and assurance evidence; and `govoplan-encryption` persists opaque vault/key lifecycle, versioned protection envelopes, quorum recovery authorization, outcome-unknown reconciliation, and disable preflight. A bundled local AES-256-GCM server-envelope provider now stores wrapped key material and supports Files/Postbox protection, rotation, revocation, destruction, rewrap, tamper detection, and fail-closed restore behavior. It is explicitly neither E2EE nor a certified KMS/HSM. |
| Search without mandatory OpenSearch | PostgreSQL-backed, permission-aware search and module provider contracts exist; OpenSearch remains an optional adapter. |
| Scale-out and recovery architecture | Stateless API/worker, shared database/object storage, event delivery, deployment, and recovery contracts are documented and partly exercised. Production profiles and drills remain active work. |
@@ -77,7 +81,12 @@ compositions described here are now implemented. Subsequent work is
**product depth and stronger maturity evidence**, not another runtime rewrite
or an unimplemented architecture boundary.
## Implementation status (2026-08-01)
## Accepted implementation baseline (2026-08-01)
This section is retained as the dated baseline against which the architecture
decision was accepted. Later implementation must be reconciled in
`STRATEGY_STATUS.md` rather than editing individual rows here into a competing
status report.
The architecture contract is implemented as a bounded, executable vertical
slice. The portfolio declarations and provider governance gates apply to the
@@ -86,14 +95,16 @@ were proven now have independent persistent owners:
| Area | Implemented state | Remaining rollout |
| --- | --- | --- |
| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for all 60 source manifests. Focused and release checks enforce `--require-architecture`; a new module cannot enter the workspace without truthful declaration and repository-local evidence. |
| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for the source manifests in the 2026-08-01 snapshot. Focused and release checks enforce `--require-architecture`; current portfolio counts belong in `STRATEGY_STATUS.md`. |
| External providers | Core validates provider objects/field groups, operations, integration maturity, source authority, bounded reads, freshness/health, idempotency, conflicts, outcome-unknown handling, evidence, correction, reconciliation, outage, classification, purpose, retention, and secret handling. Addresses/CardDAV, Files remote storage, Mail SMTP/IMAP, Calendar CalDAV/ICS/Graph/EWS, and Connectors tabular/sanctions providers declare the contract and tenant-bounded secret-free runtime state. | Registry validation rejects any declared external provider without a sanitized state provider. Future adapters must cross the same gate before activation. |
| Institutional context | Core provides versioned temporal, actor/representation, institution/unit/function/task/mandate/jurisdiction/service/case/party/work-item/workflow/approval/decision/record, legal-basis, evidence, information-governance, external-source, presentation, and geographic references. Events, automation actions, audit records, and the transactional Audit outbox preserve the envelope. | Owning modules must progressively require the relevant subset for consequential operations. |
| Semantic provider contracts | Provider-neutral DTOs and protocols cover Mandate resolution, versioned Service definitions, procedure Parties/representation, and formal Decisions. `govoplan-mandates`, `govoplan-services`, `govoplan-parties`, and `govoplan-decisions` now persist immutable revisions behind those contracts with tenant isolation, bounded reads, replay safety, OCC, migrations, uninstall guards, permissions, APIs, capability documentation, and recovery documentation. | The owners are deliberately headless. Procedure-specific UI remains with consuming modules. |
| Formal-outcome proof | Committee persists bodies, meetings, agenda items, votes, minutes, lifecycle events, and an optional protected local Decision projection. It resolves effective Mandate authority and records reconstructable formal Decisions through `decisions.registry` when installed. OCC, replay safety, tenant isolation, bounded reads, closure guards, and a full-height body/meeting/agenda/vote/minutes WebUI cover the aggregate. Provider-bound external or secret ballots use dynamic adapter capabilities; Committee validates and retains only aggregate counts, receipt/hash, and evidence, and rejects generic manual closure. | Concrete ballot-provider packages remain integration work because their protocol, custody, credentials, and operator evidence depend on the selected provider. This does not leave a Committee-owned ballot contract unspecified. |
| Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Portal exposes a tenant-scoped API and service-directory WebUI whose audiences are derived from trusted principal/function state. Launch re-fetches and re-evaluates the exact Service revision. URL launch is validated; Cases and Workflow Engine provide tenant-bound, replay-safe owner launchers. Cases persists catalogs, immutable revisions, parties, assignments, evidence/decision/record references, deadlines, lifecycle events, exact Service versions, OCC, replay safety, tenant isolation, explicit and assignment-derived object ACLs, uninstall guards, tenant summary state, and list/detail/history/timeline/share WebUI. | Form-bound launch remains unavailable until Forms and Forms Runtime move beyond scaffolds to immutable definitions, validation, submission persistence, and a real owner launcher. Portal fails this case closed and explains the missing capability. |
| Formal-outcome proof | Committee persists bodies, meetings, agenda items, minutes, lifecycle events, and an optional protected local Decision projection. Voting separately owns immutable ballot definitions, frozen electorates, recorded casting/replacement, deterministic tally, certification, challenge, annulment, and provider-backed assurance profiles. Committee consumes `voting.ballots` and retains only deliberation linkage and verified aggregate outcome. A bundled `local_confidential` reference provider encrypts server-readable casts outside native ballot rows and exposes only receipts plus aggregate evidence to Committee. | Native recorded ballots remain reconstructable, and the reference confidential provider is neither secret nor certified: its server can decrypt casts while tallying. Secret/electronic-ballot protocol selection, custody, legal acceptance, independent review, and target evidence remain explicit product decisions. |
| Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Forms owns immutable multi-page/conditional/localized schemas, accessibility assessment and package fragments. Forms Runtime owns definition-aware drafts, validation, submission receipts, status/evidence history, and durable native Case/Workflow handoffs with intent-before-effect and outcome-unknown reconciliation. Portal delegates URL, Case, Form, or Workflow launch to an installed owner while retaining exact Service/Form provenance. | Anonymous intake and concrete attachment/signature providers remain product depth. Portal and Runtime fail closed and explain any absent launcher, target capability, or provider prerequisite. |
| Generic approvals and process execution | Approvals persists exact-subject chains, delegation, separation of duties, quorum, signatures-as-evidence, escalation, OCC, and replay-safe decisions. Campaign proves an exact-version delivery gate. Workflow Engine owns immutable definitions/instances plus API, schedule, event and parent triggers, durable timer/event waits, scale-out claims, current-authority rechecks, and idempotent starts independently of the optional editor. | Policy-authored Approval template selection, concrete signature providers, cron adapters, and broader BPMN execution profiles are product/provider depth on explicit contracts. |
| Device trust and content protection | Identity Trust separates public device keys, epochs, assurance and key-access decisions from login and Access. Encryption separates resource ownership from opaque provider key custody, versioned envelopes, migration evidence, quorum recovery authorization and uninstall proof. Its local server-envelope provider and Files/Postbox adapters prove ciphertext persistence, integrity, rotation/rewrap and fail-closed key loss without leaking plaintext keys across the capability boundary. | Reviewed KMS/HSM/client providers, more owner adapters, target backup/restore/key-loss drills, and E2EE interoperability/certification remain required before stronger deployment claims. |
| Procedure-party proof | Parties persists effective procedure roles, frozen contact snapshots, and representation powers. Existing powers cannot disappear or be silently rewritten; explicit OCC-guarded revocation is required. Cases resolves the provider capability and excludes expired/revoked authority from downstream delivery. | Procedure modules still decide which contextual fields and actions to present. |
| Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Cases, Parties, Mandates, Committee, and Decisions providers. It carries one exact Service version through persisted Case intake, representation and frozen delivery authority, effective Mandate resolution, a body/meeting/agendum/vote/minute sequence, a persisted formal Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. | This is architecture and composition evidence. Signed, release-bound target accessibility, privacy, security, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
| Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Cases, Parties, Mandates, Committee, and Decisions providers. It carries one exact Service version through persisted Case intake, representation and frozen delivery authority, effective Mandate resolution, a body/meeting/agendum/vote/minute sequence, a persisted formal Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. A second executable path proves Portal to exact Form revision, persisted submission, and idempotent replay. | This is architecture and composition evidence. Signed, release-bound target accessibility, privacy, security, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
| Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. Reporting now persists immutable dataset, semantic-model, report, quality-plan, saved-view, and schedule revisions; executes typed semantic queries with quality gates, access checks, replay, pivoting, export/import assessment, and provenance; and exposes the governed analytical WebUI. | Rich dependency/impact traversal, additional expression functions, and policy-specific field visibility can grow on the established contracts without moving connector, transformation, or source ownership. |
| Portfolio and change governance | Projects now persists tenant-safe, immutable portfolio/project/milestone revisions with OCC, replay, lifecycle rules, restricted memberships, Search ACL indexing, outcomes, benefits, dependencies, capacity assumptions, change impact, and institutional references. Its WebUI exposes the planning catalogue and core planning fields. | Advanced planning structures already accepted by the API can receive deeper specialized editors without creating a second Policy, Reporting, Resources, or Goals owner. |
| Product/package governance | Signed configuration packages distinguish reference, product, sector, deployment, and integration classes; preserve parent/evidence provenance; prevent derived packages from loosening constraints; and preflight provider authority, maturity, exact binding, health, freshness, and recovery expectations. Executable product manifests now exist for governed communication and governed data/assurance and are checked in the module matrix. | Both artifacts deliberately remain product-class until target, accessibility, privacy, security, operations, and recovery evidence justifies reference readiness. |
@@ -396,7 +407,9 @@ submodule, configuration fragment, package, or profile.
- This reconciliation is canonical in the meta repository and mirrored to the
Gitea wiki.
- All 60 source manifests carry validated evidence-based architecture metadata.
- All source manifests in the accepted 2026-08-01 baseline carried validated
evidence-based architecture metadata; current counts belong in
`STRATEGY_STATUS.md`.
- External-reference, action/effect, operational-health, ownership, policy,
audit, and documentation primitives compose into one enforced provider
declaration and sanitized runtime-state contract.
@@ -424,6 +437,10 @@ submodule, configuration fragment, package, or profile.
representation/revocation authority; Cases consumes the common resolver.
- `product.service-to-decision` proves both through a portable administrative
service composition.
- Forms owns immutable, versioned schemas while Forms Runtime owns drafts,
server validation, submission receipts, status/evidence history, and exact
Service/Form provenance. Portal delegates Form launch through the runtime
capability and fails closed when it is unavailable.
### 3. Complete governed data, portfolio, and assurance - vertical slices complete
@@ -447,36 +464,79 @@ submodule, configuration fragment, package, or profile.
recovery, accessibility, privacy, security, and operator evidence. This is a
maturity gate, not missing architecture implementation.
## What remains after the executable architecture slice
## What remains within the accepted 2026-08-01 architecture slice
The remaining work is not another Core or cross-module architecture rewrite.
It falls into three explicitly different categories:
It falls into two explicitly different categories, neither of which can be
truthfully completed by adding generic platform code:
1. **Forms and Forms Runtime vertical:** both repositories remain scaffolds.
Full service entry requires immutable form-definition lookup, server-side
validation, draft/submission persistence, status/evidence history,
attachments/signatures/handoff references, replay and OCC, APIs, accessible
WebUI, migrations, recovery, and `forms_runtime.service_launcher`. Portal
already advertises this absence as an availability blocker. Implementing a
placeholder launcher before those controls would violate the accepted
contract.
2. **Concrete provider packages:** the Committee ballot adapter contract is
1. **Concrete provider packages:** the Committee ballot adapter contract is
complete, but a real secret/electronic ballot provider requires a selected
protocol and product decisions for voter eligibility, custody, secrecy,
recount, challenge, retention, and operational assurance. Equivalent future
adapters must satisfy the declared provider and recovery gates.
3. **Target-produced maturity evidence:** `reference_ready`, `supported`, and
Provider selection and certification are tracked in
[Committee #1](https://git.add-ideas.de/GovOPlaN/govoplan-committee/issues/1).
2. **Target-produced maturity evidence:** `reference_ready`, `supported`, and
`lts` cannot be generated from source code. An exact release and deployment
must produce signed, expiring accessibility, privacy, security, operator,
provider, backup/restore, rollback, and recovery-drill evidence. The verifier
and schemas are implemented; the actual claims require those real runs.
A bounded issuer now hashes retained reports, checks role-scoped signing
authority and exact installed-release origin, emits sanitized signed
receipts, verifies them immediately, and exposes admission-enforcing CLI
gates. The real pinned-release evidence run is tracked in
[GovOPlaN #37](https://git.add-ideas.de/GovOPlaN/govoplan/issues/37).
Everything else described as architecture in this document now has a
Forms and Forms Runtime no longer constitute an architecture gap. Conditional
multi-page/localized authoring, package-fragment import, and durable native
Case/Workflow handoffs are implemented. Remaining depth is limited to
anonymous/public identity profiles, concrete file/signature providers, and
additional handoff target adapters. Those use the implemented immutable
definition, runtime, policy, evidence, service-launch, and domain-owner
boundaries rather than requiring another split. Public/provider decisions stay
tracked in Forms Runtime
[#2](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/2) and
[#3](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/3).
Approvals, Voting, Workflow trigger/wait dispatch, Identity Trust, and
Encryption now likewise have repository owners, neutral Core contracts,
persistence, migrations, recovery/disable semantics, documentation and focused
tests. Their remaining tickets concern concrete providers, deeper adapters and
target evidence, not an unresolved institutional architecture boundary.
Everything else described in the accepted baseline of this document now has a
repository owner, versioned contract, bounded implementation, migration and
recovery boundary where state exists, documentation, and executable evidence.
Further work in those modules is product breadth, UX depth, provider adoption,
and evidence renewal.
## Strategic extensions accepted after the baseline
The completed baseline does not imply that institutional product architecture
can no longer grow. The 2026-08-05 strategic review accepted four extensions
that consume the existing contracts without reopening the kernel or moving
domain ownership into Core:
- [Product Experience and Module Boundaries](PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md)
separates technical package topology from stable task/object/product
surfaces; implementation is tracked in Core #283.
- [Federated GovOPlaN Architecture](FEDERATED_GOVOPLAN_ARCHITECTURE.md)
defines governed exchange between autonomous installations; implementation
is tracked in GovOPlaN #41.
- [Assisted and Non-Digital Channels](ASSISTED_AND_NON_DIGITAL_CHANNELS.md)
makes channel inclusion part of the service-to-decision journey; the first
reference proof is tracked in GovOPlaN #42.
- [Institutional Digital Twin](INSTITUTIONAL_DIGITAL_TWIN.md) defines a
time-aware, policy-filtered projection over owner data; implementation is
tracked in GovOPlaN #43.
The eAkte depth required by those journeys is owned by Records and specified in
`govoplan-records/docs/EAKTE_ARCHITECTURE.md`, tracked in Records #1. These are
new product-depth programs with bounded contracts and acceptance journeys, not
evidence that the original institutional semantics or module architecture
failed.
## Delivery tracking
The completed cross-repository architecture epic is
@@ -506,7 +566,23 @@ Its implementation work packages and resulting owners are:
- [GovOPlaN #34](https://git.add-ideas.de/GovOPlaN/govoplan/issues/34):
product and sector package classes; and
- [Docs #19](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/19):
configured architecture, maturity, and source-authority explanations.
configured architecture, maturity, and source-authority explanations;
- [Forms #2](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/2):
immutable reusable definitions and the designer surface; and
- [Forms Runtime #1](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/1):
definition-aware submissions and Portal service launch;
- [Forms #3](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/3) and
[Forms Runtime #4](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/4):
conditional/localized definition depth and governed native handoffs;
- [Approvals #1](https://git.add-ideas.de/GovOPlaN/govoplan-approvals/issues/1)
and [Campaign #22](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/22):
generic exact-subject approval chains and one consequential delivery gate;
- `govoplan-voting`: governed recorded ballots plus fail-closed provider-backed
assurance profiles consumed by Committee; and
- Identity Trust #1 and Encryption #1-#3: public device trust, provider-neutral
key/protection lifecycle, recovery authorization and disable proof, plus a
bounded local server-envelope provider and Files/Postbox fixtures; external
KMS/HSM/client-provider conformance remains separately gated.
Existing Projects #1, Reporting #4, Portal #1, Cases #1, Datasources #1,
Risk Compliance #2, GovOPlaN #14, and GovOPlaN #19 carry product-depth and
@@ -522,6 +598,9 @@ machine-enforced evidence:
retain institutional context from service entry through a persisted case,
party, authority/work context, committee deliberation, decision, observed
communication effect, minute/record, and review references;
- the Portal/Form journey retains the exact published Service and Form
revisions through persisted draft state, validates on the server, and returns
the same submission on an idempotent launch replay;
- the system can answer who acted, for whom, in which function, under which
mandate and jurisdiction, using which rule and evidence versions;
- every implemented external binding declares authority mode, maturity,
Repo-docs-INTERFACE-SURFACE-INVENTORY.md
+229 -103
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:c809e887ba20748da346b8a3 -->
<!-- codex-wiki-sync:28383616531a2f297c3aeca0 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INTERFACE_SURFACE_INVENTORY.md`.
> Origin: `repository`.
@@ -22,7 +22,14 @@ machine-readable field, label, translation, route, API-reference, and module
manifest evidence. This hand-maintained document remains the reviewed product
interpretation and rollout ledger; generated evidence does not replace it.
Snapshot refreshed: 2026-07-22.
Snapshot refreshed: 2026-08-03.
The generated snapshot contains 65 module manifests, 35 WebUI-contributing
repositories, 40 statically declared module routes, 1,156 UI fields, and 836
backend endpoints. All backend endpoints are classified and no stale endpoint
declarations were found. The 234 endpoints without a static WebUI reference are
kept visible as review evidence; they may intentionally serve workers, public
clients, connectors, or external integrations.
Evidence was read from tracked Git `HEAD` in the local GovOPlaN checkouts:
@@ -58,37 +65,73 @@ Inventory states:
| Surface | Owner and code evidence | Audience/access evidence | Primary task and target archetype | Audit / rollout |
| --- | --- | --- | --- | --- |
| Public landing and login | `govoplan-core` `PublicLandingPage`; rendered while no authenticated principal exists | Unauthenticated; maintenance and backend-reachability context are shell inputs | Understand the service and authenticate; public entry | Unreviewed; later public-entry audit |
| Session/bootstrap state | `govoplan-core` `App.tsx` and `AppShell` | All browser sessions during bootstrap | Understand that session/platform state is loading; state contract | Unreviewed; core shell |
| `/` authenticated redirect | `govoplan-core` chooses the first visible navigation destination | Authenticated; result depends on visible nav contributions | Enter the actor's first accessible service area; navigation behavior, not a content page | Unreviewed; focused-view/default-route work must preserve this fallback |
| `/dashboard` fallback | `govoplan-core` `DashboardPage` only when the Dashboard module is absent | Authenticated; no route-specific scope in core | Cross-module starting point; dashboard | Unreviewed; compare with module dashboard before shared changes |
| `/settings` | `govoplan-core` `SettingsPage` | Authenticated; contributed sections and integrations filter internally | Profile, UI/workspace preference, local connection, and user-scoped integration settings; configuration | Unreviewed; Core #225 program |
| Shell chrome | `AppShell`, `Titlebar`, `IconRail`, `BreadcrumbBar`, `HelpMenu`, language menu, unsaved-change provider | Public/authenticated variants; nav filtered later | Tenant/actor context, global navigation, help, language, session and maintenance state | Unreviewed; platform-owned prerequisite for focused views |
| Public landing and login | `govoplan-core` `PublicLandingPage`; rendered while no authenticated principal exists | Unauthenticated; maintenance and backend-reachability context are shell inputs | Understand the service and authenticate; public entry | Core shell contract complete under Core #227: semantic entry/login, uniform reachable/offline/maintenance feedback, keyboard focus, responsive layout and privacy-safe pre-authentication state |
| Session/bootstrap state | `govoplan-core` `App.tsx` and `AppShell` | All browser sessions during bootstrap | Understand that session/platform state is loading; state contract | Core shell contract complete: loading, unreachable, maintenance, authentication-required and module-load failure states use shared status/alert boundaries without erasing the shell |
| `/` authenticated redirect | `govoplan-core` chooses the first visible navigation destination | Authenticated; result depends on visible nav contributions | Enter the actor's first accessible service area; navigation behavior, not a content page | Core route/module-permutation contract complete; permission, module, View and fallback filtering precede navigation and do not execute a domain action |
| `/dashboard` fallback | `govoplan-core` `DashboardPage` only when the Dashboard module is absent | Authenticated; no route-specific scope in core | Cross-module starting point; dashboard | Core fallback and Dashboard module permutations complete; fallback remains usable without the optional Dashboard module |
| `/settings` | `govoplan-core` `SettingsPage` | Authenticated; contributed sections and integrations filter internally | Profile, UI/workspace preference, local connection, and user-scoped integration settings; configuration | Core-owned pattern migration complete in [Core #225](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/225), commit `fa32cca` |
| Shell chrome | `AppShell`, `Titlebar`, `IconRail`, `BreadcrumbBar`, `HelpMenu`, language menu, unsaved-change provider | Public/authenticated variants; nav filtered later | Tenant/actor context, global navigation, help, language, session and maintenance state | Core shell contract complete under Core #227/#225 and Views #2: semantic global controls, scroll-safe rail, visible maintenance state, guarded navigation, configured Docs fallback, optional Search, responsive/theme/i18n checks and module permutations |
## Direct Module Route Contributions
The access guard column reports only the route-level declaration in
`module.ts`. Inner APIs and controls may impose additional checks.
The access column summarizes only the route-level declaration in `module.ts`.
Inner APIs and controls may impose additional checks. Public and compatibility
routes are called out explicitly because they do not have the same manifest
semantics as authenticated navigation routes.
| Route | Owner / render evidence | Route-level access evidence | Primary task | Target archetype | Status / priority |
| --- | --- | --- | --- | --- | --- |
| `/admin` | `govoplan-access` `AdminPage` | Any core `adminReadScopes` | Administer system and tenant concerns assembled from module sections | Administration/configuration | Contributed; unreviewed; P1 under [Core #225](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/225) |
| `/address-book` | `govoplan-addresses` `AddressBookPage` | `addresses:contact:read` | Browse and manage contacts, address books, and lists | Directory/list-detail | Contributed; unreviewed; P2 after Campaign |
| `/calendar` | `govoplan-calendar` `CalendarPage` | `calendar:event:read` | Browse calendars/events and act on calendar data | Directory/list-detail | Contributed; metadata gap; unreviewed; P2 after Campaign |
| `/campaigns` | `govoplan-campaign` `CampaignListPage` | `campaigns:campaign:read` | Find, compare, create, and open campaigns | List-detail entry | Pilot; P1 [Campaign #74](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/74) |
| `/campaigns/:campaignId/*` | `govoplan-campaign` `CampaignResourceRoute` and `CampaignWorkspace` | `campaigns:campaign:read`, plus resource probe | Configure, review, send, and inspect one campaign/version | List-detail workspace containing edit, review, monitoring, and evidence surfaces | Pilot; P1 Campaign #74 |
| `/operator` | `govoplan-campaign` `OperatorQueuePage` | `campaigns:campaign:read` and any of queue, control, retry, or reconcile | Monitor and intervene in campaign jobs through authority-specific controls | Monitoring/work queue | Pilot; durable queue controls delivered in [Campaign #78](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/78); #74 audit remains |
| `/reports` | `govoplan-campaign` `AggregateReportsPage` | `campaigns:report:read` | Compare privacy-protected cross-campaign outcome totals without recipient detail, diagnostics, export, or drill-down | Aggregate reporting | Pilot; aggregate-reader surface delivered in [Campaign #80](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/80); #74 audit remains |
| `/templates` | `govoplan-campaign` `TemplatesPage` | No route guard declared in `module.ts` | Browse/manage campaign templates | Directory/list-detail | Pilot audit; permission intent must be verified; P2 |
| `/dashboard` | `govoplan-dashboard` `DashboardPage` | No route-specific scope | Assemble module-provided actionable widgets | Dashboard | Contributed; unreviewed; P2 |
| `/docs` | `govoplan-docs` `DocsPage` | Docs read or system/tenant settings read scopes | Read configured, available, and evidence-aware documentation | Documentation directory/reference | Contributed; unreviewed; P1 [Docs #15](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/15) after initial pattern content |
| `/files` | `govoplan-files` `FilesPage` | `files:file:read` | Browse folders/files and perform managed-file work | Directory/explorer | Contributed; metadata gap; unreviewed; P2 after Campaign |
| `/idm` | `govoplan-idm` `IdmPage` | Any IDM assignment/write or organization function-assign scope | Inspect and govern identity/function assignments | List-detail/configuration | Contributed; unreviewed; P2 |
| `/mail` | `govoplan-mail` `MailboxPage` | `mail:mailbox:read` | Browse mailboxes and messages | Directory/list-detail | Contributed; metadata gap; unreviewed; P2 after Campaign |
| `/notifications` | `govoplan-notifications` `NotificationCenterPage` | `notifications:notification:read` | Inspect and acknowledge notification state | List-detail/inbox | Contributed without a nav item or backend frontend metadata; navigation intent unknown; P2 discovery |
| `/ops` | `govoplan-ops` `OpsPage` | Ops read or system/tenant settings read scopes | Inspect runtime health and readiness | Monitoring | Contributed; unreviewed; P2 |
| `/organizations` | `govoplan-organizations` `OrganizationsPage` | Organization model/unit/function or admin settings read scopes | Model and inspect organizational structures/functions | Directory/list-detail | Contributed; unreviewed; P2 |
| `/scheduling` | `govoplan-scheduling` `SchedulingPage` | `scheduling:schedule:read` | Plan and decide scheduling requests and availability | List-detail/guided decision | Contributed; metadata gap; unreviewed; P2 |
| Routes | Owner | Route-level access | Primary archetype | Migration issue |
| --- | --- | --- | --- | --- |
| `/admin` | Access | Any declared administration/read scope | Administration/configuration host | Access pattern migration complete in [Access #19](https://git.add-ideas.de/GovOPlaN/govoplan-access/issues/19), commit `1409dbf`; shared host contract complete in [Core #225](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/225) |
| `/address-book` | Addresses | `addresses:contact:read` | Governed source directory, contact/list detail, external-provider operation, governance facts, and reversible correction | Addresses pattern migration complete in [Addresses #23](https://git.add-ideas.de/GovOPlaN/govoplan-addresses/issues/23), commit `f9a7185` |
| `/approvals` | Approvals | `approvals:workspace:read` | Work queue/guided decision | Approvals pattern migration complete in [Approvals #3](https://git.add-ideas.de/GovOPlaN/govoplan-approvals/issues/3), commit `24e9559` |
| `/calendar` | Calendar | `calendar:event:read` | Full-height calendar workspace with filterable collection/agenda sidebar, continuous and bounded date views, guarded VEVENT and source editors, synchronized-source status, durable outbox recovery, and destructive remote-move evidence | Calendar pattern migration complete in [Calendar #22](https://git.add-ideas.de/GovOPlaN/govoplan-calendar/issues/22), commit `d7fd944` |
| `/campaigns`, `/campaigns/:campaignId/*`, `/campaigns/queue`, `/campaigns/reports` | Campaign | Campaign read/report/control scopes | List-detail, guided review, monitoring, reporting | Campaign pattern pilot complete in [Campaign #74](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/74); bounded product features such as watched-folder policy remain independently tracked |
| `/operator` | Campaign | Campaign read plus queue/control scope | Compatibility redirect to `/campaigns/queue` | Campaign #74 complete; redirect remains declared for saved links and is retired under the compatibility policy rather than through the UI migration |
| `/cases`, `/cases/:caseId` | Cases | `cases:case:read` | Governed case directory and detail workspace with guarded OCC lifecycle editor, provider-owned references, immutable timeline/history, and confirmed object-access editor | Cases pattern migration complete in [Cases #4](https://git.add-ideas.de/GovOPlaN/govoplan-cases/issues/4), commit `43b4cc8` |
| `/committee` | Committee | `committee:workspace:read` | Governed workspace | Committee pattern migration complete in [Committee #2](https://git.add-ideas.de/GovOPlaN/govoplan-committee/issues/2), commit `e64af30` |
| `/dashboard` | Dashboard | No route-specific scope | View-specific personal workspace with module/permission-filtered widget library, guarded four-column composition, nested widget settings, server/browser fallback, and optimistic layout persistence | Dashboard pattern migration complete in [Dashboard #3](https://git.add-ideas.de/GovOPlaN/govoplan-dashboard/issues/3), commit `da3947f` |
| `/dataflow` | Dataflow | Pipeline read/admin | Governed library, guarded graph/constrained-SQL definition editor, typed node inspector, bounded intermediate preview, automation triggers, and durable run/deployment evidence | Dataflow pattern migration complete in [Dataflow #20](https://git.add-ideas.de/GovOPlaN/govoplan-dataflow/issues/20), commit `109ddcd` |
| `/datasources` | Datasources | Catalogue read/source admin | Governed catalogue, staging preflight, optional-origin directory, authority editor, and immutable evidence | Datasources pattern migration complete in [Datasources #7](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/7), commit `6406ce7` |
| `/distribution-lists` | Distribution Lists | List read/write/admin | Governed directory, immutable-revision editor, expansion preview, and evidence register | Distribution Lists pattern migration complete in [Distribution Lists #8](https://git.add-ideas.de/GovOPlaN/govoplan-dist-lists/issues/8), commit `6cdd804` |
| `/docs` | Docs | Documentation or settings read | Documentation/reference | Configured-system workflow/reference/pattern help complete in [Docs #15](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/15), commit `abe2f78` |
| `/files` | Files | `files:file:read` | Directory/explorer | Files pattern migration complete in [Files #42](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/42), commit `d8ae506` |
| `/forms` | Forms | `forms:definition:read` | Definition library/editor | Forms pattern migration complete in [Forms #4](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/4), commit `e505536` |
| `/forms-runtime`, `/forms-runtime/:instanceId` | Forms Runtime | Participate or workspace read | Guided form execution | Forms Runtime pattern migration complete in [Forms Runtime #5](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/5), commit `07dd35b` |
| `/idm` | IDM | Assignment, function-change, relationship, or organization scopes | Directory/governed change | IDM pattern migration complete in [IDM #12](https://git.add-ideas.de/GovOPlaN/govoplan-idm/issues/12), commit `d864317` |
| `/mail`, `/mail/bounces` | Mail | Mailbox or bounce read/manage | Directory/explorer, operational evidence | Mail pattern migration complete in [Mail #20](https://git.add-ideas.de/GovOPlaN/govoplan-mail/issues/20), commit `7844d9c` |
| `/notifications` | Notifications | `notifications:notification:read` | Inbox/list-detail with guarded recipient state, confirmed local cancellation/dispatch, and sanitized delivery evidence | Notifications pattern migration complete in [Notifications #4](https://git.add-ideas.de/GovOPlaN/govoplan-notifications/issues/4), commit `ad6a31f` |
| `/ops` | Ops | Operations or settings read | Monitoring/evidence with contextual run, drain, readiness-blocker, and recovery guidance | Ops pattern migration complete in [Ops #4](https://git.add-ideas.de/GovOPlaN/govoplan-ops/issues/4), commit `2b32643` |
| `/organizations` | Organizations | Model/unit/function or settings read | Directory/hierarchy editor | Organizations pattern migration complete in [Organizations #7](https://git.add-ideas.de/GovOPlaN/govoplan-organizations/issues/7), commit `97acfcb` |
| `/portal` | Portal | `portal:service:read` | Explained service directory and governed handoff | Portal pattern migration complete in [Portal #2](https://git.add-ideas.de/GovOPlaN/govoplan-portal/issues/2); durable evidence in `govoplan-portal/docs/INTERFACE_PATTERN_MIGRATION.md` |
| `/postbox` | Postbox | `postbox:postbox:read` | Inbox/list-detail | Postbox pattern migration complete in [Postbox #26](https://git.add-ideas.de/GovOPlaN/govoplan-postbox/issues/26), commit `a97eb3b` |
| `/projects` | Projects | `projects:project:read` | Revisioned list-detail/project workspace | Projects pattern migration complete in [Projects #2](https://git.add-ideas.de/GovOPlaN/govoplan-projects/issues/2); durable evidence in `govoplan-projects/docs/INTERFACE_PATTERN_MIGRATION.md` |
| `/reporting`, `/reports` | Reporting | `reporting:definition:read` | Governed report catalogue, analytical workspace and evidence | Reporting pattern migration complete in [Reporting #8](https://git.add-ideas.de/GovOPlaN/govoplan-reporting/issues/8); durable evidence in `govoplan-reporting/docs/INTERFACE_PATTERN_MIGRATION.md` |
| `/risk-compliance` | Risk Compliance | Workspace or sanctions read | Immutable source evidence, version-pinned screening, list-detail review, and revisioned assurance graph with explicit blockers and consequences | Risk Compliance pattern migration complete in [Risk Compliance #8](https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance/issues/8), commit `24d80a6` |
| `/scheduling` | Scheduling | `scheduling:schedule:read` | List-detail/guided decision | Scheduling pattern migration complete in [Scheduling #8](https://git.add-ideas.de/GovOPlaN/govoplan-scheduling/issues/8), commit `c17cbda` |
| `/scheduling/public/:requestId/:token` | Scheduling | Public signed token | Public participation | Scheduling #8 complete in `c17cbda` |
| `/search` | Search | `search:result:read` | Keyboard-first global/context overlay and full results fallback | Search pattern migration complete in [Search #4](https://git.add-ideas.de/GovOPlaN/govoplan-search/issues/4); durable evidence in `govoplan-search/docs/INTERFACE_PATTERN_MIGRATION.md` |
| `/templates` | Templates | Template read/write/publish/render/admin | Governed library, immutable-revision editor, compatibility preview, and render evidence | Templates pattern migration complete in [Templates #5](https://git.add-ideas.de/GovOPlaN/govoplan-templates/issues/5), commit `72fafa2` |
| `/voting` | Voting | `voting:ballot:read` | Governed ballot workspace | Voting pattern migration complete in [Voting #1](https://git.add-ideas.de/GovOPlaN/govoplan-voting/issues/1), commit `2625990` |
| `/workflow` | Workflow | Definition read or instance admin | Native BPMN editor, governed revision actions and execution evidence | Workflow pattern migration complete in [Workflow #15](https://git.add-ideas.de/GovOPlaN/govoplan-workflow/issues/15); durable evidence in `govoplan-workflow/docs/INTERFACE_PATTERN_MIGRATION.md` |
## Final Module Closure Evidence
The final five module-owned work packages complete the 2026-08-03 rollout
snapshot. Their module documents are the durable detailed inventories; the
table below records the cross-product closure evidence.
| Owner | Dominant archetype and consequential boundary | Focused evidence |
| --- | --- | --- |
| Workflow | Definition list-detail plus specialized native BPMN editor; save/activate/archive/delete/reset and instance transitions remain revisioned, confirmed, and Engine-owned | Shared dialogs/status/alerts/help, dirty-navigation guard, keyboard palette insertion, edge inspector alternative, responsive/reduced-motion contract, TypeScript and focused structure test |
| Search | Focus-contained global/context overlay plus URL-stable full results; filters only narrow permission-aware source results | F3/Ctrl/Cmd+K, listbox keyboard navigation, provider-partial diagnostics, shared controls/help, narrow layout and focused overlay/interface tests |
| Reporting | Three-region governed analytical workspace; runs, schedules, exports and publications retain purpose, permission, source and policy provenance | Shared grid/dialog/status/help, keyboard-explainable Run blockers, responsive task order, provider/semantic backend tests and focused interface test |
| Projects | Revisioned list-detail planning workspace; visibility and saves are ACL/OCC-governed and retain a change reason | Shared dialog/status/help/field labels, save errors attached to the editor, semantic list controls, responsive/focus contract and focused interface test |
| Portal | Explained service directory and exact-revision provider handoff; Portal never owns the launched case/form/workflow effect | Shared status/alert/toggle/help/blocker controls, stable disabled Open action with actor/action/destination, guarded navigation, responsive layout and focused interface test |
Future WebUI modules and newly added routes are not grandfathered by this
snapshot. They must meet the same surface definition of done in their owning
feature issue and pass the source/runtime inventory gates; they do not reopen
this finite migration program unless the pattern contract itself changes.
## Manifest And Runtime Route Alignment
@@ -98,28 +141,27 @@ loading reason about the configured interface without executing module UI code.
is recorded here as an evidence gap; this inventory does not infer whether each
gap is intentional.
| Module | `module.ts` routes | Backend manifest frontend routes | Backend nav alignment | Result |
| --- | --- | --- | --- | --- |
| Access | `/admin` | `/admin` | Aligned | Described |
| Addresses | `/address-book` | `/address-book` | Aligned | Described |
| Admin | No direct route; `admin.sections` | None | Not applicable | Composed surface |
| Audit | No direct route; `admin.sections` | None | Not applicable | Composed surface |
| Calendar | `/calendar` | None | `/calendar` nav exists | Metadata gap |
| Campaign | Five routes | None | Four top-level nav items exist | Metadata gap; wildcard resource route is also undescribed |
| Dashboard | `/dashboard` | `/dashboard` | Aligned | Described |
| Docs | `/docs` | `/docs` | Aligned | Described |
| Files | `/files` | None | `/files` nav exists | Metadata gap |
| IDM | `/idm` | `/idm` | Aligned | Described |
| Mail | `/mail` | None | `/mail` nav exists | Metadata gap |
| Notifications | `/notifications` | No frontend metadata | No nav item | Metadata and discovery gap |
| Ops | `/ops` | `/ops` | Aligned | Described |
| Organizations | `/organizations` | `/organizations` | Aligned | Described |
| Policy | No direct route; `admin.sections` | None | Not applicable | Composed surface |
| Scheduling | `/scheduling` | None | `/scheduling` nav exists | Metadata gap |
The generated comparison is aligned for all authenticated canonical routes.
Two deliberate exceptions remain visible:
Before a release claims a complete configured-system route inventory, add a
contract check or explicit exceptions so executable routes and manifest
metadata cannot silently diverge.
- Campaign contributes `/operator` as a compatibility redirect for saved View
projections; its canonical and manifest-declared destination is
`/campaigns/queue`.
- Scheduling contributes `/scheduling/public/:requestId/:token` through the
separate `publicRoutes` contract. Authenticated manifest routes intentionally
do not describe public signed-token entry points yet.
Admin, Audit, Policy, Tenancy, and Views contribute composed administration or
settings surfaces rather than direct routes. Their migration issues are
[Admin #8](https://git.add-ideas.de/GovOPlaN/govoplan-admin/issues/8),
[Audit #8](https://git.add-ideas.de/GovOPlaN/govoplan-audit/issues/8),
[Policy #11](https://git.add-ideas.de/GovOPlaN/govoplan-policy/issues/11),
[Tenancy #6](https://git.add-ideas.de/GovOPlaN/govoplan-tenancy/issues/6), and
[Views #2](https://git.add-ideas.de/GovOPlaN/govoplan-views/issues/2).
Release evidence must continue to run the generated inventory and manifest
shape checks so new executable routes, public routes, aliases, and composed
surfaces cannot silently diverge from their declared metadata.
## Composed Surfaces And Extension Points
@@ -128,25 +170,108 @@ enabled and the actor passes the declared filters.
| Host surface | Contributor and evidence | Contributed regions/actions | Pattern implication | Audit |
| --- | --- | --- | --- | --- |
| `/admin` | Access host (`AdminPage`) | System tenants/users/roles, tenant users/groups/roles/API keys/settings, function-role mappings, user/group mail and file connector scopes | One stable admin information architecture must contain both host-owned and contributed sections | Unreviewed; P1 Core #225 |
| `/admin` | `govoplan-admin` `admin.sections` | Overview; system settings; configuration changes; configuration packages; role/group templates; module management | Configuration, guided operations, review/preflight, consequence | In progress under Core #225; surface-level evidence still needed |
| `/admin` | `govoplan-audit` `admin.sections` | System audit; tenant audit | Evidence/provenance and reporting | Unreviewed |
| `/admin` | `govoplan-files` `admin.sections` and `files.connectors` | System and tenant file connections plus scoped connector managers used by Access | Adaptive configuration, discovery/test, policy and credentials | First migration family in Core #225; verification incomplete in this inventory |
| `/admin` | `govoplan-organizations` `admin.sections` | Tenant organization settings | Configuration/list-detail | Unreviewed |
| `/admin` | `govoplan-policy` `admin.sections` | System, tenant, group, and user retention | Effective value, source/provenance, consequential configuration | Unreviewed; Core #225 phase 4 |
| `/admin` and `/settings` | `govoplan-mail` `mail.profiles` | System/tenant/group/user mail profile and policy managers | Same server/credential/policy grammar as file connectors | Unreviewed; Core #225 mail migration |
| `/settings` | Core host | Profile; interface; workspace; local connection | Personal configuration with adaptive forms and immediate feedback | Unreviewed |
| `/settings` | Files and Mail named capabilities | User-scoped file connections and mail profiles/policy | Optional integration regions disappear cleanly when capability absent | Unreviewed |
| `/settings` | `govoplan-notifications` `settings.sections` | Notification preferences | Personal configuration | Unreviewed |
| `/dashboard` | Dashboard host and `dashboard.widgets` | Installed-modules widget; Ops health widget when Ops contributes it | Widget ordering, staleness, permissions, destination behavior | Unreviewed |
| `/organizations` | IDM `organizations.functionActions` | Action leading to assignment view filtered by IDM scopes | Cross-module context action through explicit capability | Unreviewed |
| Campaign attachments/import | Files `files.fileExplorer` | Folder tree, managed chooser, file listing/pattern resolution/sharing | Optional domain composition without sibling-private imports | Pilot audit under Campaign #74 |
| Campaign review/send | Mail runtime `mail.devMailbox` | Mock-mail verification when backend advertises runtime capability | Optional review stage with unavailable/optional states | Pilot audit under Campaign #63/#62 |
| `/admin` | Access host (`AdminPage`) | System tenants/users/roles, tenant users/groups/roles/API keys/settings, function-role mappings, user/group mail and file connector scopes | One stable admin information architecture must contain both host-owned and contributed sections | Pattern migration, contextual help, explained permission/protection states, optional-module blockers, localization, and focused evidence complete in Access #19 (`1409dbf`); Core #225 shared host contract complete |
| `/admin` | `govoplan-admin` `admin.sections` | Overview; system settings; configuration changes; configuration packages; role/group templates; module management | Configuration, guided operations, review/preflight, consequence | Pattern migration, contextual help, explained permission/protection/applicability states, guarded consequential actions, localization, and focused evidence complete in Admin #8 (`d428f33`) |
| `/admin` | `govoplan-tenancy` `admin.sections` | System tenant registry and active-tenant settings | Administration directory, effective configuration, lifecycle consequence | Pattern migration, contextual help, explained permission/lifecycle/system-policy states, dirty-state guards, localization, and focused evidence complete in Tenancy #6 (`e76fe16`) |
| `/admin` | `govoplan-audit` `admin.sections` | System audit; tenant audit | Evidence/provenance and reporting | Pattern migration, localized evidence projection, contextual help, and focused tests complete in Audit #8 (`6d3fcc1`) |
| `/admin` | `govoplan-files` `admin.sections` and `files.connectors` | System and tenant file connections plus scoped connector managers used by Access | Adaptive configuration, discovery/test, policy and credentials | Pattern migration, contextual help, blocker explanations and focused evidence complete in Files #42 (`d8ae506`) |
| `/admin` | `govoplan-organizations` `admin.sections` | Tenant organization settings | Configuration/list-detail | Pattern migration, tenant-owned provenance, contextual help, guarded settings/editor drafts, explained permission states, localization and focused evidence complete in Organizations #7 (`97acfcb`) |
| `/admin` | `govoplan-policy` `admin.sections` | System, tenant, group, and user retention | Effective value, source/provenance, consequential configuration | Pattern migration complete in Policy #11 (`f964ed7`) with Core editor contract `fa32cca` |
| `/admin` and `/settings` | `govoplan-mail` `mail.profiles` | System/tenant/group/user mail profile and policy managers | Same server/credential/policy grammar as file connectors | Pattern migration, contextual help, policy/target/permission blockers and focused evidence complete in Mail #20 (`7844d9c`; shared test-reason contract Core `2d0551a`) |
| `/settings` | Core host | Profile; interface; workspace; local connection | Personal configuration with adaptive forms and immediate feedback | Pattern migration complete in Core #225 (`fa32cca`) |
| `/settings` | Files and Mail named capabilities | User-scoped file connections and mail profiles/policy | Optional integration regions disappear cleanly when capability absent | Files #42, Mail #20 and Core #225 complete |
| `/admin` and `/settings` | `govoplan-views` `admin.sections`, `settings.sections`, and `views.runtime` | System/tenant definition and assignment editors, personal/group editors, global selector | Versioned presentation projection with inheritance, lockout safeguards, optional directory targets, and no authorization effect | Pattern migration, contextual help, localized selector/editor, guarded drafts, explained inherited/permission/capability states, and focused evidence complete in Views #2 (`c125f33`) |
| `/settings` | `govoplan-notifications` `settings.sections` | Notification preferences | Personal configuration | Pattern migration, contextual help, permission/target explanation, typed toggles and focused evidence complete in Notifications #4 (`ad6a31f`) |
| `/dashboard` | Dashboard host and `dashboard.widgets` | Installed-modules widget; Ops health widget when Ops contributes it | Widget ordering, staleness, permissions, destination behavior | Pattern migration, view-aware composition, keyboard/drag alternatives, responsive packing, module filtering and focused evidence complete in Dashboard #3 (`da3947f`) |
| `/organizations` | IDM `organizations.functionActions` | Action leading to assignment view filtered by IDM scopes | Cross-module context action through explicit capability | IDM pattern migration complete in IDM #12 (`d864317`) |
| Campaign attachments/import | Files `files.fileExplorer` | Folder tree, managed chooser, file listing/pattern resolution/sharing | Optional domain composition without sibling-private imports | Campaign #74 pilot complete; watched-folder and duplicate-attachment product policy remain independent Campaign #60/#61 features |
| Campaign review/send | Mail runtime `mail.devMailbox` | Mock-mail verification when backend advertises runtime capability | Optional review stage with unavailable/optional states | Explicit intervention and review-progress vocabulary delivered in Campaign #63; send modes/progress delivered in #62/#79 |
Other named capability exports (`files.connectors`, `organizations.functionPicker`,
and mail profile validation) are contracts consumed inside the composed surfaces
above; they are not independent routes.
## Core Configuration Surface Map
Core #225 now supplies and verifies the platform-owned configuration contract.
The durable Core inventory is
`govoplan-core/docs/INTERFACE_PATTERN_MIGRATION.md`.
| Surface / code evidence | Primary task | Target pattern | Material consequence/state | Completion evidence |
| --- | --- | --- | --- | --- |
| `/settings` (`SettingsPage`) | Change personal profile, interface/workspace preferences, or local development connection | Two-zone typed settings workspace | Changes are user-scoped; save and test actions distinguish clean, busy, and active states | Contextual help, unsaved guard, typed controls and keyboard-explainable disabled actions in Core `fa32cca` |
| Reusable credentials (`CredentialEnvelopeManager`) | Compare and configure scoped reusable authentication material | Repeated administration plus adaptive create/edit | Secret values are write-only; permission and missing-owner states block mutation explicitly; deletion can break dependent connections | Actionable blocker, stable row actions, typed references, unsaved guard and shared destructive confirmation |
| Retention (`RetentionPolicyManagement`) | Inspect effective retention and narrow permitted local values | Effective-policy editor | Parent locks, source paths and write authority control whether sensitive evidence can be retained | Typed narrowing controls, source-path help, lock/target/permission blockers and clean/loading/save reasons |
| Shared configuration primitives | Compose module-owned settings without sibling-private imports | Platform behavior contract | Consequence, focus, help, async, confirmation and permission semantics remain consistent | Core component suites, 121 module-system tests and full-product type/build/bundle gates |
No primary Core configuration flow requires raw JSON. Expert JSON remains
limited to diagnostics, interchange, conflict evidence, or read-only inspection.
## Policy Surface Map
Policy #11 verifies the four composed retention sections. The durable
module-level inventory is
`govoplan-policy/docs/INTERFACE_PATTERN_MIGRATION.md`.
| Surface / code evidence | Primary task | Target pattern | Material consequence/state | Completion evidence |
| --- | --- | --- | --- | --- |
| System retention | Set the instance ceiling and run retention | Effective-policy editor plus destructive operation | An applied run can irreversibly redact/delete retained content; dry-run and applied evidence remain distinct | Core source-path/lock contract, permission and busy reasons, shared confirmation, typed/filterable outcome grid and audit-oriented wording |
| Tenant retention | Narrow the inherited system ceiling | Effective-policy editor | Tenant policy cannot silently loosen its parent | Core typed controls, effective path and parent-lock explanation |
| Group and user retention | Select an authorized target and narrow inherited policy | Targeted effective-policy editor | Selection exposes only bounded account/group labels; no retained content is returned | Delta-backed target loading, retry, missing-target blocker and responsive shared admin composition |
Automated evidence for Policy `f964ed7` comprises 50 backend/manifest tests,
the Policy interface structural gate, 65 manifest-shape checks, and the
full-product TypeScript/Vite build with structural localization, theme and
bundle-budget gates. Policy uses no sibling-private imports.
## Files Surface Map
Files #42 classifies and verifies the complete Files-owned route and composition
boundary. The durable module-level inventory is
`govoplan-files/docs/INTERFACE_PATTERN_MIGRATION.md`.
| Surface / code evidence | Primary task | Target pattern | Material consequence/state | Completion evidence |
| --- | --- | --- | --- | --- |
| `/files` (`FilesPage`) | Browse spaces/folders and repeatedly act on current content | Full-height directory/explorer | Navigation is low consequence; upload, synchronize, move, copy and share are medium; delete is high | Stable two-pane composition, contextual help, selection/permission/state-specific disabled reasons, shared confirmation and responsive collapse |
| Upload/archive, transfer, rename and connector-import dialogs | Supply, validate and review one bounded change | Adaptive create/edit or guided import | Writes managed content and may resolve conflicts or import untrusted bytes | Shared dialogs/drop zone, bounded archive preflight, conflict review, explicit confirmation and no browser-native confirmation |
| Share/access explanation | Inspect or change who can use a resource | Review/decision | Grants can disclose content; delete/revoke changes access | Shared access explanation, action components and destructive confirmation; backend redaction remains authoritative |
| File connector tree and connection/credential dialogs | Compare and configure external endpoints and reusable credentials | Administration plus adaptive create/edit | Endpoint, secret and capability changes can enable remote access | Shared connection tree/forms/advanced panel, endpoint discovery and login test, unsaved-change guard, read-only deployment provenance and actionable disabled reasons |
| Connector policy card | Narrow effective connector use | Effective-policy editor | Inherited deny/allow rules affect lower scopes | Typed selectors, deny-precedence warning, effective sources, contextual admin help and permission blocker |
| `files.widget.spaces` | See available spaces and enter Files | Dashboard widget | Space/provider names remain permission-filtered | Shared loading, alert and status components; bounded configuration and refresh |
| `files.fileExplorer` capability | Select a governed managed snapshot for another module | Directory chooser | Exact file/version becomes another module's governed input | Capability-only composition, no sibling-private import, stable chooser/confirmation and exact snapshot evidence |
Automated evidence for commit `d8ae506` comprises 104 Files backend tests,
three focused Files WebUI structure tests, the full-product TypeScript/Vite
build, structural localization audit, theme contract and bundle budget. Shared
Dialog and disabled-tooltip behavior provide focus entry/return and
keyboard-reachable explanations; responsive source order is guarded at 1050 px
and 760 px. Secrets are not returned to the WebUI, and JSON remains only an
advanced provider-compatibility escape hatch rather than the primary editor.
## Mail Surface Map
Mail #20 classifies and verifies the complete Mail-owned route and composition
boundary. The durable module-level inventory is
`govoplan-mail/docs/INTERFACE_PATTERN_MIGRATION.md`.
| Surface / code evidence | Primary task | Target pattern | Material consequence/state | Completion evidence |
| --- | --- | --- | --- | --- |
| `/mail` (`MailboxPage`) | Browse an authorized provider mailbox without changing it | Full-height directory/explorer | Message metadata and content are private; every provider read is bounded and non-mutating | Stable three-pane composition, contextual help, explicit no-profile blocker, refresh reasons, keyboard rows, paging and responsive collapse |
| Mail profile tree and profile/server/credential dialogs | Compare and configure reusable transport identities | Administration plus guided/adaptive create/edit | Endpoint and credential changes can enable external effects | Shared connection tree/dialog/stage rail/forms, focused hierarchy editors, unsaved guard, connection tests, permission/target blockers and disabled-save reasons |
| Mail policy card | Narrow profile visibility, lower-scope definitions and transport/address patterns | Effective-policy editor | Inherited allow/deny rules affect delivery and lower scopes | Typed selectors and controls, effective source path, lock/read-only blocker, dirty-save state and contextual admin help |
| `/mail/bounces` watcher table | Configure and explicitly scan bounded IMAP evidence sources | Operational administration | Provider access changes durable source cursors and evidence | Shared grid/status/loading/alerts, actionable no-profile and busy states, field help and stable row actions |
| `/mail/bounces` observations and watcher removal | Review sanitized delivery outcomes or stop future scans | Evidence/reporting plus destructive confirmation | Recipient diagnostics are sensitive; watcher removal retains existing evidence | Bounded sanitized rows and shared confirmation with retained-evidence consequence |
| `mail.profiles` and reference-selector capabilities | Select/validate Mail-owned transport from another module | Governed capability composition | A selected identity can perform external effects | Stable references, Mail-owned authorization/secret resolution, no sibling-private imports and clean optional absence |
Automated evidence for Mail commit `7844d9c` and Core commit `2d0551a`
comprises 114 Mail backend tests, Mail's focused UI/model/structure suite, the
Core shared mail-component suite, 65 manifest-shape checks and the full-product
TypeScript/Vite build with structural localization, theme and bundle-budget
gates. Shared Dialog and disabled-tooltip behavior provides focus containment,
return and keyboard-reachable explanations. Responsive source order is guarded
at 1250 px, 900 px and 760 px. Passwords remain write-only, mailbox responses
are bounded, and bounce evidence excludes raw provider messages.
## Campaign Pilot Surface Map
Campaign is detailed first because it exercises almost every archetype. The
@@ -163,70 +288,71 @@ prove that the composition or states satisfy the pattern.
| Surface / code evidence | Primary task | Target pattern | Material consequence/state | Known issue / rollout |
| --- | --- | --- | --- | --- |
| Campaign list (`CampaignListPage`) | Find, compare, create, open | List-detail entry | Campaign lifecycle/status and creation | Audit in [#74](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/74); guided entry [#35](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/35) |
| Overview (`CampaignOverviewPage`) | Understand/edit campaign identity, version, access, lifecycle | Object overview plus adaptive edit | Lock/archive/delete/access changes need real consequence and reversibility wording | #74 remaining audit |
| Fields (`CampaignFieldsPage`) | Define recipient/template field schema | Structured editor | Schema changes can invalidate recipient/template data | #74 audit |
| Attachments/files (`AttachmentsDataPage`, `AttachmentRulesOverlay`) | Select sources and attachment/ZIP rules | Directory chooser plus adaptive rule editor | Missing or mismatched files affect built messages | #74; attachment-detail [#59](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/59) |
| Recipients (`RecipientDataPage`) | Select/import/map/edit recipients, address fields and per-recipient values/files | Import/mapping plus list-detail editor | Personal data, validation, bulk activation, file links | Consolidated editor delivered in #67; #74 remaining audit and guided entry #35 |
| Template (`TemplateDataPage`, placeholder/expression dialogs) | Author subject/body and preview substitutions | Adaptive editor plus stable preview | Generated communication content and unresolved expressions | #74; stable overlay [#73](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/73) |
| Mail settings (`MailSettingsPage` settings view) | Select/configure campaign mail transport | Adaptive configuration | Credentials, SMTP/IMAP destinations, test outcomes | #74; align with Core #225 mail pattern |
| Campaign settings (`GlobalSettingsPage` settings view) | Configure campaign behavior | Adaptive configuration | Can alter validation/build/send behavior | #74 audit |
| Mail policy (`MailSettingsPage` policy view) | Inspect/override effective mail policy | Effective policy/provenance editor | Inheritance and locks affect allowed delivery | #74; Core #225 policy pattern |
| Campaign policy (`GlobalSettingsPage` policy view) | Inspect/override campaign policy | Effective policy/provenance editor | Inheritance, actor authority, and blocked edits | #74; Core #225 policy pattern |
| Review/send (`ReviewSendPage`) | Validate, build, mock-test, confirm/send, inspect results | Guided review/decision plus durable progress | External communication, bounded synchronous execution, persisted queue mode, partial effects, retries, evidence | Bounded synchronous and explicit/persisted queued modes delivered in [#62](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/62) and [#79](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/79); [#63](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/63) wording and #74 audit remain |
| Campaign list (`CampaignListPage`) | Find, compare, create, open | List-detail entry | Campaign lifecycle/status and creation | #74 and guided entry [#35](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/35) complete |
| Overview (`CampaignOverviewPage`) | Understand/edit campaign identity, version, access, lifecycle | Object overview plus adaptive edit | Lock/archive/delete/access changes expose consequence, reversibility, owner/access and lifecycle evidence | #74 complete; lifecycle policy is independently extended in Campaign #26 |
| Fields (`CampaignFieldsPage`) | Define recipient/template field schema | Structured editor | Schema changes can invalidate recipient/template data | #74 complete |
| Attachments/files (`AttachmentsDataPage`, `AttachmentRulesOverlay`) | Select sources and attachment/ZIP rules | Directory chooser plus adaptive rule editor | Missing or mismatched files affect built messages | #74 and attachment-detail [#59](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/59) complete |
| Recipients (`RecipientDataPage`) | Select/import/map/edit recipients, address fields and per-recipient values/files | Import/mapping plus list-detail editor | Personal data, validation, bulk activation, file links | Consolidated editor #67, guided entry #35 and #74 audit complete; independent bulk action #68 remains product scope |
| Template (`TemplateDataPage`, placeholder/expression dialogs) | Author subject/body and preview substitutions | Adaptive editor plus stable preview | Generated communication content and unresolved expressions | #74 and stable overlay [#73](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/73) complete |
| Mail settings (`MailSettingsPage` settings view) | Select/configure campaign mail transport | Adaptive configuration | Credentials, SMTP/IMAP destinations, test outcomes | #74 and Core #225 shared mail pattern complete; final credential hierarchy remains Mail #10 |
| Campaign settings (`GlobalSettingsPage` settings view) | Configure campaign behavior | Adaptive configuration | Can alter validation/build/send behavior | #74 complete |
| Mail policy (`MailSettingsPage` policy view) | Inspect/override effective mail policy | Effective policy/provenance editor | Inheritance and locks affect allowed delivery | #74 and Core #225 effective-policy pattern complete |
| Campaign policy (`GlobalSettingsPage` policy view) | Inspect/override campaign policy | Effective policy/provenance editor | Inheritance, actor authority, and blocked edits | #74 and Core #225 effective-policy pattern complete |
| Review/send (`ReviewSendPage`) | Validate, build, mock-test, confirm/send, inspect results | Guided review/decision plus durable progress | External communication, bounded synchronous execution, persisted queue mode, partial effects, retries, evidence | Interventions #63, send/progress #62/#79 and #74 wording/accessibility audit complete |
| Message and attachment detail overlays | Inspect one built/mock message and its attachment links | Stable detail/review dialog | Personal data, exact outbound content, reviewed state | Delivered and verified in [#59](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/59) and [#73](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/73) |
| Campaign report (`CampaignReportPage`) | Filter and inspect delivery outcomes | Reporting/list-detail | Partial, failed, explicitly excluded/skipped, SMTP/IMAP outcomes and retries | Server-owned filtering and counts delivered in [#65](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/65) with the full-result DataGrid contract from [Core #263](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/263); excluded semantics in [#66](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/66) |
| Audit (`CampaignAuditPage`) | Inspect campaign evidence/history | Provenance timeline/report | Actor/action/effect trace | #74 audit |
| JSON (`CampaignJsonView`) | Inspect expert representation | Advanced diagnostics/reference | Raw data may contain personal/configuration values; not a primary editor | #74 privacy/redaction audit |
| Audit (`CampaignAuditPage`) | Reach campaign evidence/history | Explained provenance handoff | Campaign emits platform evidence; Audit owns reading, retention and bundles | #74 complete as an explicit Audit handoff; object-scoped projection may follow Audit #3 without a sibling-private import |
| JSON (`CampaignJsonView`) | Inspect/download expert representation | Advanced diagnostics/reference | Full authorized configuration may contain personal data but no inline transport secrets | #74 privacy audit complete with explicit sensitivity warning and campaign-read boundary |
| Create wizard (`CreateWizard`) | Seed a campaign through basics, sender, fields, recipients, template, attachments, review, send | Guided setup | Current steps mix creation and later consequential delivery; completion semantics need audit | Guided first campaign [#35](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/35) |
| Review/send wizard routes | Alternate guided review/send shells | Guided review | Tracked routes exist; implementation relationship to `ReviewSendPage` must be established, not guessed | #74 inventory decision |
| Operator queue (`OperatorQueuePage`) | Monitor jobs and intervene | Monitoring/work queue | Campaign/version/job identity, historical active-version discovery, fixed action positions, authority-aware disabled states, exact non-overlapping queue counts, server-paged jobs, bounded refresh, retry/queue/reconcile per version, campaign-wide pause/resume/cancel, and leave/return progress | Durable operator controls delivered in [#78](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/78); #74 wording/accessibility audit remains |
| Review/send wizard routes | Focus the canonical review or send stage | Guided review | Thin wrappers render the same `ReviewSendPage` with a stable initial stage; no parallel workflow state exists | #74 inventory decision complete |
| Operator queue (`OperatorQueuePage`) | Monitor jobs and intervene | Monitoring/work queue | Campaign/version/job identity, historical active-version discovery, fixed action positions, authority-aware disabled states, exact non-overlapping queue counts, server-paged jobs, bounded refresh, retry/queue/reconcile per version, campaign-wide pause/resume/cancel, and leave/return progress | Durable controls #78 and #74 wording/accessibility audit complete |
| Aggregate reports (`AggregateReportsPage`) | Compare cross-campaign delivery outcomes | Privacy-preserving aggregate reporting | Tenant/campaign ACL, deployment/tenant small-cell policy, complementary and overlapping-cell suppression, explicit denominator, and no recipient detail/diagnostics/export/drill-down | Separate aggregate-reader surface delivered in [#80](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/80); not parity with the permission-gated per-campaign detail report |
| Templates route (`TemplatesPage`) | Browse template records | Directory/list-detail | Template availability and later generated outputs | #74 audit; verify missing route guard intent |
The five review stages currently named in code are `Validate and inspect`,
`Build and review`, `Mock send and verify`, `Confirm and send`, and `Delivery
results`. Campaign #63 owns the intervention and status vocabulary; Workflow is
not required to define or implement it.
## Repositories Without A WebUI Route Contribution
## Repositories Without A WebUI Package
The following local repositories contain a backend manifest but no
`webui/src/module.ts` at this snapshot:
The generated manifest snapshot reports no WebUI package for:
`govoplan-approvals`, `govoplan-assets`, `govoplan-booking`,
`govoplan-certificates`, `govoplan-committee`, `govoplan-consultation`,
`govoplan-contracts`, `govoplan-dist-lists`, `govoplan-evaluation`,
`govoplan-facilities`, `govoplan-forms-runtime`, `govoplan-grants`,
`govoplan-helpdesk`, `govoplan-identity`, `govoplan-inspections`,
`govoplan-tickets`, `govoplan-learning`, `govoplan-permits`,
`govoplan-poll`, `govoplan-procurement`, `govoplan-records`,
`govoplan-resources`, `govoplan-rest`, `govoplan-risk-compliance`,
`govoplan-soap`, `govoplan-tenancy`, and `govoplan-transparency`.
`govoplan-assets`, `govoplan-booking`, `govoplan-certificates`,
`govoplan-connectors`, `govoplan-consultation`, `govoplan-contracts`,
`govoplan-decisions`, `govoplan-encryption`, `govoplan-evaluation`,
`govoplan-facilities`, `govoplan-grants`, `govoplan-helpdesk`,
`govoplan-identity`, `govoplan-identity-trust`, `govoplan-inspections`,
`govoplan-learning`, `govoplan-mandates`, `govoplan-parties`,
`govoplan-permits`, `govoplan-poll`, `govoplan-procurement`,
`govoplan-records`, `govoplan-resources`, `govoplan-rest`,
`govoplan-services`, `govoplan-soap`, `govoplan-tickets`,
`govoplan-transparency`, `govoplan-wiki`, and `govoplan-workflow-engine`.
This is only negative route evidence. It does not classify the backend module's
maturity or decide that it needs a WebUI. Connector-only, capability-only, or
backend-only modules may remain intentionally headless.
Tenancy does provide composed administration surfaces despite having no direct
route. This section is only negative package evidence; connector-only,
capability-only, runtime-only, and backend-only modules may intentionally remain
headless. A new WebUI should be created only for a concrete user task, not to
make every module symmetrical.
## Rollout Matrix
| Order | Scope | Current evidence | Target | Owner / issue | Verification gate | Status |
| --- | --- | --- | --- | --- | --- | --- |
| 0 | Product grammar and route inventory | Doctrine, ledger, layout rules, module contract, current route sources | One reconciled pattern language and evidence inventory | Meta [#11](https://git.add-ideas.de/GovOPlaN/govoplan/issues/11) | Docs links/diff checks; issue/wiki sync after integration | Initial slice in this document |
| 0 | Product grammar and route inventory | Doctrine, ledger, layout rules, module contract, current route sources | One reconciled pattern language and evidence inventory | Meta [#11](https://git.add-ideas.de/GovOPlaN/govoplan/issues/11) | Reviewed route/component inventory, module documents, manifest shapes and focused contracts | Complete 2026-08-03 |
| 1 | Campaign baseline integration | Recipient-editor WIP and tracker state have been reconciled with remote `main` | Integrated, testable baseline before migration claims | Campaign #67 and tracker cleanup | Backend and focused WebUI suites; issue evidence | Complete 2026-07-22 |
| 2 | Campaign previews/details | Stable shared dialog with bounded scrolling and fixed responsive preview workspace | Stable header/body/footer, accessible long-content detail | Campaign #59 and #73 | Review-preview and overlay structure tests | Complete 2026-07-22 |
| 3 | Campaign review/interventions | Five domain-owned stages with unresolved intervention language | Clear stages, outcomes, blockers, next actor/action, reviewed evidence | Campaign #63 | State matrix behavior/accessibility tests and agreed vocabulary | P1 needs product wording decision |
| 3 | Campaign review/interventions | Five domain-owned stages use central blocker and guided-review primitives; validation/build warnings name action, actor, and destination; hard blockers, individual review, and group review remain distinct; reviewed/remaining counts survive reload through build-bound review evidence | Clear stages, outcomes, blockers, next actor/action, reviewed evidence | Campaign #63 | `reviewProgress` state tests, shared-component structure contract, TypeScript build, configured-system help topic, and Campaign documentation tests | Complete 2026-08-03 (`d635f3a`; Core primitives and contextual help `b823a22`) |
| 4 | Campaign send/progress | A hard deployment ceiling bounds synchronous delivery; the selected synchronous, worker-queue, or database-queue mode is explicit and persisted; progress and recovery survive navigation; immediate-send response and audit evidence are allowlisted | Pre-send mode/consequence plus durable leave/return progress, retry and reconciliation without recipient/provider leakage | Campaign #62 and #79 | Boundary/concurrency/preflight, async selection, persisted mode, sanitized response/audit, partial/failure/retry and reload/return tests | Complete 2026-07-22 (`7e16603`, `60efd1c`, `62a6879`, `b0282eb`, `f095a3e`) |
| 5 | Campaign report filtering | Core DataGrid distinguishes client/full-result from server-owned queries; Campaign applies filter/sort/count before pagination and synchronizes count shortcuts with the grid query | One shared server-owned status/list/filter/count model | Campaign #65 and Core #263 | DataGrid contract/build tests plus exact shortcut/query/filter/count and large-result behavior | Complete 2026-07-22 (`e6062fe`, `cece71d`, `aa4ec66`, `4eb651c`) |
| 6 | Campaign operator recovery | A durable campaign/version queue page exposes historical work, exact non-overlapping state counts, persisted mode, permission-safe controls, server-paged job evidence, bounded refresh and active-state recovery | Fixed-position actions, disabled explanations, leave/return state, version-scoped retry/queue/reconcile and explicit campaign-wide pause/resume/cancel | Campaign #78 | Queue model/structure, historical-version, permission, paging, recovery-control, stale-response and delta tests | Complete 2026-07-22 (`21f3014`, `99d44ee`, `735e874`) |
| 7 | Campaign aggregate reports | A separate aggregate-reader projection and UI expose only policy-suppressed business totals with a stable status domain | Explicit denominator and exclusions, deployment floor plus tenant-strengthened small-cell threshold, complementary and overlapping-cell suppression, no detail/export/diagnostics | Campaign #80 | Aggregate query, cross-metric suppression, route/role/ACL, stable filter and UI structure tests | Complete 2026-07-22 (`06125cc`, `fc36aee`, `8ee87b7`, `ac3329c`, `1225802`) |
| 8 | Campaign excluded outcomes | Excluded build rows become explicit skipped transport outcomes and remain protected from queue/cancel/retry ambiguity | One durable source-to-job-to-report meaning with guarded historical normalization | Campaign #66 | Builder/persistence, migration, query/count, queue-control and report-explanation tests | Complete 2026-07-22 (`7229fb8`) |
| 9 | Guided first campaign | Existing wizard routes and ordinary workspace overlap | Task-oriented entry that hands off clearly to normal editing/review | Campaign #35 | First-run flow, resume/back, validation, optional modules, no implicit send | P1 after core pilot patterns stabilize |
| 10 | Prove/extract generic primitives | Core already exports many primitives; Campaign composition still unreviewed | Extract only contracts with a second consumer or clear platform ownership | Core #225 plus bounded follow-ups | Core behavior/accessibility tests and module-permutation tests | After Campaign proof |
| 11 | Configured-system pattern help | Docs route and classification exist | Role/config-aware pattern and route/field/blocker help | Docs #15 | Topic grouping, audience filtering, stable links/anchors | P1 after initial pattern IDs stabilize |
| 12 | Admin/configuration family | Phase inventory and connector primitives exist in the ledger | Apply the pattern to files, mail, policy, retention, packages, modules, API keys, settings | Core #225 and module children | Per-surface state/accessibility/consequence evidence | Parallel where independent of Campaign shared decisions |
| 13 | Remaining direct routes | Routes are contributed; most are unreviewed | Per-module bounded audit and migration plan | New module issues derived from this inventory | Applicable definition-of-done gates | P2 after Campaign, not a bulk rewrite |
| 14 | Manifest/runtime alignment | Several executable routes are absent from manifest metadata | Declared alignment or explicit validated exception | Core contract issue to create | Automated manifest/module route check and configured Docs verification | Discovery follow-up |
| 9 | Guided first campaign | Eight-stage creation flow persists current step/draft and hands off to ordinary review/delivery preparation | Task-oriented entry that hands off clearly to normal editing/review | Campaign #35 | First-run flow, resume/back, partial validation, immutable-history and optional-module behavior, no implicit send | Complete 2026-07-30 |
| 10 | Prove/extract generic primitives | Shared consequence, focus, help, blocker, unsaved-change, confirmation, connection-tree and effective-policy contracts now have Core and multiple module consumers | Keep Core behavior-only and leave domain composition in owning modules | Core #225 plus bounded follow-ups | Core behavior/accessibility tests and module-permutation tests | Complete 2026-08-03 (`fa32cca`; Files `d8ae506`; Mail `7844d9c`) |
| 11 | Configured-system pattern help | Role/config-aware workflow, reference, pattern, and system topics are projected by Docs; shared route, field, blocker, and action links resolve to configured Docs or the hosted fallback | Stable configured-system guidance without feature-to-Docs imports | Docs #15 | Docs suite, shared component tests, Campaign review tests, 46 module permutations, full-product bundle budget | Complete 2026-08-03 (Docs `abe2f78`; Core `b823a22`; Campaign `d635f3a`) |
| 12 | Admin/configuration family | Core host/settings/credential/retention contracts, shared primitives, module lifecycle, Files, Mail, Policy, Access, Admin, Tenancy, Views, and Organizations are integrated and verified | Continue the same consequence/provenance grammar only through bounded module-owned migrations | Core #225 and module children | Per-surface state/accessibility/consequence evidence | Core #225 complete `fa32cca`; Access `1409dbf`; Files `d8ae506`; Mail `7844d9c`; Policy `f964ed7`; Admin `d428f33`; Tenancy `e76fe16`; Views `c125f33`; Organizations `97acfcb` |
| 13 | Remaining module surfaces | 33 bounded module-owned issues cover every WebUI contributor not already tracked by Campaign #74 or completed Docs #15 | Per-module audit and migration, ordered by user task and consequence rather than a bulk rewrite | Issues linked in the direct-route and composed-surface sections | Module-focused tests, manifest shapes, contextual Docs, and applicable definition-of-done gates | Complete: prior 28 recorded commits plus Workflow #15, Search #4, Reporting #8, Projects #2 and Portal #2 verified 2026-08-03 |
| 14 | Manifest/runtime alignment | Authenticated canonical routes align; public signed-token and compatibility routes are explicit exceptions | Stable declarations reconcile with source and any effective runtime module combination | [Meta #25](https://git.add-ideas.de/GovOPlaN/govoplan/issues/25) | Strict duplicate/stale/undeclared declaration CI, per-module digests, and authorized read-only runtime inventory | Complete 2026-08-04 |
Workflow remains outside this rollout matrix because it has its own runtime and
editor workstream, not because it is postponed. Focused views can be specified,
Repo-docs-PACKAGE-REGISTRY-RELEASES.md
+204
@@ -0,0 +1,204 @@
<!-- codex-wiki-sync:c616e13c97cdaee310347ccb -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/PACKAGE_REGISTRY_RELEASES.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Package Registry Releases
GovOPlaN publishes reusable module artifacts through Gitea's native PyPI and
npm registries. These packages improve developer installation, release
resolution, cacheability, and artifact inspection. They do not replace the
signed runtime distribution: the signed manifest and digest-pinned OCI images
remain the production deployment authority.
## Publication boundary
Every repository with a `pyproject.toml` contains
`.gitea/workflows/module-package-release.yml`. The meta repository owns the
canonical template and installs it with:
```bash
python tools/repo/sync-module-package-workflows.py --write
python tools/repo/sync-module-package-workflows.py --check
```
The workflow runs for `v*` tags and may be dispatched manually for an existing
tag. The organization preflight verifies that every package repository protects
the `v*` namespace. Before building, the workflow itself verifies that:
- the tagged commit is contained in `main`;
- the tag, Python project version, and optional WebUI package version agree;
- package names remain in the `govoplan-*` and `@govoplan/*-webui` namespaces.
The workflow binds the repository explicitly from the Gitea Actions context.
Do not rely on GitHub-compatible environment variables being injected by the
runner image; Gitea runners may expose only the context values. Gitea 1.24 job
tokens cannot read repository tag-protection settings, so package jobs must not
receive a broad administrator token merely to repeat the organization preflight.
Run the following before the first publication and after repository or tag-rule
changes:
```bash
python tools/gitea/gitea-configure-package-releases.py
```
Preview and dispatch the exact wheel/WebUI versions selected by the developer
meta-package with:
```bash
python tools/gitea/gitea-dispatch-package-set.py \
--env-file ~/.config/gitea/gitea.env
python tools/gitea/gitea-dispatch-package-set.py \
--env-file ~/.config/gitea/gitea.env \
--apply
```
The dispatcher reads exact versions from `packages/govoplan-meta/pyproject.toml`,
inspects the selected tag to determine whether a WebUI package is expected,
skips complete registry pairs and does not duplicate an active workflow. Use
`--repository govoplan-core` for a bounded dispatch or `--verify-existing` to
rebuild and hash-verify versions already present in both registries.
For coordinated lockstep tags, `push-release-tag.sh` pushes module tags first,
Core next, and the meta tag last. This is a dependency guarantee for a
single-capacity Actions runner: the developer package cannot run before its
exact Core and module versions have entered the queue.
The same release entry point first validates the migration graph, then records
the reviewed current Alembic heads under the target release version and reruns
the strict migration audit before it changes package versions, commits, or
tags. The default preflight intentionally does not require those heads to exist
in the previous release baseline. A failed candidate-baseline check therefore
cannot produce a protected package release.
The source gate validates `pyproject.toml`, the module version declaration
(`MODULE_VERSION` or the top-level `ModuleManifest.version`), public package
`__version__`, and WebUI metadata before creating tags. Release-tag artifact
checks run only after the candidate tags and immutable WebUI lock have been
created locally.
Release-lock regeneration resolves a fresh immutable lock from the reviewed
candidate manifests; it does not seed resolution from the previous release
lock. This prevents removed transitive packages and stale peer metadata from
blocking or contaminating the new release. Candidate resolution also uses an
isolated temporary npm cache, so a locally replaced tag cannot reuse metadata
from a failed, unpushed release attempt.
Modules that retain the same WebUI package identity in both a root publish
manifest and `webui/package.json` use the WebUI manifest as the canonical peer
contract. The coordinated release synchronizes `peerDependencies` and
`peerDependenciesMeta` into the publish manifest before creating the module
tag, then synchronizes each lockfile root from the final package metadata. A
distinct root package remains independent.
It builds one wheel and, where applicable, one npm tarball. The workflow records
the source tag, source commit, filename, size, and SHA-256 in
`package-artifacts.json` before publishing. Gitea rejects a second upload of the
same package version, so correction requires a new version rather than artifact
replacement.
A retry after partial publication is safe. Before upload, the workflow reads the
native package registry file record and compares its SHA-256 with the artifact
rebuilt from the protected tag. An exact existing artifact is skipped; a
same-version artifact with another digest or an unexpected file set fails
closed. This permits a failed npm publication to resume without weakening
package immutability or accepting `--skip-existing` blindly.
The npm tarball is always published through an explicit local `./dist/...`
path. Without that prefix, npm may interpret a relative tarball name as a Git
package shorthand before it ever contacts the configured registry.
Published WebUI packages contain registry-compatible dependencies only. The
workflow converts an internal dependency pinned to a protected `vX.Y.Z` Git tag
into the exact `X.Y.Z` registry version and rejects unresolved `file:` or Git
dependencies. Repository development metadata may therefore keep local or Git
references without leaking them into the published package contract.
Historical `add-ideas` and current `GovOPlaN` organization URLs are accepted
for immutable tagged releases; both normalize to the same exact registry
dependency and no branch or unversioned Git reference is accepted.
## One-time Gitea setup
Protect `v*` tags in every package repository and the meta repository. Allow
only the `Owners` team to create or delete those tags.
```bash
set -a
. ~/.config/gitea/gitea.env
set +a
python tools/gitea/gitea-configure-package-releases.py --apply
```
Create a dedicated personal access token with only `write:package` scope and
store these organization-level Actions secrets on `GovOPlaN`:
- `GOVOPLAN_PACKAGE_USERNAME`: account owning the package token;
- `GOVOPLAN_PACKAGE_TOKEN`: dedicated package-write token.
Do not use an administrator or general release token. Gitea 1.24 does not grant
package publication to the automatic Actions job token. Organization secrets
allow the same least-privilege credential to serve every module workflow.
## Exact release consumption
`tools/release/generate-release-package-set.py` translates the reviewed Git
source refs in `requirements-release.txt` into an exact registry package set.
It resolves each version tag to its commit and verifies the package metadata in
that tag.
`tools/release/resolve-package-artifacts.py` then downloads exactly those wheel
and WebUI versions from Gitea. It reads the identity embedded in every wheel and
npm tarball, rejects missing, duplicate, unexpected, or oversized artifacts,
and writes `package-artifacts.lock.json` with SHA-256 values and npm integrity
values. Credentials are accepted only through environment variables and are
never written to the lock. Python resolution ignores ambient pip configuration
and extra indexes for GovOPlaN roots, preventing an internal package name from
being selected from an undeclared registry.
The runtime distribution workflow uses the verified wheelhouse directly and
installs module WebUI tarballs only after matching them to the lock. It publishes
the package set, package lock, and hash-locked requirements as release assets.
The WebUI installer receives the absolute runtime-build interpreter path so its
directory changes cannot escape the isolated release environment.
Gitea 1.24 dispatches this workflow from a branch, but that branch is only the
workflow implementation. The job fetches and peels the protected `v<version>`
tag explicitly, then binds both the signed distribution source and the Gitea
release assets to that exact commit. A post-tag workflow repair can therefore
retry publication without relabelling the later branch commit as released
source.
The package-lock SHA-256 is part of the signed distribution manifest. Runtime
finalization also requires the lock's package versions and hashes to match the
wheel composition embedded in the images. OCI assembly remains network-free
after package and third-party dependency resolution.
The source refs remain in the module catalog for source provenance and release
planning. Production installation consumes the signed runtime images rather
than invoking `pip`, `npm`, or Git on the target host.
## Developer meta-package
`packages/govoplan-meta` builds the optional `govoplan` package. Its default
dependencies mirror the reviewed runtime roots; `govoplan[full]` adds all
currently packageable workspace modules. Regenerate it after changing release
requirements or package versions:
```bash
python tools/release/generate-developer-meta-package.py
python tools/release/generate-developer-meta-package.py --check
```
`push-release-tag.sh` performs this synchronization before release commits and
tags. The meta-package is for editable/developer setup and composition tests. It
does not enable modules, apply migrations, provision services, or establish
backup and recovery evidence.
If the tag-triggered developer meta-package job fails before publication, rerun
`publish-developer-meta-package.yml` with the existing protected version. The
manual path validates that tag against `main`, checks out its exact commit, and
publishes only when the registry does not already contain the same wheel hash.
Generic Packages are intentionally not used. Add that transport only when a
consumer needs an artifact format unsupported by PyPI, npm, Gitea Releases, or
the OCI registry.
Repo-docs-PLATFORM-CONTROL-PLANE.md
+88 -13
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:03bb1794aa22a789aa26402c -->
<!-- codex-wiki-sync:416929920605003e906d19be -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/PLATFORM_CONTROL_PLANE.md`.
> Origin: `repository`.
@@ -32,6 +32,7 @@ releases, module boundaries, migrations, and security controls.
| Labels and translations | Generated translation catalogs plus source usage |
| Fields and help coverage | Shared form components plus generated TypeScript AST inventory |
| API use by the WebUI | Typed API clients plus generated static reference inventory |
| Stable platform interface IDs | Typed manifest/WebUI declarations plus line-independent source anchors for low-level controls |
| Effective configuration | Owning module data plus Policy provenance |
Runtime introspection is authoritative for an installed system. Static source
@@ -52,12 +53,48 @@ The command writes:
- `audit-reports/platform-inventory/platform-interface-inventory.json`
- `audit-reports/platform-inventory/platform-interface-inventory.md`
Use `--strict` for the combined translation, endpoint, and declaration audit.
Use `--strict-declarations` for duplicate/stale/undeclared interface checks
without making existing translation coverage a release blocker. Use
`--strict-endpoints` in the endpoint-surface CI gate so unrelated translation
catalog work cannot disable route classification enforcement. Both strict modes
require every backend endpoint without a statically visible WebUI path to have
an exact entry in
`tools/inventory/endpoint-surface-declarations.json`. The registry is keyed by
repository, HTTP method, and canonical version-independent path. It accepts:
- `ui_reachable`: a mounted router, generic action, or provider path hides the
reference from static extraction;
- `intentionally_headless`: a capability/API is deliberately consumed without
its own UI;
- `public_integration`: a documented public or interoperability endpoint;
- `worker_internal`: a worker, scheduler, reconciliation, or monitoring path;
- `compatibility`: a retained transition endpoint with a current replacement;
- `missing_ui`: a real UI gap, which must include a Gitea tracking issue;
- `removable`: a reviewed dead endpoint pending removal.
Strict mode also rejects declarations that no longer match source. When an
endpoint is added, changed, or removed, update its declaration in the same
change. Do not classify an endpoint from a string mismatch alone: first check
mounted prefixes, dynamic action paths, public clients, worker use, and
capability consumers.
It combines:
1. loaded module manifests
2. TypeScript AST extraction of fields, label attributes, visible text,
translations, frontend routes, navigation, capabilities, and API references
3. Python AST extraction of FastAPI route decorators and router prefixes
4. normalized runtime declarations from every loaded `ModuleManifest`
The declaration set covers routes, navigation, View surfaces, fields, actions,
help references, translations, admin/settings sections, widgets, search
objects, permissions, provided interfaces, and backend capabilities. Typed
module contributions keep their declared IDs. Shared controls may declare
`interfaceId` and `helpTopicId`; otherwise the extractor assigns a deterministic
source anchor based on repository, file, component context, control type, and
semantic label rather than a line number. The JSON records which identity
source was used.
The JSON includes exact repository, file, and line evidence. A missing-help
entry is a review candidate because dynamic parent components may supply help.
@@ -65,9 +102,40 @@ A backend route without a static frontend reference is also a review candidate:
public APIs, workers, callbacks, health checks, connectors, and dynamic URL
assembly are valid explanations.
`--strict` currently enforces only translation-catalog completeness. Endpoint
and help classifications need narrow reviewed baselines before they can become
release gates.
The module matrix enforces endpoint and interface declarations with
`--strict-endpoints --strict-declarations`.
Combined `--strict` additionally fails when used translation keys are absent
from generated locale catalogs. Help-text findings remain review candidates
rather than a release gate because dynamic parent components can supply help.
## Runtime Comparison
Core exposes a sanitized read-only catalog at
`GET /api/v1/platform/interface-catalog`. Access requires
`admin:module:read` or `system:settings:read`. Tenant module entitlements are
applied before serialization, so the response describes only the effective
installed combination. It contains IDs, paths, authorization metadata,
versions, counts, and canonical digests; it excludes factories, callbacks,
credentials, and mutable runtime state.
Capture and compare a running installation:
```bash
curl --fail --silent \
-H "Authorization: Bearer $GOVOPLAN_ACCESS_TOKEN" \
"$GOVOPLAN_URL/api/v1/platform/interface-catalog" \
> /tmp/govoplan-runtime-interface.json
./.venv/bin/python tools/inventory/platform-interface-inventory.py \
--runtime-snapshot /tmp/govoplan-runtime-interface.json \
--strict-declarations \
--strict-endpoints
```
The comparison accepts any installed subset. Every module present in the
runtime response must have the same contract version, module version, and
declaration digest as the static release inventory. Unknown, duplicate, or
mismatched runtime modules fail strict declaration mode.
## Admin Information Architecture
@@ -121,13 +189,20 @@ Custom code, new routes, arbitrary SQL, and executable workflow nodes remain
release artifacts. Modeling them as ordinary configuration would create an
unreviewed code-execution and migration channel.
## Next Enforcement Slices
## Enforced Contract
1. Require every WebUI module route and admin/settings contribution to have
matching manifest metadata or a reviewed exception.
2. Add stable field IDs and optional help-topic IDs to shared field components.
3. Classify each statically unreferenced backend endpoint by consumer type.
4. Compare a running installation's OpenAPI and module registry against the
release inventory.
5. Publish the sanitized installed-system structure through Ops/Docs for
authorized administrators.
1. Public WebUI routes and View surfaces must reconcile with runtime manifest
metadata; stale runtime routes and source-only public surfaces fail CI.
2. Duplicate stable IDs fail CI. Shared controls support explicit field/action
and help-topic identities; fallback anchors remain visible review evidence.
3. Every statically unreferenced backend endpoint has an exact reviewed
consumer classification, and stale classifications fail CI.
4. Runtime module combinations can be compared exactly with static release
evidence through versioned per-module digests.
5. Runtime introspection is authorized, tenant-filtered, and read-only. It is
safe for Ops/Docs projection but is not a generic configuration or code
mutation channel.
Generated JSON and Markdown remain build/audit artifacts. Do not hand-edit or
use them as a backlog; change the owning manifest, typed WebUI contribution,
translation/help declaration, or exact endpoint classification instead.
Repo-docs-PLATFORM-CORE-IDEAS.md
+179
@@ -0,0 +1,179 @@
<!-- codex-wiki-sync:8eed8cfe8077795c55348ae1 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/PLATFORM_CORE_IDEAS.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# GovOPlaN Platform Core Ideas
## Purpose
GovOPlaN is an institutional governance and operations layer. Its central
promise is:
> Model the institution, orchestrate its work, connect its systems, and
> preserve why and under whose authority it acted.
The platform should let people complete a real task without understanding its
repository or module graph. It should let institutions retain control over
their data, procedures, providers, and deployment while still sharing
interoperable definitions and evidence.
This document is the stable summary of the ideas that every product package,
module, interface, and integration must preserve. Current implementation state
lives in [Strategy Status](STRATEGY_STATUS.md).
## Ten Core Ideas
### 1. Institutional context before application context
Work happens for a tenant, institution, organizational unit, function,
mandate, jurisdiction, service, case, and represented party. The real actor
and represented capacity remain distinct. Application permissions alone do not
prove institutional competence.
### 2. Governance is executable
Policy is not explanatory prose around an operation. Consequential actions
must expose applicable rules, authority, purpose, expected effects, review
requirements, recovery behavior, and evidence. Inheritance may tighten a rule
but must not silently loosen an upstream constraint.
### 3. Time has two independent meanings
Valid time answers when a fact applied. Recorded time answers what the system
knew at a point in history. Historical browsing changes the business-data
projection, never the current authorization context. Corrections and
supersession remain visible rather than rewriting history.
### 4. One context, many owners
Cases, tasks, decisions, records, messages, files, appointments, reports, and
external objects remain owned by their domain modules or source systems. Stable
references create one navigable context without a universal copied master
record or cross-module table access.
### 5. Native and connected operation are peers
For every integration, GovOPlaN states whether it is authoritative, mirrors an
external source, synchronizes governed fields, adds a governance overlay, or
keeps a link only. An external system can be used today and replaced later
without losing provenance or institutional control.
### 6. Human work is a first-class system object
An intake becomes owned, reviewable work. A person can see the current context,
next responsible action, reason, deadline, consequence, and completion
evidence. Workflow Engine coordinates machine and human transitions; focused
views guide people through the relevant platform surfaces.
### 7. Views reduce complexity without changing authority
The interface is a task- and role-sensitive projection of installed
capabilities. Views, dashboards, search, documentation, and workflow-guided
surfaces may hide irrelevant functions, but they never grant access. Users can
escape a focused mode when policy permits and can always understand why
something is unavailable.
### 8. Evidence and recovery are part of the operation
Intent, exact input versions, approvals, external effects, receipts,
outcome-unknown states, reconciliation, corrections, retention, and recovery
belong to one evidence chain. A retry must be idempotent; rollback claims must
distinguish reversible local state from effects already observed elsewhere.
### 9. Inclusion is multi-channel, not portal-only
Public portal, postbox, mail, telephone, paper, in-person assistance, APIs, and
external systems are channels around the same governed work. Assisted entry
records who entered information, for whom, from which source, with which
attestation, and how the affected person receives a usable receipt and
correction path.
### 10. Successful configurations are portable products
Modules are ingredients. A usable product is a signed configuration package
with terminology, forms, policies, workflows, views, reports, provider
profiles, documentation, migration rules, and evidence. Institutions derive
local packages without forking code or weakening inherited constraints.
## Platform Planes
The planes below are ownership lenses, not navigation groups or mandatory
deployment tiers.
| Plane | Responsibility |
| --- | --- |
| Experience | Shell, views, dashboard, search, help, accessibility, and task-focused composition |
| Participation and channels | Portal, postbox, mail, campaigns, calendar, scheduling, consultation, and assisted channels |
| Human work and procedure | Services, forms/runtime, cases, tasks, approvals, workflow execution, and domain procedures |
| Content, records, and evidence | Files, templates, DMS, eAkte/records, audit, reporting, transparency, and publication |
| Institutional governance | Identity, access, tenancy, organizations, functions, mandates, policy, trust, and formal decisions |
| Data and integration | Connectors, datasources, dataflow, search, external references, provider health, and reconciliation |
| Runtime and assurance | Module composition, operations, deployment, recovery, security evidence, and signed packages |
## Canonical Distinctions
The platform must not collapse these pairs:
- identity vs account vs represented capacity;
- role/permission vs function/mandate/competence;
- valid time vs recorded time;
- purpose for use vs general technical access;
- document content vs managed file bytes vs institutional record;
- task vs workflow definition vs workflow instance;
- approval vs formal decision;
- message intent vs transport delivery vs recipient acknowledgement;
- source authority vs connector maturity;
- current state vs historical evidence;
- correction/compensation vs erasure of an observed effect;
- a module boundary vs a user-visible product boundary.
## Product Experience Rule
The normal user interface speaks in services, work, records, messages,
meetings, decisions, and outcomes. Module names, provider IDs, capability names,
package coordinates, and schema details are technical provenance. They are
visible to administrators and in expandable diagnostics, but they are not the
primary information architecture for ordinary work.
## Maturity Rule
A repository, route, model, or unit test does not make a capability complete.
Claims advance only with evidence appropriate to the claim:
1. `scaffold`: boundary and documentation exist;
2. `vertical_slice`: useful behavior has focused tests;
3. `reference_ready`: an end-to-end reference journey passed target,
accessibility, privacy, security, operations, and recovery evidence;
4. `supported`: upgrades, interoperability, support procedures, and release
guarantees are defined;
5. `lts`: compatibility and maintenance windows are contractual.
## Deliberate Non-Goals
GovOPlaN does not aim to:
- replace every specialist system, ERP, DMS, groupware, or data tool;
- make one database authoritative for every connected fact;
- expose every installed capability to every person;
- infer authority from organizational membership alone;
- make historical browsing weaken current security;
- treat AI output as an unaccountable institutional decision;
- create a repository for every noun in the information model;
- claim production maturity from local development evidence.
## Decision Test
A proposed feature fits the platform when it improves at least one real
institutional journey and can answer:
1. Who owns the object and source of truth?
2. In which institutional and temporal context does it apply?
3. For which declared purpose may it be used?
4. Which policy and authority permit the action?
5. What effect, evidence, retention, and recovery behavior result?
6. How can it operate with an external owner without losing autonomy?
7. How will a person discover and complete it without learning the module
graph?
Repo-docs-PRODUCT-EXPERIENCE-AND-MODULE-BOUNDARIES.md
+154
@@ -0,0 +1,154 @@
<!-- codex-wiki-sync:7bfe07a46ece3912e6471c15 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Product Experience and Module Boundaries
## Problem
GovOPlaN's runtime modularity is a strength, but the implementation structure
is exposed too directly in the product. Ordinary users encounter module names,
one top-level route per module, one navigation item per repository, package and
provider identifiers, and errors framed as missing modules. This makes the
system look like a toolbox of adjacent applications instead of one operating
environment for institutional work.
The correction is not a monolithic frontend and not hidden provenance. It is a
separate product information architecture assembled from typed module
contributions.
Implementation is tracked in
[Core #283](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/283).
## Current Exposure Inventory
| Surface | Direct exposure | Appropriate audience | Product-facing alternative |
| --- | --- | --- | --- |
| Side rail | One icon and route for many installed modules | Administrators and power users | Work areas, services, inboxes, records, communication, data and assurance |
| Route paths | Technical owners such as `/dataflow`, `/forms`, or `/postbox` | Deep links and diagnostics | Stable product aliases and journey routes that resolve to owner surfaces |
| Dashboard | Installed module count and module-owned widget library | Operators | Outcome, obligation, work, exception, and service widgets |
| Administration | Package names, database state, capabilities, providers | Module and system administrators | Guided product/package configuration with technical details on demand |
| Errors | "Module/capability not installed" | Diagnostics | Explain the unavailable outcome, responsible administrator, and enabling path |
| Documentation | Topics grouped primarily by module | Administrators | Task, role, service, and object documentation with module provenance secondary |
| Permissions | Module-namespaced scopes | Access administrators | Human-readable responsibility bundles; exact scopes remain inspectable |
| Search | Provider/module as a result facet | Advanced filtering | Object type, institution, time, purpose, case/service, and source authority |
| Workflow | Steps can expose target route/module details | Workflow designers | User-facing action and expected result; technical binding in definition details |
| Connector state | Provider IDs and source types | Integration owners | Named source, authority, freshness, health, last effect, and recovery state |
## Boundary Decision
Three layers remain distinct:
1. **Technical module layer:** package ownership, dependencies, capabilities,
permissions, migrations, routes, and provider identifiers.
2. **Product composition layer:** work areas, object types, journeys, commands,
inboxes, configuration packages, and role-based defaults.
3. **Presentation projection:** active view, tenant policy, current task,
temporal context, language, accessibility preferences, and device layout.
Modules own implementation and contribute typed product metadata. Core
assembles it. Views filters it. Policy constrains it. Access authorizes the
underlying actions. No consumer imports another optional module's UI directly.
## Product Surface Contract
Each WebUI module should be able to announce:
- `product_areas`: stable areas to which a route, command, widget, or object
belongs;
- `object_types`: user-facing nouns, icons, search context, detail route, and
owner provenance;
- `work_item_sources`: open work, exceptions, deadlines, and responsible
capacity;
- `journey_actions`: launch, resume, review, correct, decide, publish, and
reconcile commands;
- `workspace_surfaces`: embeddable but owner-rendered list, detail, editor, and
status surfaces;
- `configuration_contributions`: guided settings with consequence and
prerequisite metadata;
- `help_contexts`: user/admin documentation for the product identity as well as
the technical owner;
- `technical_provenance`: module, interface version, capability, and provider
identifiers shown only in details and evidence.
The contract references surfaces. It does not permit Core or a product package
to import their implementation.
## Navigation Model
The default shell should prioritize:
1. global search and create/resume commands;
2. personal and function-bound work;
3. configured product areas;
4. pinned user destinations;
5. administration and technical module inspection when authorized.
A module route remains a valid deep link. A product area may combine links and
owner-rendered surfaces from several modules. When a required contribution is
absent, the area explains the missing outcome rather than rendering a broken
placeholder.
Views remain the projection mechanism. They may select product areas, routes,
sections, commands, widgets, and fields. A view must not grant a permission or
change data semantics. Policy can force, allow, or prohibit a surface at system,
tenant, group, or user scope.
## Error And Provenance Language
Normal errors answer:
- what the person was trying to achieve;
- why it is unavailable or failed;
- whether data was saved or an external effect may have occurred;
- who can resolve it and where;
- the correlation/evidence reference.
An expandable technical section may then identify the module, capability,
provider, request, and version. This keeps the product intelligible without
hiding operational truth.
## Migration
### Slice 1: inventory and aliases
- classify every route, navigation item, widget, setting, search object, and
help context by product area and object type;
- add product aliases without removing existing deep links;
- flag raw module IDs in ordinary-user labels and errors.
### Slice 2: work-first shell
- provide a generic work/exception/deadline aggregation capability;
- make work areas and configured packages the default navigation;
- move the complete module catalogue to administration and an optional power-
user surface.
### Slice 3: composite journeys
- let product packages define journey launch/resume actions and default views;
- let Workflow Engine activate a view and focus an owner surface without
controlling authorization;
- expose provider provenance and technical bindings on demand.
### Slice 4: enforceability
- make product classification mandatory for user-visible manifest surfaces;
- reject duplicate product identities and missing owner routes in CI;
- add browser tests proving that reference users can complete a journey without
knowing module names.
## Acceptance Criteria
- An ordinary user can describe every primary navigation item as work or an
institutional object, not as a package.
- A product package can remove irrelevant navigation while retaining deep-link
and help integrity.
- Missing optional modules produce an actionable product explanation.
- Administrators can still inspect exact module, capability, provider, schema,
and evidence provenance.
- Module permutation tests prove that no product surface assumes an optional
owner is installed.
Repo-docs-PRODUCTION-TARGET-HANDOFF.md
+189
@@ -0,0 +1,189 @@
<!-- codex-wiki-sync:f300a18700ddb6305b431a33 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/PRODUCTION_TARGET_HANDOFF.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Production Target And Independent Evidence Handoff
This runbook identifies the external inputs needed to finish
[GovOPlaN #27](https://git.add-ideas.de/GovOPlaN/govoplan/issues/27) and
[GovOPlaN #37](https://git.add-ideas.de/GovOPlaN/govoplan/issues/37). The
repository can render, inspect and sign evidence for a target, but it cannot
manufacture an independent failure domain or an independent approval authority.
## GovOPlaN #27: real two-node target
The bounded acceptance target is two independently schedulable worker nodes.
The API and WebUI must each have ready replicas on both nodes, all Deployments
must be available, the active module composition and software versions must be
consistent, every configured queue must have a worker, and the database
connection budget must pass. The validation then deletes one ready API pod and
requires replacement without an observed readiness outage.
Two virtual machines on different physical hosts or availability zones meet the
failure-domain intent. Two containers, VMs or Kubernetes nodes on one physical
host are useful development targets but do not close #27. A two-worker cluster
also does not prove control-plane high availability. For a self-managed
production cluster, use three control-plane nodes plus at least two workers; a
managed control plane plus two workers is the shorter path.
### What the target owner must provide
Provide these through a secure handoff, not an issue, chat message or Git:
1. A kubeconfig path with access to the target, for example
`~/.config/govoplan/targets/<target>.kubeconfig`, mode `0600`.
2. A stable installation ID, public HTTPS hostname, namespace, ingress class and
TLS-secret or certificate-manager arrangement.
3. Two independently schedulable workers and permission to place API and WebUI
replicas on both.
4. External, logically shared PostgreSQL, Redis and S3 endpoints with trusted
CA material and network reachability from every worker. Do not co-locate the
only copies of these services on the two workers used for the failure drill.
5. The six runtime secret values required by the generated manifest:
`MASTER_KEY_B64`, `DATABASE_URL`, `GOVOPLAN_DATABASE_URL_PGTOOLS`,
`REDIS_URL`, `FILE_STORAGE_S3_ACCESS_KEY_ID` and
`FILE_STORAGE_S3_SECRET_ACCESS_KEY`.
6. A short-lived GovOPlaN API key limited to `ops:operations:read`, supplied in
`GOVOPLAN_OPS_API_KEY` only for evidence collection.
7. An approved drill window and permission to delete one API pod.
If no Kubernetes target exists, provide hostnames/IP addresses for the machines,
an SSH user and key path, the internal/external DNS plan, and the permitted
firewall ports. Those inputs are sufficient to provision a k3s target. They are
not sufficient to claim control-plane HA unless three control-plane failure
domains are present.
### Separate deployment and evidence authorities
The deployment identity may create and update the namespace, Secret,
ConfigMap, Deployments, Services, Jobs, PodDisruptionBudgets and Ingress. The
evidence collector only needs:
- cluster scope: `get` and `list` for `nodes`;
- target namespace: `get` and `list` for `pods` and `deployments`;
- target namespace during the approved drill: `delete` for `pods`.
Use separate kubeconfig contexts or service accounts when the same person does
not hold both roles.
### Render, apply and verify
Use the signed, digest-pinned installation bundle selected for the target:
```bash
export KUBECONFIG="$HOME/.config/govoplan/targets/<target>.kubeconfig"
python tools/deployment/govoplan-deploy.py render-kubernetes \
--directory /srv/govoplan/<installation-id> \
--namespace govoplan \
--secret-name govoplan-runtime \
--tls-secret-name govoplan-tls \
--ingress-class-name nginx \
--output /srv/govoplan/<installation-id>/kubernetes.json
kubectl apply -f /srv/govoplan/<installation-id>/kubernetes.json
kubectl -n govoplan wait --for=condition=available deployment --all --timeout=10m
export GOVOPLAN_OPS_API_KEY="$(cat /run/secrets/govoplan-ops-evidence-key)"
python tools/deployment/govoplan-deploy.py verify-kubernetes \
--directory /srv/govoplan/<installation-id> \
--namespace govoplan \
--exercise-api-pod-loss \
--output /srv/govoplan/<installation-id>/evidence/kubernetes-multi-host.json
unset GOVOPLAN_OPS_API_KEY
```
The verifier emits sanitized JSON and exits nonzero if the topology, runtime,
queue, connection-budget or pod-loss checks fail. Preserve the private cluster
logs and manifest alongside the sanitized result in the controlled evidence
store.
## GovOPlaN #37: controlled signed target evidence
Yes, collection, review and signing can run in containers. A container provides
repeatability and process isolation; it does not create independent authority.
The production approver must control a different private key from the target
operator/assessor and must review the evidence before signing the
`production_approval` scope.
Use at least these three key boundaries:
1. **Installer authority:** signs installed-release-origin receipts only.
2. **Target assessment authority:** signs the permitted target, accessibility,
privacy, security, operations and recovery scopes.
3. **Production approval authority:** independently signs only
`production_approval` after reviewing the other evidence.
Do not reuse release-catalog keys for any of these roles. Keep private Ed25519
keys outside Git, Gitea, GovOPlaN application storage and chat. Publish only the
public keyrings. The proof issuer already rejects key reuse across release,
installer and proof trust domains.
### Generate independently held keys
Each authority runs this command in its own `0700` directory. The generator
refuses existing output paths and writes both files as `0600`:
```bash
install -d -m 0700 "$HOME/.config/govoplan/authority-keys"
python tools/assessments/generate-authority-keypair.py \
--purpose proof \
--key-id authority:target-2026 \
--scope target_environment \
--scope accessibility \
--scope privacy \
--scope security \
--scope operations \
--scope recovery \
--private-key "$HOME/.config/govoplan/authority-keys/target-2026.pem" \
--keyring "$HOME/.config/govoplan/authority-keys/target-2026-public.json"
```
The independent production approver generates another key with only
`--scope production_approval`. An installer authority uses `--purpose installer`
and no `--scope`. Merge public key entries into the separately controlled
keyrings only after the responsible authorities verify fingerprints out of
band.
### Container boundary
Use two one-shot jobs or containers:
- **Collector/assessor:** network access, read-only source and trust mounts,
read/write private evidence output, and the narrowly scoped kubeconfig. It
must not receive the production-approval private key.
- **Production approver:** `--network none`, read-only assessment/evidence/trust
mounts, a read-only secret mount containing only the approval key, and a
separate output mount. It must not receive deployment credentials.
Build or select the assessment image by digest and record that digest in the
evidence log. A representative runtime shape is:
```bash
docker run --rm --network none --read-only --tmpfs /tmp \
--user "$(id -u):$(id -g)" \
--mount type=bind,src="$PWD/evidence",dst=/evidence,readonly \
--mount type=bind,src="$PWD/trust",dst=/trust,readonly \
--mount type=bind,src="$HOME/.config/govoplan/authority-keys",dst=/run/keys,readonly \
--mount type=bind,src="$PWD/approved",dst=/output \
<assessment-image>@sha256:<digest> \
<assessment command>
```
The current evidence commands and required scopes are documented in
[`TARGET_MATURITY_EVIDENCE_RUNBOOK.md`](TARGET_MATURITY_EVIDENCE_RUNBOOK.md).
The final proof must cover `target_environment`, `accessibility`, `privacy`,
`security`, `operations`, `recovery` and independent `production_approval`, and
must bind to the verified installed composition and installer receipt.
## Completion boundary
#27 can close after the real target produces a passing pod-loss result. #37 can
close after an independently approved, schema-valid proof is generated for that
same installed composition and the public authority keyrings, proof and private
evidence custody references are recorded. Neither issue should close from a
single-host simulation or a self-approved signature.
Repo-docs-README.md
+81
@@ -0,0 +1,81 @@
<!-- codex-wiki-sync:b3a66bfea806aebd00371934 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/README.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# GovOPlaN Documentation Map
This directory contains cross-repository product, architecture, release, and
operational documentation. The map below defines which document answers which
question. A document not listed as the current status source must not present
volatile repository, issue, release, or maturity counts as current facts.
## Strategy
| Question | Canonical source |
| --- | --- |
| What are the stable ideas and boundaries of the platform? | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) |
| What product outcomes should GovOPlaN pursue? | [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) |
| Which institutional concepts and owners form the target architecture? | [Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) |
| Which end-to-end proofs should guide implementation? | [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md) |
| What is the reconciled state now? | [Strategy Status](STRATEGY_STATUS.md) |
The dated [Strategic Review](STRATEGIC_REVIEW_2026-08-05.md) explains why the
current reset and sequencing were chosen. It is an assessment record, not a
second live status page.
## Product Architecture
| Topic | Canonical source |
| --- | --- |
| Product-facing experience and hiding technical module boundaries | [Product Experience and Module Boundaries](PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md) |
| Federation between autonomous installations | [Federated GovOPlaN Architecture](FEDERATED_GOVOPLAN_ARCHITECTURE.md) |
| Institutional digital twin and continuous assurance | [Institutional Digital Twin](INSTITUTIONAL_DIGITAL_TWIN.md) |
| Assisted and non-digital channels | [Assisted and Non-Digital Channels](ASSISTED_AND_NON_DIGITAL_CHANNELS.md) |
| Cross-module temporal, purpose, retention, and institutional-context adoption | `govoplan-core/docs/INFORMATION_GOVERNANCE_ADOPTION.md` |
| eAkte and digital-record ownership | `govoplan-records/docs/EAKTE_ARCHITECTURE.md` |
| Data source, definition, and transformation graph | [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md) |
| Focused task views | [Views Architecture](VIEWS_ARCHITECTURE.md) |
| Shared interface patterns | [Interface Pattern Language](INTERFACE_PATTERN_LANGUAGE.md) |
## Runtime And Delivery
- [Module Contracts and Installs](MODULE_CONTRACTS_AND_INSTALLS.md)
- [Platform Control Plane](PLATFORM_CONTROL_PLANE.md)
- [Installation and Deployment Architecture](INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md)
- [Scaling and Multi-Host Deployment](SCALING_AND_MULTI_HOST_DEPLOYMENT.md)
- [Recovery and Rollback Guarantees](RECOVERY_AND_ROLLBACK_GUARANTEES.md)
- [Recovery Ledger Adoption](RECOVERY_LEDGER_ADOPTION.md)
- [Package Registry Releases](PACKAGE_REGISTRY_RELEASES.md)
## Evidence And Snapshots
These documents are intentionally dated or pinned. They may remain useful even
after the product changes, but they do not override `STRATEGY_STATUS.md`.
- [Capability and Infrastructure Fit Assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md), pinned to the 2026-07-22 Campaign composition
- [Strategic Review 2026-08-05](STRATEGIC_REVIEW_2026-08-05.md)
- [Backup and Restore Evidence](BACKUP_AND_RESTORE_EVIDENCE.md)
- [Production Target Handoff](PRODUCTION_TARGET_HANDOFF.md)
- [Target Maturity Evidence Runbook](TARGET_MATURITY_EVIDENCE_RUNBOOK.md)
Machine-readable schemas and evidence files belong beside the document that
defines them. Generated inventories belong in `audit-reports/` and should not
be edited manually.
## Maintenance Rules
1. Gitea issues are the only live work-state source.
2. `STRATEGY_STATUS.md` is the only prose reconciliation of current portfolio
state. Refresh it from manifests, inventories, tests, and Gitea; do not copy
its counts into durable architecture pages.
3. Durable documents state decisions, invariants, ownership, and acceptance
gates. They link to status and issues for implementation depth.
4. Dated assessments retain their original composition and conclusion. Add a
snapshot notice rather than silently updating their claims.
5. Module-specific behavior and user/admin documentation remain in the owning
repository. Meta documentation defines cross-module outcomes and contracts.
6. A new strategy document must replace, narrow, or link an existing source;
it must not introduce a parallel roadmap.
Repo-docs-RECOVERY-AND-ROLLBACK-GUARANTEES.md
+14 -6
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:e432d0c3b51f11d9f6c79468 -->
<!-- codex-wiki-sync:e6b9a1e9dbe58c1c70ca7fb5 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md`.
> Origin: `repository`.
@@ -51,6 +51,10 @@ least one check. The ledger verifies its hash chain before evidence is trusted.
This is a platform contract, not an assertion that every existing module
operation has adopted it. Module operations with external or multi-resource
effects must be migrated to the ledger before claiming these guarantees.
The owning-module inventory and adoption state are maintained in
[Recovery Ledger Adoption](RECOVERY_LEDGER_ADOPTION.md); CI validates the
machine-readable inventory so newly identified boundaries cannot disappear from
the backlog silently.
## Deployment Journal
@@ -105,11 +109,15 @@ old code may not understand the new schema. Recovery then means one of:
3. restore a separately verified, coordinated database/object/key backup and
then deploy the matching release.
The deployment tool does not create or validate that database backup. A
`backup-required` annotation on the Kubernetes migration Job is an operator
gate, not backup evidence. Production automation must provide a backup hook or
external backup controller whose artifact, timestamp, scope, encryption key,
and restore test can be referenced from the recovery record.
The deployment tool does not create that backup. It does verify an externally
produced, signed evidence contract covering PostgreSQL, objects, protected
configuration, and key custody at one recovery point plus an isolated restore
drill. A self-hosted release change cannot reach the migration command or be
exported as a Kubernetes migration Job until fresh evidence bound to the
previous immutable release has been adopted. Compose verifies it again after
runtime quiescing. See
[Backup And Restore Evidence](BACKUP_AND_RESTORE_EVIDENCE.md) for the contract,
provider runbooks, RPO/RTO ownership, retention, and disposal rules.
## Scaled Nodes
Repo-docs-RECOVERY-LEDGER-ADOPTION.md
+96
@@ -0,0 +1,96 @@
<!-- codex-wiki-sync:3abb0169fb7fc0969c1e991a -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/RECOVERY_LEDGER_ADOPTION.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Recovery Ledger Adoption
The Core recovery ledger is a platform primitive, not automatic protection for
module-owned effects. The canonical, machine-checked inventory is
[`recovery-operation-inventory.json`](recovery-operation-inventory.json).
## Classification Rules
- Use `atomic` only when every mutation commits in one database transaction and
no external effect occurs.
- Use `compensation` when every completed effect has a bounded, verifiable
inverse action. A best-effort delete is not proof of compensation.
- Use `snapshot_restore` only with fresh, signed backup evidence that covers all
affected state services at one recovery point.
- Use `forward_recovery` for provider acceptance, queue publication, cursor
advancement, and other effects that may be resumable but cannot safely be
undone.
- Use `irreversible` for approved purge or destruction where no automated
recovery is claimed.
One feature may cross more than one boundary. Module installation is
compensatable before schema migration, forward-only after migration starts, and
snapshot-restorable for an approved destructive retirement. Mail submission is
forward recovery because losing the response after provider acceptance must not
cause an automatic resend.
## Adoption Order
1. Campaign build is the reference implementation for a database plus object
storage operation. Its operation reserves a build-specific object prefix,
persists request and precondition evidence before writes, records the final
object manifest, and verifies database/object state before success.
2. Campaign delivery and Mail provider effects adopt outcome-unknown semantics
without weakening their existing provider-specific idempotency records.
3. Files applies the same contract to uploads, purge, integrity reconciliation,
and writable connector synchronization.
4. Connectors, Dataflow, and Workflow Engine consume the contract at their
registry/capability boundaries so optional providers remain optional.
5. Core module lifecycle uses the ledger in addition to, not instead of, signed
deployment and backup evidence.
Every fenced operation uses a process incarnation and distributed lease. A
stale process cannot append a checkpoint or report success. An expired operation
is claimed for recovery through an explicit takeover that preserves the prior
fence in the checkpoint chain; it is never resumed as a normal retry.
Connectors read-only sanctions and feed acquisitions are adopted: source
revision/cursor and dry-run evidence are recorded before provider I/O, while
the immutable snapshot and terminal checkpoint commit atomically. The generic
external-mutation contract is conformance-tested but remains `planned` until a
production connector actually publishes, updates, or deletes provider state.
Dataflow runs are adopted. Database-only execution uses one atomic terminal
commit for the run projection and recovery checkpoint. Output publication uses
forward recovery: source and output digests are checkpointed before dispatch,
a conclusive provider result commits with the run projection, and an expired
or failed attempt after dispatch becomes `outcome_unknown`. A stale attempt may
be retried only when its durable boundary proves dispatch had not started.
Workflow Engine is adopted at both declared boundaries. Instance workers,
trigger deliveries, and timer resumptions use process-bound distributed fences.
Every module-action invocation records the pinned definition, input, preview,
authority, provider-idempotency, and action-contract hashes before dispatch.
Conclusive results commit with the Workflow projection. A lost acknowledgement,
invalid result, or unannounced non-atomic effect becomes `outcome_unknown` and
cannot be retried until evidence confirms either that the effect occurred or is
absent. Linked Dataflow uncertainty blocks the Workflow without duplicating
Dataflow's recovery authority.
Core module lifecycle is adopted at four boundaries. Installer recovery is
prepared before snapshots so a full database restore preserves the attempted
operation. Pre-migration package changes use compensation, migrated changes use
forward recovery, destructive retirement requires a hashed and restore-checked
snapshot, and live graph changes restore the prior registry when no migration
ran. A deployment-wide database fence serializes these effects; any unresolved
predecessor blocks a differently keyed retry until explicit reconciliation.
Supervised installs become successful only after restart and health evidence is
recorded.
## Operator Contract
Ops lists non-terminal and manual-intervention operations. Operators must verify
the checkpoint chain before trusting evidence, distinguish `outcome_unknown`
from rejection, and use the owning module's documented reconciliation action.
No evidence payload may contain credentials or resolved secrets.
The parent adoption issue remains open until all inventory rows are adopted and
the module matrix proves crash, retry, stale-fence, tamper, and optional-module
behavior for each consequential path.
Repo-docs-REFERENCE-JOURNEY-PROGRAM.md
+34 -1
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:20f93899bb2d38e94f5cb9dd -->
<!-- codex-wiki-sync:54161a07d8965a13877bbf1d -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/REFERENCE_JOURNEY_PROGRAM.md`.
> Origin: `repository`.
@@ -25,6 +25,27 @@ delivered as small, reviewable, green increments and is complete only when its
user journey, failure behavior, documentation, and operator evidence work in a
pinned composition.
## 2026 outcome reset
Repository completion is not product completion. From 2026-08-05 onward, work
is accepted primarily through three maintained real-life journeys:
1. **Governed communication:** select accountable recipients, prepare content
and attachments, approve, deliver through Mail and/or a function-bound
Postbox, reconcile uncertain outcomes, and file the evidence.
2. **Inclusive service-to-decision:** accept a request through a digital or
assisted channel, establish identity and purpose, guide the case through
human and automatic work, decide, notify, and file the resulting eAkte.
3. **Monthly data and sanctions:** acquire immutable source snapshots, validate
and reconcile them interactively, preserve decisions and lineage, produce
reports and files, and deliver the accepted result through Campaign.
The staged program below remains the architectural build order. These journeys
are the acceptance lens across those stages. Every significant feature should
identify the journey it improves, or provide security, operability, recovery,
accessibility, or usability evidence that those journeys require. Work that
does neither stays in the backlog until a concrete consumer exists.
## Why this sequence
The sequence grows one connected product rather than advancing repositories in
@@ -93,6 +114,12 @@ journey needs and supplies contracts shared by all five stages.
execution. Database, broker, cache, and worker channels are constrained by
deployment network policy and authenticated transport rather than treated as
tenant connector profiles.
10. **Information governance.** Temporal browsing, purpose-aware access,
retention/legal-hold behavior, and institutional acting context are applied
to every owned object type. Historical reads use current authorization.
Module manifests state `contract_only`, `partial`, `enforced`, or
`not_applicable` adoption with evidence; supported maturity is blocked until
every applicable dimension is enforced.
## Documentation contract for every reference stage
@@ -115,6 +142,9 @@ Every demonstrated journey provides:
provenance, evidence, retention, and destructive actions.
- **Acceptance view:** runnable examples, expected results, failure injection,
and release gates.
- **Channel and records view:** assisted/non-digital intake and output,
representation, provenance, filing, retention, legal hold, and archive
consequences where the journey creates evidence or a record.
The Docs module selects and links these views according to installed
capabilities and actor context. Feature repositories remain the source of
@@ -443,6 +473,9 @@ or the external editor the document-lifecycle owner.
link, callback, webhook, file, identity, or data row.
- Do not claim a stage complete from local unit tests. Use pinned composition,
target integration, failure drills, adaptive docs, and operator evidence.
- Do not claim a module complete while its relevant information-governance
dimensions remain `contract_only` or while the reference journey lacks an
assisted-channel and records outcome where those are applicable.
- A later stage may prototype contracts while the preceding gate is being
proven, but it may not redefine an owning module's boundary by convenience.
Repo-docs-REPOSITORY-INDEX.md
+2 -1
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:3a6877289005519a3e438aaf -->
<!-- codex-wiki-sync:cdb82de8932b1f366260c346 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/REPOSITORY_INDEX.md`.
> Origin: `repository`.
@@ -84,6 +84,7 @@ Generated from `repositories.json`. Use that JSON file as the machine-readable s
| `govoplan-tickets` | `domain` | `../govoplan-tickets` | [govoplan-tickets](https://git.add-ideas.de/GovOPlaN/govoplan-tickets) |
| `govoplan-transparency` | `domain` | `../govoplan-transparency` | [govoplan-transparency](https://git.add-ideas.de/GovOPlaN/govoplan-transparency) |
| `govoplan-views` | `platform` | `../govoplan-views` | [govoplan-views](https://git.add-ideas.de/GovOPlaN/govoplan-views) |
| `govoplan-voting` | `domain` | `../govoplan-voting` | [govoplan-voting](https://git.add-ideas.de/GovOPlaN/govoplan-voting) |
| `govoplan-wiki` | `domain` | `../govoplan-wiki` | [govoplan-wiki](https://git.add-ideas.de/GovOPlaN/govoplan-wiki) |
| `govoplan-workflow` | `platform` | `../govoplan-workflow` | [govoplan-workflow](https://git.add-ideas.de/GovOPlaN/govoplan-workflow) |
| `govoplan-workflow-engine` | `platform` | `../govoplan-workflow-engine` | [govoplan-workflow-engine](https://git.add-ideas.de/GovOPlaN/govoplan-workflow-engine) |
Repo-docs-REPOSITORY-STRUCTURE.md
+8 -1
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:62d5248f22f8f90b5ee5067f -->
<!-- codex-wiki-sync:838909a8e14561fcb99e8e9f -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/REPOSITORY_STRUCTURE.md`.
> Origin: `repository`.
@@ -83,6 +83,13 @@ one place. If a deployment profile later needs pinned SHAs for every repository,
generate that lock as a release artifact instead of making day-to-day
development depend on submodule updates.
Module release tags also publish wheels and WebUI tarballs to the organization
PyPI/npm registries. The meta release resolves exact versions into a hash-bound
package lock before producing the signed OCI runtime. See
`docs/PACKAGE_REGISTRY_RELEASES.md`. Git tags remain source provenance; package
registries are reusable artifact transport; the signed runtime manifest and
digest-pinned images remain production authority.
## Docker Placement
Whole-product Docker and production-like deployment composition belongs in
Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT.md
+81 -5
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:c2e1a6a893c11e2057885bf5 -->
<!-- codex-wiki-sync:26d7e61532af09dda11e554f -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md`.
> Origin: `repository`.
@@ -7,6 +7,10 @@
---
# Scaling And Multi-Host Deployment
For the exact external handoff, least-privilege collector permissions and live
two-node acceptance procedure, see
[`PRODUCTION_TARGET_HANDOFF.md`](PRODUCTION_TARGET_HANDOFF.md).
## Implemented Contract
GovOPlaN now supports a stateless application tier backed by logically shared
@@ -157,8 +161,29 @@ versioning, and lifecycle controls.
## Capacity
- Scale API replicas only within the PostgreSQL connection budget.
- Set `GOVOPLAN_DB_CONNECTION_LIMIT` to the PostgreSQL role's effective
connection limit. The Kubernetes export reserves
`GOVOPLAN_DB_CONNECTION_RESERVE` connections and rejects a topology whose
calculated rolling-update peak would exceed the remainder. The calculation
includes API pools, every Celery parent and prefork child, the scheduler,
migration, and one surge replica per deployment. Role-specific pool and
overflow values are emitted into each workload rather than inherited from one
unconstrained global default.
- Scale workers by queue, with upper bounds based on external provider limits.
`GOVOPLAN_WORKER_POOLS` may contain a JSON list of exact queue owners, for
example:
```json
[
{"name":"delivery","queues":["send_email","append_sent"],"replicas":2,"concurrency":2},
{"name":"platform","queues":["events","workflow","default"],"replicas":2,"concurrency":2}
]
```
Pool replica totals must equal `replicas.worker`, and the pools must cover
`CELERY_QUEUES` exactly without duplicate ownership. Each pool receives its
own Deployment, disruption budget, topology-spread selector, runtime identity,
and declared concurrency.
- Keep one fenced scheduler rather than load-balancing schedulers.
- Increase WebUI replicas for asset/proxy capacity.
- Measure request latency, database query time and locks, active connections,
@@ -176,15 +201,66 @@ access, node visibility, drain controls, migration serialization, and scheduler
fencing. It does not by itself provide:
- a highly available PostgreSQL, Redis, or object-store deployment;
- automatic PostgreSQL backup, point-in-time recovery, or restore verification;
- automatic PostgreSQL/object backup creation or point-in-time recovery;
- autoscaling policy;
- central logs, metrics, traces, or alert routing;
- managed ingress certificates;
- certificate portability between independently managed ingress providers;
- automatic reconciliation of every possible module side effect;
- a service-level availability guarantee.
Those are deployment and module-adoption requirements. Before claiming high
The deployer verifies and gates migrations on signed coordinated backup and
isolated-restore evidence, but backup capture and restoration remain owned by
the selected state-service providers. Before claiming high
availability, drill replica loss, rolling replacement, session continuity, job
redelivery, scheduler failover, migration exclusion, object-store outage, and a
coordinated database/object/key restore. Recovery rules and evidence are
defined in [Recovery And Rollback Guarantees](RECOVERY_AND_ROLLBACK_GUARANTEES.md).
## Worker Delivery Evidence
The module-matrix workflow runs `tools/checks/worker-runtime-drill.py` against a
real isolated Redis database. The drill starts supervised Celery worker
processes and records four guarantees without accessing tenant data:
1. a task published through the broker is consumed exactly once;
2. an application retry is delivered again and completes;
3. warm `SIGTERM` lets an in-flight late-ack task complete before shutdown; and
4. loss of a worker after task start causes the unacknowledged task to be
redelivered after the configured visibility timeout.
Run the same drill with the release Python environment and target Redis before
promoting a worker composition. Use a dedicated Redis database, retain the JSON
evidence, and set `CELERY_VISIBILITY_TIMEOUT_SECONDS` above the longest supported
business-task duration. The short visibility timeout used by CI is an isolated
test setting, not a production recommendation.
```bash
GOVOPLAN_WORKER_DRILL_REDIS_URL=redis://redis.example.test:6379/15 \
.venv/bin/python tools/checks/worker-runtime-drill.py \
--output evidence/worker-runtime.json
```
## Live Multi-Host Evidence
After deploying a pinned release on at least two Kubernetes nodes, create an API
key with Ops read scope and run:
```bash
export GOVOPLAN_OPS_API_KEY='...'
python tools/deployment/govoplan-deploy.py verify-kubernetes \
--directory /srv/govoplan/installation \
--namespace govoplan
```
The command fails unless API and WebUI pods are ready on at least two nodes,
all rendered deployments are available, Ops reports a consistent release and
module composition, every declared worker queue is served, and the calculated
database peak remains below its budget. It writes a private, sanitized JSON
record under the installation evidence directory and never retains the API key.
Use `--exercise-api-pod-loss` in an approved drill window to delete one API pod,
observe the public readiness path continuously, and record its replacement.
This proves the bounded stateless-node-loss slice only. Session continuity,
accepted-job redelivery, state-service failover, and coordinated restore remain
separate target exercises whose signed evidence is governed by
`docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md` and GovOPlaN #37.
Repo-docs-SECURITY-AUDIT.md
+15 -5
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:a4820145b884caa507fc00cf -->
<!-- codex-wiki-sync:77e9576b6c4c161d71f2d5a1 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/SECURITY_AUDIT.md`.
> Origin: `repository`.
@@ -170,10 +170,20 @@ important scanner counts in the tracker issue.
The jscpd step is intentionally scoped to application and test source. It
excludes documentation snippets, package manifests, generated translations,
public SVG assets, workflow YAML, and declarative backend schema JSON because
those reports produce metadata or asset repetition rather than actionable source
duplication. Keep exclusions narrow and create child issues for source-code
clusters that cross module ownership or make behavior harder to change safely.
public SVG assets and catalog output, workflow YAML, declarative backend schema
JSON, the generated migration baseline, and mirrored development migration
directories because those reports produce metadata or generated-source
repetition rather than actionable source duplication. Keep exclusions narrow
and create child issues for source-code clusters that cross module ownership or
make behavior harder to change safely.
The 2026-08-02 full-workspace baseline covered 64 repositories and reported
1.82% duplicated lines before those generated-source exclusions. The reviewed
high-value clusters were catalog acceptance persistence, release publication
result assembly, and local WebUI JSON mutation wrappers. Similar Dataflow and
Workflow graph/governance code remains independently owned until its shared
contract is stable enough for Core; a raw similarity score is not grounds for a
module-to-module dependency.
## Image Freshness
Repo-docs-STRATEGIC-REVIEW-2026-08-05.md
+132
@@ -0,0 +1,132 @@
<!-- codex-wiki-sync:afdbe5ff13f3b4a267797904 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/STRATEGIC_REVIEW_2026-08-05.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Strategic Review - 2026-08-05
## Assessment
GovOPlaN has not lost its central direction. The architecture now expresses a
coherent institutional governance platform, but architecture and repository
breadth have advanced faster than complete, usable outcomes. The immediate
need is convergence: fewer simultaneous fronts, stronger cross-cutting
adoption, and end-to-end reference journeys that non-developers can complete.
This is a dated review. Current status belongs in
[Strategy Status](STRATEGY_STATUS.md); stable direction belongs in
[Platform Core Ideas](PLATFORM_CORE_IDEAS.md).
## What Is Already Strong
- A modular runtime with manifests, capabilities, interfaces, migrations,
optional integrations, signed releases, and permutation checks.
- Explicit institutional semantics for identity, representation,
organization, function, mandate, service, case, party, approval, decision,
evidence, and record references.
- Governed communication foundations spanning Campaign, Mail, Files, Postbox,
Addresses, Distribution Lists, Templates, Audit, and Policy.
- Governed data foundations spanning Connectors, Datasources, Dataflow,
Reporting, Search, and immutable provenance.
- Bitemporal browsing, views, contextual documentation, action/effect
contracts, event delivery, recovery ledgers, and stateless deployment
contracts.
- A credible deployment and release foundation with signed artifacts and
reproducible composition evidence.
## Where The Program Veered
### Repository breadth preceded product proof
Logical modularity often became a repository before a reference journey proved
that an independent release boundary was required. Scaffolds are useful as
ownership markers, but their number makes the product appear broader and more
complete than its supported outcomes.
### Foundations outran reference gates
Later-stage contracts such as federation, encryption, formal governance,
deployment evidence, and broad module metadata were developed while basic
human-work and records journeys remained incomplete. Those foundations are not
wasted; they now need to be consumed by a small number of demonstrable
products.
### The module graph leaked into the experience
Navigation, routes, administration, errors, documentation, and configuration
often present module names and package structure directly. This is appropriate
for operators, but ordinary users should see work, services, records, and
outcomes.
### Status became duplicated
Roadmaps, target architecture, fit assessments, issue comments, and release
documents each contained partial implementation snapshots. Their stable
decisions remain valuable, but volatile counts and maturity claims diverged.
### Too much work remained active simultaneously
The issue portfolio had many high-priority and in-progress items without
milestones. This reduces the signal of both labels and roadmap order and makes
completion harder to demonstrate.
## Where GovOPlaN Has Not Gone Far Enough
1. No composition has yet crossed the full `reference_ready` gate.
2. The human-work spine is incomplete: work queues, tasks, handoffs, deadlines,
reminders, escalation, and resumption need a coherent user experience.
3. Records and document management remain too shallow for a public-sector
operating platform.
4. Real target integrations and GovOPlaN-to-GovOPlaN federation are not yet
proven.
5. Temporal browsing, purpose-aware access, retention, and institutional
context exist as contracts but are not adopted uniformly by domain reads
and effects.
6. German completeness, contextual help, accessibility, responsive behavior,
and browser-level journey testing are not yet release gates everywhere.
7. Multi-host, backup/restore, provider interoperability, and independent
signed target evidence still require real environments and operators.
## Important Omissions
- a named first institution, bounded users, volumes, and operating constraints;
- measurable usability outcomes, not only functional tests;
- installable sector packages and migration/exit demonstrations;
- support, upgrade, deprecation, and LTS promises;
- complete assisted, paper, telephone, and in-person channel handling;
- a native eAkte/records model that can also overlay an external DMS or archive.
## Opportunities Beyond The Original Idea
- an institutional digital twin that exposes responsibilities, dependencies,
obligations, services, work, data, controls, and change impact over time;
- continuous assurance that evaluates controls and evidence as work happens;
- process mining and conformance analysis over governed event histories;
- federated product packages and inter-institution case/evidence exchange;
- accountable assistance that drafts and explains without obscuring authority;
- public evidence chains that disclose decisions and provenance without
exposing protected source data.
## Recommended Reset
1. Freeze new repositories unless a real journey proves an independent owner,
release lifecycle, security boundary, or optional installation need.
2. Use one generated maturity/status dashboard and one current status document.
3. Complete governed communication and function-bound Postbox against a real
target.
4. Complete the monthly-data journey, then sanctions screening on the same
data foundations.
5. Complete one browser-driven service-to-decision journey, including assisted
intake and records.
6. Make eAkte/records the next major product-depth program.
7. Tie feature work to a reference journey, a security/recovery gate, or a
measured usability defect.
## Success Criterion
The reset succeeds when a public institution can install a signed composition,
configure a named procedure, complete it through digital and assisted channels,
connect an external source, reconstruct the authority and evidence, recover it
after failure, and transfer or retire it without custom code.
Repo-docs-STRATEGY-STATUS.md
+125
@@ -0,0 +1,125 @@
<!-- codex-wiki-sync:b09dec9ca6da7cf182aaa126 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/STRATEGY_STATUS.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# GovOPlaN Strategy Status
## Status Record
| Field | Value |
| --- | --- |
| Reconciled on | 2026-08-05 |
| Source scope | Local workspace manifests, source inventory, focused journey checks, signed release evidence, and live Gitea issue state |
| Stable direction | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) and [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) |
| Delivery source | Gitea issues |
This is the only prose source for current cross-product status. It is a
reconciliation, not a release certification. Module manifests and target
evidence remain authoritative for specific maturity claims.
## Portfolio Snapshot
- 65 source module manifests were loadable and architecture-declared.
- 47 modules declared `vertical_slice`; 18 declared `scaffold`.
- No module declared `reference_ready`, `supported`, or `lts`.
- The live portfolio had 133 open issues, including 39 priority-P1 items.
- 117 open issues had no milestone, so issue labels do not yet express a
reliable completion sequence on their own.
- Three product package manifests existed: governed communication, governed
data and assurance, and service to decision. None had crossed the complete
target-evidence gate.
These counts are dated. Refresh them rather than copying them into another
document.
## Interface And Contract Evidence
The 2026-08-05 source inventory found:
- 1,247 UI fields and 1,220 UI actions;
- 7,929 stable interface declarations with no duplicate IDs;
- 39 frontend routes and 872 backend endpoints;
- no public WebUI surfaces missing runtime declarations;
- no stale runtime route declarations;
- no unclassified endpoint without a static UI reference;
- all 1,247 fields with a resolvable F1 context; 1,087 remain candidates for
richer field-specific content beyond page/module fallback;
- German (`de`) as the complete reference locale and no used key missing from
the required German or English catalogs;
- 260 module information-governance dimensions classified as `contract_only`.
This is an honest platform-wide baseline, not a claim that temporal,
purpose, retention, and institutional-context adoption is complete.
## Credible Current Outcomes
### Platform foundation
Module discovery, optional dependency validation, migrations, shared WebUI,
tenant and access foundations, signed catalogs/packages, event delivery,
recovery contracts, contextual help, views, temporal titlebar context, and
stateless-runtime patterns are implemented and tested at varying depths.
### Governed communication
Campaign authoring, recipient data, attachments, templates, mail profiles,
mock/real delivery paths, audit evidence, reporting, distribution-list
composition, and optional Postbox delivery form the deepest product cluster.
Target provider, accessibility, recovery, and high-volume evidence still
prevent a reference-ready claim.
### Institutional service and decision
Services, Forms, Forms Runtime, Cases, Parties, Mandates, Approvals, Committee,
Voting, Decisions, Portal, Postbox, and Audit have an executable service-to-
decision fixture. Browser-complete assisted intake, production identity,
records, delivery, and target evidence remain.
### Governed data and assurance
Connectors, Datasources, Dataflow, Reporting, Search, Policy, Risk Compliance,
and Workflow provide source governance, immutable snapshots, transformation,
quality, semantic reporting, and provenance foundations. The monthly-data and
sanctions journeys still need real connectors, complete interactive
reconciliation, publication/export, and guided handoff evidence.
## Material Gaps
| Gap | Consequence | Next proof |
| --- | --- | --- |
| No reference-ready product package | The platform cannot yet make a bounded supported-product claim | Complete one named target composition and evidence bundle |
| Human-work spine incomplete | Users still navigate modules and remember unfinished work | Task/work inbox, resumable guided journey, deadlines and handoffs |
| Records/eAkte shallow | Institutional memory and disposition remain fragmented | Native record lifecycle plus external DMS/archive overlay |
| Cross-cutting governance adoption uneven | Historical and purpose-sensitive behavior varies by module | Enforced adoption declarations and route/query/effect migration |
| Explicit help/accessibility depth incomplete | German/reference and F1 association gates now pass, but generic fallback remains too common | High-risk German help content and browser/a11y matrix |
| Real federation absent | Cross-institution exchange remains connector-specific | Paired-instance signed exchange and reconciliation proof |
| External production evidence incomplete | Scale, restore, interoperability and custody claims remain conditional | Real target drills and independent signed evidence |
## Active Strategic Order
1. Establish German, help, temporal, purpose, retention, and institutional
context as enforceable platform quality contracts.
2. Complete governed communication and Postbox against a named target.
3. Complete the monthly-data flow and use it as the data foundation for
sanctions screening.
4. Complete one digital and assisted service-to-decision journey with an eAkte.
5. Add native PostgreSQL search coverage for the objects used by those
journeys; keep OpenSearch optional.
6. Prove one external product connector and one GovOPlaN federation exchange.
7. Finish multi-host, restore, provider, accessibility, and independent signed
target evidence before increasing maturity claims.
## Refresh Procedure
Refresh this page only from evidence:
1. run `tools/checks/check-manifest-shapes.py`;
2. run `tools/inventory/platform-interface-inventory.py --strict
--strict-declarations --strict-endpoints`;
3. run the selected reference-journey checks;
4. inspect signed release and target evidence;
5. query live Gitea issue/milestone state;
6. update the dated values and material gaps here;
7. retain prior assessments as dated evidence rather than rewriting them.
Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.md
+11 -1
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:978cfaf4b9d5c9243c07ec19 -->
<!-- codex-wiki-sync:538772aaddfda8ddf7a63f92 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md`.
> Origin: `repository`.
@@ -148,6 +148,16 @@ The canonical backlog item is
Implementation status as of the current source tree:
- Slice 1 has a published production-artifact baseline. Immutable
[`v0.1.14`](https://git.add-ideas.de/GovOPlaN/govoplan/releases/tag/v0.1.14)
binds source commit `1f039dd39c1ce2672f4978c8abc6dff862ef1445`, a signed
one-file deployer, exact API/Web and managed-dependency image digests,
composition, SBOMs, and provenance. Runtime Distribution
[run #459](https://git.add-ideas.de/GovOPlaN/govoplan/actions/runs/459)
passed migrations, schema checks, non-root API/Web readiness, and worker
delivery/shutdown on both amd64 and arm64. Each future release must renew the
evidence, and a real installation must still produce topology-specific
ingress, failover, backup, and recovery receipts.
- Slice 6 has a working application-tier foundation: state profiles, shared
object storage, runtime node registration/heartbeats/drain, fenced scheduler,
migration serialization, exact-head startup waiting, Ops visibility, and a
Repo-docs-TARGET-MATURITY-EVIDENCE-RUNBOOK.md
+164
@@ -0,0 +1,164 @@
<!-- codex-wiki-sync:3270ea8e441467aafc0cf8af -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md`.
> Origin: `repository`.
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
---
# Target Maturity Evidence Runbook
For authority-key generation, container isolation and the concrete inputs that
must be supplied by the target owner and independent production approver, see
[`PRODUCTION_TARGET_HANDOFF.md`](PRODUCTION_TARGET_HANDOFF.md).
This runbook turns retained target-environment results into a sanitized,
signed GovOPlaN capability-fit proof. It does not make a deployment suitable,
certified, supported, or production-approved by itself. The proof records what
independent authorities assessed against one exact installed release.
## Roles and custody
Use separate trust domains for release signing, installation receipts,
boundary assessment, and production approval. A private proof key must be
provisioned outside the assessed application and its matching public key must
already exist in a separately managed
`capability-fit-proof-authority-keyring.schema.json` document. Do not store
private keys, raw reports, credentials, personal data, backup material, or
target endpoints in Git.
Each authority key lists only the scopes that role may attest. At least one
supplied signing key must cover every claim, and the issuer rejects a key that:
- is absent, inactive, expired, or revoked in the authority keyring;
- expires before the proof;
- does not match its independently provisioned public key;
- reuses release-catalog or installer-authority key material.
## Target run
Install one pinned catalog release and issue its installed-composition receipt
with `tools/assessments/installer-receipt.py`. Exercise the actual target
topology, including:
- PostgreSQL and Redis as shared state services;
- shared S3-compatible object storage;
- at least two stateless API replicas and the intended worker topology;
- fenced singleton work, ingress, certificates, proxy headers, and the real
network/trust boundary;
- provider health and freshness for every provider required by the product;
- monitoring, alerting, failure response, accessibility, privacy, and security
controls;
- backup, isolated restore, failed-deployment rollback, and forward recovery.
For the recovery claim, retain the observed recovery point, measured RPO and
RTO, database/object-store consistency result, and semantic reconstruction of
the institutional and Service/Form reference journeys. Measure RPO from the
last acknowledged durable effect that survives recovery and RTO until service
health plus semantic reconstruction pass. Failed runs are evidence too and
must use a negative result.
The private reports stay in the approved evidence store. Give each report an
opaque artifact ID and each evaluated control a versioned opaque control ID.
## Private claim manifest
Create a private manifest conforming to
`capability-fit-boundary-run.schema.json`. Relative artifact paths resolve from
the manifest directory. Paths are read and hashed by the issuer and are never
copied into the signed output.
```json
{
"$schema": "./capability-fit-boundary-run.schema.json",
"schema_version": "0.1.0",
"evidence_kind": "govoplan.capability-fit-boundary-run",
"proof_id": "target:production:20260802",
"expires_at": "2026-09-01T00:00:00Z",
"claims": [
{
"scope": "target_environment",
"result": "passed",
"control_ids": ["topology:shared-state-v1"],
"artifacts": [
{"artifact_id": "target:run-20260802", "path": "private/target.json"}
]
},
{
"scope": "recovery",
"result": "passed",
"control_ids": ["recovery:restore-rollback-v1"],
"artifacts": [
{"artifact_id": "recovery:run-20260802", "path": "private/recovery.json"}
]
}
]
}
```
Reference readiness needs positive `target_environment`, `accessibility`,
`privacy`, `security`, `operations`, and `recovery` claims. Provider acceptance
and production approval are separate scopes. A production-approval authority
must not approve its own unreviewed target run.
## Issue and verify
Issue only while the signed installer observation is current. Repeat
`--signing-key` when multiple independent roles are needed. The command first
verifies the catalog, independent catalog trust root, exact installed payload,
installer receipt, and installer authority. It then hashes artifacts, signs the
sanitized proof, verifies it immediately, and writes both proof and review with
atomic private-file permissions.
```bash
./.venv/bin/python tools/assessments/boundary-evidence.py \
--assessment /srv/govoplan/assessment.json \
--catalog /srv/govoplan/catalogs/stable.json \
--keyring /srv/govoplan/catalogs/keyring.json \
--trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
--installed-evidence /srv/govoplan/evidence/installed.json \
--installer-receipt /srv/govoplan/evidence/installer-receipt.json \
--installer-authority-keyring /srv/govoplan/trust/installer-authorities.json \
--claims /srv/govoplan/evidence/private/target-run.json \
--authority-keyring /srv/govoplan/trust/proof-authorities.json \
--signing-key authority-target=/run/secrets/target-proof-ed25519.pem \
--output /srv/govoplan/evidence/target-proof.json \
--review-output /srv/govoplan/evidence/target-proof-review.json
```
Add `--expected-external-provider-subject provider-production` when the claim
manifest contains `external_providers`. This value is an opaque deployment ID,
not a URL or credential.
## Promotion gate
The general verifier can now be made admission-enforcing. These switches return
a blocking exit status when a required claim is absent, expired, negative,
revoked, or bound to another assessment, release, installation, or subject:
```bash
./.venv/bin/python tools/assessments/capability-fit.py \
--catalog /srv/govoplan/catalogs/stable.json \
--keyring /srv/govoplan/catalogs/keyring.json \
--trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
--installed-evidence /srv/govoplan/evidence/installed.json \
--installer-receipt /srv/govoplan/evidence/installer-receipt.json \
--installer-authority-keyring /srv/govoplan/trust/installer-authorities.json \
--boundary-evidence /srv/govoplan/evidence/target-proof.json \
--boundary-authority-keyring /srv/govoplan/trust/proof-authorities.json \
--require-reference-readiness \
--require-production-approval \
--output /srv/govoplan/evidence/admission-review.json
```
Use `--require-external-provider-proof` as well when the promoted product
requires an external provider. Live admission must not use
`--verification-time`; that switch is only for clearly labelled historical
review.
## Renewal and failure
Renew evidence after release, installed composition, deployment, control, or
provider changes and before expiry. Revoke an authority key immediately after
custody loss and rerun the affected assessment with a new independent key.
Never copy a previous positive claim to a new release. Preserve negative and
superseded receipts according to the approved evidence-retention policy.