116 lines
5.7 KiB
Markdown
116 lines
5.7 KiB
Markdown
# 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](docs/INTERFACE_PATTERN_MIGRATION.md).
|
|
|
|
<!-- 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
|
|
- 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.
|