govoplan/docs/PLATFORM_CONTROL_PLANE.md

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:

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.