feat: add platform interface inventory and encryption registry
This commit is contained in:
@@ -9,6 +9,12 @@ The applicable design contract is
|
||||
|
||||
## Snapshot And Method
|
||||
|
||||
The source-derived inventory command is documented in
|
||||
[`PLATFORM_CONTROL_PLANE.md`](PLATFORM_CONTROL_PLANE.md). It produces
|
||||
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.
|
||||
|
||||
Evidence was read from tracked Git `HEAD` in the local GovOPlaN checkouts:
|
||||
@@ -215,10 +221,11 @@ backend-only modules may remain intentionally headless.
|
||||
| 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 |
|
||||
|
||||
Workflow/user-story implementation is postponed. It is not on the critical path
|
||||
for this rollout matrix. Focused views can be specified, manually selected, and
|
||||
tested through core composition contracts; a later workflow step may become one
|
||||
activation source without changing the proven surface patterns.
|
||||
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,
|
||||
manually selected, and tested through core composition contracts today.
|
||||
Workflow steps may activate those views through the same contract without
|
||||
changing the proven surface patterns.
|
||||
|
||||
## Inventory Maintenance
|
||||
|
||||
|
||||
126
docs/PLATFORM_CONTROL_PLANE.md
Normal file
126
docs/PLATFORM_CONTROL_PLANE.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Platform Control Plane And Self-Description
|
||||
|
||||
## Objective
|
||||
|
||||
GovOPlaN should be able to describe its installed structure without becoming a
|
||||
self-modifying application. The platform model is a declarative control plane:
|
||||
module manifests, UI contributions, schemas, policy provenance, runtime
|
||||
capabilities, and generated source evidence describe what can be configured.
|
||||
Ordinary administrators edit validated data through those contracts; they do
|
||||
not edit Python, TypeScript, routes, or database code from the product UI.
|
||||
|
||||
This distinction provides the requested overview while preserving reviewable
|
||||
releases, module boundaries, migrations, and security controls.
|
||||
|
||||
## Canonical Sources
|
||||
|
||||
| Concern | Canonical source |
|
||||
| --- | --- |
|
||||
| Installed modules and dependency graph | Runtime `ModuleManifest` registry |
|
||||
| Backend routes | Registered FastAPI application; Python AST is build-time evidence |
|
||||
| Frontend routes and navigation | `PlatformWebModule` contributions |
|
||||
| View-filterable regions | Versioned `viewSurfaces` declarations |
|
||||
| Admin sections and module settings | `admin.sections`, including `moduleId`, `kind`, scope group, permission guards, and surface ID |
|
||||
| User settings | `settings.sections` and core settings schemas |
|
||||
| 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 |
|
||||
| Effective configuration | Owning module data plus Policy provenance |
|
||||
|
||||
Runtime introspection is authoritative for an installed system. Static source
|
||||
inventory is authoritative evidence for a checkout or release candidate. The
|
||||
two should be compared in CI and by Ops, not conflated.
|
||||
|
||||
## Generated Inventory
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /mnt/DATA/git/govoplan
|
||||
./.venv/bin/python tools/inventory/platform-interface-inventory.py
|
||||
```
|
||||
|
||||
The command writes:
|
||||
|
||||
- `audit-reports/platform-inventory/platform-interface-inventory.json`
|
||||
- `audit-reports/platform-inventory/platform-interface-inventory.md`
|
||||
|
||||
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
|
||||
|
||||
The JSON includes exact repository, file, and line evidence. A missing-help
|
||||
entry is a review candidate because dynamic parent components may supply help.
|
||||
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.
|
||||
|
||||
## Admin Information Architecture
|
||||
|
||||
The Admin host uses a tree because system, tenant, group, user, and module
|
||||
settings form a hierarchy rather than one flat list. Every contributed section
|
||||
can identify:
|
||||
|
||||
- its owning `moduleId`
|
||||
- whether it is `management` or `settings`
|
||||
- its system/tenant/group/user scope group
|
||||
- an optional future `parentId`
|
||||
- permission and View visibility requirements
|
||||
|
||||
Existing panels remain their own render owners. The tree only changes discovery
|
||||
and grouping. A later embedded-settings contract may add named slots inside an
|
||||
owning page; it must not allow one module to import another module's private
|
||||
component.
|
||||
|
||||
## Navigation And Workflow
|
||||
|
||||
The intended maximum visible navigation stack is:
|
||||
|
||||
1. global shell context
|
||||
2. one task/object navigation surface
|
||||
3. one workflow stage surface when a workflow is active
|
||||
|
||||
Workflow instance pages should reuse the Campaign stage language: clear stage
|
||||
state, optional/skipped/blocked semantics, partial progress, and a stable current
|
||||
step. Workflow definition pages remain graph editors. Views may activate a
|
||||
focused workflow view that suppresses unrelated shell and module surfaces while
|
||||
retaining an explicit way out.
|
||||
|
||||
Nested module submenus should not be added merely because a data hierarchy
|
||||
exists. Prefer a tree inside configuration/directory surfaces, tabs for sibling
|
||||
views, and the workflow stage rail for ordered work.
|
||||
|
||||
## Safe Meta-Configuration
|
||||
|
||||
The platform can eventually render many configuration editors from versioned
|
||||
JSON Schema and UI Schema supplied by modules. Generated editors remain bounded
|
||||
by:
|
||||
|
||||
- explicit typed schemas and migrations
|
||||
- module-owned validation and preview
|
||||
- Policy locks and provenance
|
||||
- permission and View filtering
|
||||
- preflight, consequence, and rollback information
|
||||
- auditable apply operations
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
@@ -34,6 +34,7 @@ Generated from `repositories.json`. Use that JSON file as the machine-readable s
|
||||
| `govoplan-dms` | `domain` | `../govoplan-dms` | [govoplan-dms](https://git.add-ideas.de/GovOPlaN/govoplan-dms) |
|
||||
| `govoplan-dist-lists` | `domain` | `../govoplan-dist-lists` | [govoplan-dist-lists](https://git.add-ideas.de/GovOPlaN/govoplan-dist-lists) |
|
||||
| `govoplan-docs` | `platform` | `../govoplan-docs` | [govoplan-docs](https://git.add-ideas.de/GovOPlaN/govoplan-docs) |
|
||||
| `govoplan-encryption` | `platform` | `../govoplan-encryption` | [govoplan-encryption](https://git.add-ideas.de/GovOPlaN/govoplan-encryption) |
|
||||
| `govoplan-erp` | `domain` | `../govoplan-erp` | [govoplan-erp](https://git.add-ideas.de/GovOPlaN/govoplan-erp) |
|
||||
| `govoplan-evaluation` | `domain` | `../govoplan-evaluation` | [govoplan-evaluation](https://git.add-ideas.de/GovOPlaN/govoplan-evaluation) |
|
||||
| `govoplan-facilities` | `domain` | `../govoplan-facilities` | [govoplan-facilities](https://git.add-ideas.de/GovOPlaN/govoplan-facilities) |
|
||||
|
||||
@@ -191,6 +191,12 @@
|
||||
"description": "GovOPlaN Erp module behavior or integration.",
|
||||
"exclusive": false
|
||||
},
|
||||
{
|
||||
"name": "module/encryption",
|
||||
"color": "b60205",
|
||||
"description": "GovOPlaN Encryption key custody, cryptographic policy, and E2EE integration.",
|
||||
"exclusive": false
|
||||
},
|
||||
{
|
||||
"name": "module/evaluation",
|
||||
"color": "bfdadc",
|
||||
|
||||
Reference in New Issue
Block a user