docs: organize cross-product documentation

docs/operations/DEPLOYMENT_PROFILES.md

@@ -0,0 +1,120 @@
+# GovOPlaN Deployment Profiles
+
+## Purpose
+
+GovOPlaN distinguishes how code is executed, where it is placed, and how mature
+the target is. These are separate concerns:
+
+- **execution basis:** editable source trees or an immutable signed release;
+- **topology:** local processes, one-host containers, or a multi-host
+  orchestrator;
+- **component ownership:** installer-managed or externally supplied state and
+  infrastructure services; and
+- **assurance state:** development, rehearsal/acceptance, or approved
+  production.
+
+PostgreSQL, Redis, object storage, mail and ingress choices are component
+bindings inside a profile. They do not create a new application topology by
+themselves.
+
+## Canonical Profiles
+
+| Profile | Entry point | Application execution | State services | Intended use | Explicit boundary |
+| --- | --- | --- | --- | --- | --- |
+| Local source development | `tools/launch/launch-dev.sh` | Editable Uvicorn/Vite processes with reload | Local development bindings, optionally the shared PostgreSQL helper | Fast module and UI work | No production packaging, isolation, availability or capacity claim |
+| Split source integration | `tools/launch/launch-production-like-dev.sh` | Editable API, WebUI, worker and scheduler processes | Containerized PostgreSQL/Redis by default; environment bindings may point at developer-owned services | Queue, migration, Redis and split-role integration while retaining source reload | “Production-like” describes behavior, not immutable artifacts or a production security boundary |
+| Immutable single-host rehearsal | `govoplan-deploy init/apply --profile evaluation` | Signed API/WebUI images and generated Compose roles | Bounded managed components or explicit external bindings | Test the downloadable artifacts, installer, migrations, load balancer and component choices | All containers and managed services may share one host and failure domain; evaluation conveniences are not production controls |
+| Single-host production | `govoplan-deploy init/apply --profile self-hosted` | Signed API/WebUI images behind generated HAProxy and selected TLS ingress | Durable local/single-node managed services where accepted, or external services | Small and medium installations whose accepted availability boundary is one host | Multiple containers add capacity and rolling-process resilience, but do not survive host loss |
+| Multi-host Kubernetes production | `govoplan-deploy render-kubernetes` or the guarded K3s lab/acceptance workflow | Immutable API, WebUI and queue-specific worker Deployments across failure domains | External PostgreSQL, Redis and S3-compatible storage; external secret and ingress control | Institution-scale availability and horizontal application-tier capacity | Production claims require independent nodes, HA state services, load/capacity evidence and signed recovery evidence |
+
+Docker Compose services are containers or replicas, not Kubernetes pods. The
+immutable single-host rehearsal is the appropriate Dockerized whole-product
+test when source reload is not required.
+
+The K3s VM lab has two modes over the same Kubernetes profile:
+
+- `rehearsal` may place VMs on one physical hypervisor and proves bounded
+  orchestration behavior;
+- `acceptance` requires independently controlled worker failure domains and can
+  contribute target evidence.
+
+## Module composition and availability
+
+Official immutable API and WebUI images carry the verified `full` package
+profile. This is package availability, not runtime activation and not a license
+or tenant entitlement. The signed distribution manifest records the complete
+package composition; the desired module graph selects which installed modules
+are active; tenant module policy applies unavailable/available/forced ceilings;
+and Views/Policy control group and user presentation.
+
+Local and single-host profiles may use the supervised installer to download a
+signed catalog artifact into a private digest cache and mutate the local package
+environment during maintenance. A multi-host/shared-state profile must never
+change one replica in place. Its Admin install plan is a composition request:
+publish and roll out a new signed image whose package lock contains the target,
+then activate the module graph after all replicas report the same composition.
+
+## Component Choices
+
+The installer may manage a component where its bounded profile is appropriate,
+or consume an operator-provided service:
+
+| Component | Managed boundary | External/BYO boundary |
+| --- | --- | --- |
+| PostgreSQL | Single-host Compose database | Stable primary-aware endpoint supplied by a PostgreSQL provider/operator |
+| Redis | Single-host persistent Redis | Tested HA Redis endpoint compatible with queues, throttling and coordination |
+| File/object storage | Durable local storage or single-node Garage | Shared, redundant S3-compatible storage |
+| Mail | Development GreenMail only | Institution/provider SMTP and IMAP services |
+| Ingress/TLS | Generated Caddy on one host | Existing reverse proxy or Kubernetes ingress and secret management |
+
+Switching to an external component changes ownership and evidence requirements;
+it does not remove GovOPlaN's health, capacity, backup and recovery checks.
+
+## Scaling Responsibilities
+
+GovOPlaN scales application roles, while the infrastructure control plane owns
+machines and state-service replication:
+
+| Concern | Scaling model | Owner |
+| --- | --- | --- |
+| API and WebUI | Increase replicas behind health-aware Services/Ingress | GovOPlaN deployment desired state, reconciled by Compose or Kubernetes |
+| Background work | Add queue-specific worker replicas and bounded concurrency | GovOPlaN deployment desired state and worker-pool configuration |
+| Scheduler, migrations and module lifecycle | Singleton execution protected by database leases/fencing | GovOPlaN; these roles are never scaled as unfenced active-active workers |
+| Kubernetes worker/control nodes | Add, drain, replace and upgrade machines; optionally use a cluster autoscaler | Kubernetes/platform operator, not the GovOPlaN application |
+| PostgreSQL | Replication, failover, backups, connection pooling and stable writer endpoint | Database operator/provider; GovOPlaN currently consumes the stable endpoint and does not route arbitrary reads to replicas |
+| Redis | Replication/failover, persistence, eviction and TLS/authentication | Redis operator/provider |
+| S3-compatible storage | Placement, replication, repair and capacity | Storage operator/provider |
+
+Administrators should eventually be able to review and change permitted
+application replica and worker-pool desired state through the Ops surface.
+Creating physical machines, database replicas or storage members remains an
+orchestrator/provider action. GovOPlaN must observe their health and block unsafe
+changes rather than becoming a second infrastructure scheduler.
+
+Every scale change must recalculate the database connection budget, preserve
+queue coverage, verify software/module-composition consistency and respect
+drain and fencing state.
+
+## What Has Been Proven
+
+The current implementation and the signed `v0.1.18` rehearsal prove that the
+application tier can run as stateless API, WebUI and worker replicas against
+logically shared state. Two Kubernetes worker VMs hosted API and WebUI replicas,
+and an API pod was replaced without an observed public-readiness failure.
+
+This is not yet proof of general “large organization fit.” That claim also
+requires:
+
+- representative concurrent-user, dataset, report and background-job load
+  tests with latency and saturation budgets;
+- independent physical failure domains and real ingress/network behavior;
+- HA PostgreSQL, Redis and object storage with failover drills;
+- session, accepted-job and provider-effect continuity under node and service
+  loss;
+- coordinated backup/isolated restore, measured RTO/RPO and semantic recovery;
+- observability, alerting, capacity forecasting and sustained soak evidence.
+
+The profile therefore proves the architecture is horizontally deployable. A
+specific institution is production-fit only after its target topology and load
+envelope have produced the governed evidence described in
+`TARGET_MATURITY_EVIDENCE_RUNBOOK.md`.