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