127 lines
5.3 KiB
Markdown
127 lines
5.3 KiB
Markdown
# 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.
|