# GovOPlaN Admin

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

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

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

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.

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