GovOPlaN Admin

The Admin-owned workspace sections, lifecycle stages, consequence classes, contextual-help contract, and verification evidence are recorded in docs/INTERFACE_PATTERN_MIGRATION.md.

Repository type: module (platform).

govoplan-admin owns generic system administration API and WebUI contributions during the GovOPlaN module split.

This repository owns the live admin_governance_templates and admin_governance_template_assignments tables. Core migrations rename the historical unprefixed governance tables for existing development databases. It contributes the stable /api/v1/admin/system/governance-templates routes and owns governance-template CRUD plus materialization into access-owned tenant groups and roles. The /synchronize operation validates selected templates and tenants in bounded bulk reads, delegates one versioned projection batch to Access, and returns an auditable outcome for every assignment. Dry runs do not mutate Access data; applied retries are idempotent and never silently skip blocked assignments.

WebUI Package

The repository root and webui/ directory both expose the package @govoplan/admin-webui. The package does not contribute the /admin route itself; govoplan-access owns the route shell. Instead, admin contributes section entries through core's admin.sections UI capability:

• overview
• system settings
• governance template tenant roles
• governance template groups

The route shell in access collects those sections at runtime, applies their scope requirements, and renders them without importing admin package internals.

Module Lifecycle Administration

The admin module owns the operator surfaces for module lifecycle management:

• installed/enabled/desired module state
• runtime activation and deactivation of installed modules
• signed catalog install planning
• automatic discovery from the signed public stable directory when no deployment catalog override is configured
• non-destructive uninstall planning, with explicit destroy_data retirement options where a module provides a retirement provider
• installer preflight status, maintenance-mode blockers, migration/restart checklist entries, and rendered operator commands
• installer daemon request queue, cancellation/retry, recent run summaries, rollback status, run IDs, request IDs, and trace IDs

Package mutation is intentionally not executed inside the FastAPI request. The admin UI records operator intent and queues or renders commands for the trusted installer process described in /mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md.

Catalog entries can be searched by module, package, repository, or tag and filtered by availability, installed state, update state, and blockers. Each row shows its signed source revision and immutable artifact digest together with configuration requirements and release notes when the publisher supplies them. Withdrawn entries and targets with missing dependencies, incompatible named interfaces, or an unsupported current-version window cannot be added to a plan. Selecting an eligible entry preserves its signed registry URLs and integrity evidence in the reviewed plan. The installer, not the browser or API request, downloads and verifies those artifacts. On a shared or Kubernetes deployment, the same plan requires a new immutable image composition instead of changing one running replica.

The WebUI presents the lifecycle as five derived stages: plan, preflight, installer request, daemon execution, and run evidence. The projection resets when the saved plan changes and associates evidence only with an installer request created at or after the current plan revision. It therefore cannot make an old successful run look like evidence for a new plan. The earliest queue blocker is shown through Core's actionable blocker pattern with the required action, responsible operator or administrator, and destination. Contextual help uses the stable admin.module-lifecycle-workflow documentation topic.

Tenant Module Entitlements

Deployment lifecycle and tenant availability are separate administration workflows. System > Tenant modules lets a system administrator select a tenant, mark installed modules unavailable, available, or forced, and set the tenant's current selection. Tenant > Modules lets an account with the admin:module:write permission change only the available selection. The module_admin role template grants the narrow read/write pair for that task.

Core closes required dependencies, retains protected administration modules, uses an optimistic entitlement revision, and records audit and governed configuration evidence. A selected module that is not globally active remains configured but unavailable at runtime. Module selection never grants module permissions.

User and group module visibility is configured through Views, where each WebUI module is represented by its root module surface. This keeps tenant operational state distinct from presentation preferences.

Licensing remains a generic catalog/preset contract. Official open-source GovOPlaN directory entries carry no feature requirement; a license affects an entry only when that catalog explicitly declares license_features.

Package Surfaces

The admin UI intentionally exposes two different package concepts:

• Configuration packages are import/export bundles for module-owned configuration data. They support dry-run diagnostics, approval, apply, and export workflows without installing Python or WebUI packages.
• Module package catalog and operator install plan live under Modules. They describe approved release artifacts, install/update/remove plans, preflight blockers, maintenance-mode requirements, installer-daemon requests, and rollback visibility.

These surfaces should stay separate in navigation and copy. If future UI work combines them visually, it must still preserve the operator distinction between configuration mutation and package installation.