diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index 6eab1ff..cc516be 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -402,6 +402,15 @@ The package install-plan API records operator intent only: summaries and the current installer lock status. - `GET /api/v1/admin/system/modules/install-runs/{run_id}` returns the raw run record for diagnosis. +- `GET /api/v1/admin/system/modules/install-requests` returns daemon handoff + requests queued from the admin UI or CLI. +- `POST /api/v1/admin/system/modules/install-requests` queues a supervised + installer request. It requires maintenance mode and maintenance access. The + FastAPI request writes only the request record; it does not run package + commands. +- `GET /api/v1/admin/system/modules/package-catalog` reads approved package + references from `GOVOPLAN_MODULE_PACKAGE_CATALOG` so operators can add known + module refs to the install plan without typing them manually. - `PUT /api/v1/admin/system/modules/install-plan` saves planned install or uninstall rows. Install rows must use tagged package or git references, not local `file:`/workspace paths. Python install rows must also include the @@ -422,6 +431,13 @@ The package install-plan API records operator intent only: verification, runs the restart command if provided, polls health, and automatically rolls packages back from the run snapshot if commands, migrations, restart, or health recovery fail. +- `govoplan-module-installer --daemon` runs the request executor. It polls the + runtime request queue, claims one request at a time, and executes the same + supervised installer flow. `--daemon-once` processes at most one queued + request and exits, which is useful for tests or process-manager one-shot + units. +- `govoplan-module-installer --enqueue-supervised` creates the same request + record from a shell instead of from the admin UI. - `govoplan-module-installer --rollback ` restores the saved package snapshots, restores the captured SQLite or external database snapshot when present, and reruns package installation from the previous freeze file. @@ -433,6 +449,13 @@ The package install-plan API records operator intent only: - `govoplan-module-installer --list-runs --format json`, `--show-run --format json`, and `--lock-status --format json` expose the same run-history and lock information from the operator shell. +- `--list-requests --format json` and `--show-request --format json` + expose daemon handoff records from the operator shell. + +The supervisor accepts multiple restart commands and health URLs. This is the +process boundary for web, worker, scheduler, and auxiliary service restarts: +each restart command is executed, each health URL is polled, and rollback uses +the same restart/health set after restoring package and database snapshots. The installer preflight is intentionally conservative: @@ -454,7 +477,7 @@ The installer preflight is intentionally conservative: The installer supervisor must run outside the FastAPI server process. A server request handler cannot reliably restart or roll back the process that is currently executing the request. The admin UI therefore remains an operator -planning surface; the trusted daemon/CLI is the executor. +planning and request-submission surface; the trusted daemon/CLI is the executor. Automatic rollback covers Python and WebUI package state. For `sqlite:///` database URLs, `--migrate` also captures a SQLite backup and rollback restores @@ -472,9 +495,9 @@ are satisfied. The running FastAPI server still reports `package_mutation_supported=false` because dependency-manager operations are not executed inside request handlers. -The trusted mutation boundary is the operator CLI. This keeps the interpreter, -npm dependency graph, frontend bundle, migrations, and worker process set under -process-supervisor control. +The trusted mutation boundary is the operator CLI/daemon. This keeps the +interpreter, npm dependency graph, frontend bundle, migrations, and worker +process set under process-supervisor control. Frontend module loading primarily uses the build-time package graph generated by the core WebUI host. Installing or uninstalling a WebUI package therefore still