diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 7539daf..3085ad0 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -10,6 +10,7 @@ This page is generated from repository and product-directory project files. - [Repo-docs-CAPABILITY-AND-INFRASTRUCTURE-FIT](Repo-docs-CAPABILITY-AND-INFRASTRUCTURE-FIT) - `/mnt/DATA/git/govoplan/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md` - [Repo-docs-CONNECTED-GOVERNANCE-PLATFORM-ROADMAP](Repo-docs-CONNECTED-GOVERNANCE-PLATFORM-ROADMAP) - `/mnt/DATA/git/govoplan/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md` - [Repo-docs-DATASOURCE-AND-DEFINITION-GRAPH-ARCHITECTURE](Repo-docs-DATASOURCE-AND-DEFINITION-GRAPH-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md` +- [Repo-docs-DEPLOYMENT-PROFILES](Repo-docs-DEPLOYMENT-PROFILES) - `/mnt/DATA/git/govoplan/docs/DEPLOYMENT_PROFILES.md` - [Repo-docs-FEDERATED-GOVOPLAN-ARCHITECTURE](Repo-docs-FEDERATED-GOVOPLAN-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/FEDERATED_GOVOPLAN_ARCHITECTURE.md` - [Repo-docs-FRONTEND-LAYOUT-PRINCIPLES](Repo-docs-FRONTEND-LAYOUT-PRINCIPLES) - `/mnt/DATA/git/govoplan/docs/FRONTEND_LAYOUT_PRINCIPLES.md` - [Repo-docs-GITEA-ISSUES](Repo-docs-GITEA-ISSUES) - `/mnt/DATA/git/govoplan/docs/GITEA_ISSUES.md` @@ -26,6 +27,7 @@ This page is generated from repository and product-directory project files. - [Repo-docs-PLATFORM-CONTROL-PLANE](Repo-docs-PLATFORM-CONTROL-PLANE) - `/mnt/DATA/git/govoplan/docs/PLATFORM_CONTROL_PLANE.md` - [Repo-docs-PLATFORM-CORE-IDEAS](Repo-docs-PLATFORM-CORE-IDEAS) - `/mnt/DATA/git/govoplan/docs/PLATFORM_CORE_IDEAS.md` - [Repo-docs-PRODUCT-EXPERIENCE-AND-MODULE-BOUNDARIES](Repo-docs-PRODUCT-EXPERIENCE-AND-MODULE-BOUNDARIES) - `/mnt/DATA/git/govoplan/docs/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md` +- [Repo-docs-PRODUCT-INPUT-REGISTER](Repo-docs-PRODUCT-INPUT-REGISTER) - `/mnt/DATA/git/govoplan/docs/PRODUCT_INPUT_REGISTER.md` - [Repo-docs-PRODUCTION-TARGET-HANDOFF](Repo-docs-PRODUCTION-TARGET-HANDOFF) - `/mnt/DATA/git/govoplan/docs/PRODUCTION_TARGET_HANDOFF.md` - [Repo-docs-README](Repo-docs-README) - `/mnt/DATA/git/govoplan/docs/README.md` - [Repo-docs-RECOVERY-AND-ROLLBACK-GUARANTEES](Repo-docs-RECOVERY-AND-ROLLBACK-GUARANTEES) - `/mnt/DATA/git/govoplan/docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md` diff --git a/Repo-README.md b/Repo-README.md index 3770bcc..937e1ae 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/README.md`. > Origin: `repository`. @@ -178,6 +178,10 @@ Create and validate a private, declarative installation bundle: The current executable slice and remaining production gates are documented in [Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). +The canonical distinction between local source development, split source +integration, immutable single-host rehearsal, one-host production and +multi-host Kubernetes production is in +[Deployment Profiles](docs/DEPLOYMENT_PROFILES.md). Same-host replica balancing and the multi-host promotion boundary are documented in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). Create, update, pause, resume, verify and remove a local or multi-hypervisor K3s diff --git a/Repo-docs-DEPLOYMENT-PROFILES.md b/Repo-docs-DEPLOYMENT-PROFILES.md new file mode 100644 index 0000000..0462004 --- /dev/null +++ b/Repo-docs-DEPLOYMENT-PROFILES.md @@ -0,0 +1,111 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan/docs/DEPLOYMENT_PROFILES.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# 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. + +## 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`. diff --git a/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md b/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md index 30a094e..f3205c9 100644 --- a/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md +++ b/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md`. > Origin: `repository`. @@ -17,6 +17,10 @@ reconfigures that installation instead of creating unrelated state. The canonical product journey remains [System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). This document defines the deployer boundary and the first executable slice. +The execution, topology, component-ownership and assurance modes are defined +canonically in [Deployment Profiles](DEPLOYMENT_PROFILES.md). In particular, +the editable production-like developer launcher is distinct from both an +immutable Compose rehearsal and a supported one-host production deployment. ## First Executable Slice diff --git a/Repo-docs-KUBERNETES-TEST-LAB.md b/Repo-docs-KUBERNETES-TEST-LAB.md index 00e83bf..1bf0ae0 100644 --- a/Repo-docs-KUBERNETES-TEST-LAB.md +++ b/Repo-docs-KUBERNETES-TEST-LAB.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/KUBERNETES_TEST_LAB.md`. > Origin: `repository`. @@ -65,10 +65,19 @@ sudo apt-get install -y \ sudo systemctl enable --now libvirtd ``` -Use a dedicated lab-administration account. The lifecycle invokes `sudo -n`, so -that account needs non-interactive permission for libvirt, image and cloud-init -operations. `NOPASSWD: ALL` is acceptable only on isolated lab hypervisors; use -a bounded sudo policy on shared infrastructure. +Use a dedicated lab-administration account. Remote hypervisors are managed over +SSH and the lifecycle invokes `sudo -n` there, so that account needs bounded +non-interactive permission for libvirt, image and cloud-init operations. +`NOPASSWD: ALL` is acceptable only on isolated lab hypervisors. + +On a local hypervisor, put the workstation account in the `libvirt` group and +point `vm_image_directory` at a directory writable by that account and +traversable by `libvirt-qemu`. The lifecycle connects explicitly to +`qemu:///system` and does not require passwordless local sudo. Log out and back +in after a new group assignment before running `doctor --online`. Create the +configured image directory before running the doctor; it deliberately rejects +a missing or non-writable storage root instead of silently falling back to a +different filesystem. Create a dedicated SSH key on the management workstation: @@ -129,6 +138,21 @@ Cloud image, K3s binary, K3s installer and GovOPlaN release inputs are URL plus SHA-256 pairs. Updating means changing those reviewed pins and then running the `update` command; the tool deliberately does not follow `latest` aliases. +The one-host example uses the dedicated `govoplan-lab` NAT network. Its DHCP +pool ends at `192.168.123.99`; the static lab addresses start at +`192.168.123.201`. Define and start it once on the local hypervisor: + +```bash +virsh --connect qemu:///system net-define \ + tools/lab/libvirt/govoplan-lab-network.xml +virsh --connect qemu:///system net-autostart govoplan-lab +virsh --connect qemu:///system net-start govoplan-lab +``` + +Re-running those commands is unnecessary when `virsh net-info govoplan-lab` +already reports an active, persistent network. The lab destroy command leaves +this reusable network in place. + ## 3. Validate And Create The VMs ```bash @@ -170,7 +194,9 @@ digest and by the existing GovOPlaN signature policy. It deploys PostgreSQL, Redis, single-node Garage and GreenMail on the state VM. The API, WebUI, workers and scheduler run in K3s from digest-pinned release images. A private lab CA protects both ingress and S3; backend pods receive only the CA Secret and keep -TLS verification enabled. +TLS verification enabled. The CA profile carries critical `CA:TRUE` and +`keyCertSign,cRLSign` constraints. `deploy` and `update` rotate older lab CAs +that do not satisfy that profile and reissue the ingress/S3 certificate. The final output identifies two local files below `state_directory`: @@ -189,7 +215,8 @@ sudo update-ca-certificates ``` Review mappings before adding them to `/etc/hosts`; the lifecycle does not edit -the workstation's trust or resolver configuration. +the workstation's trust or resolver configuration. Reinstall `pki/ca.crt` in +the client trust store after an automatic CA rotation. ### Enroll the first administrator @@ -219,11 +246,34 @@ chmod 0600 "$ARTIFACT" Submit the token from that artifact once to `/api/v1/bootstrap/first-admin` with the administrator email, display name, password, tenant slug and tenant name. The password must contain at least 12 -characters. Delete the local artifact after successful enrollment. +characters. The lab command performs that exchange without placing either the +token or password in process arguments, rejects redirects, and removes the +artifact only after HTTP 201: + +```bash +"$PYTHON" tools/lab/govoplan-lab.py --config "$LAB" enroll-admin \ + --email 'owner@example.org' \ + --display-name 'System Owner' \ + --tenant-slug default \ + --tenant-name 'Default Tenant' +"$PYTHON" tools/lab/govoplan-lab.py --config "$LAB" enroll-admin \ + --email 'owner@example.org' \ + --display-name 'System Owner' \ + --tenant-slug default \ + --tenant-name 'Default Tenant' \ + --apply +``` + +The public lab hostname must already resolve on the management workstation; +the command verifies TLS through the generated private CA directly. ## 5. Collect #27 Evidence -Create a short-lived API key with only `ops:operations:read`, then run: +Create a short-lived API key authorized to read the Ops status endpoint. In the +current Access administration UI, open **Tenant API keys** and select only +**View tenant settings** (`admin:settings:read`); the Ops endpoint explicitly +accepts that compatibility scope. A dedicated operator credential may instead +use `ops:operations:read`. Then run: ```bash export GOVOPLAN_OPS_API_KEY='short-lived-value' diff --git a/Repo-docs-PLATFORM-CORE-IDEAS.md b/Repo-docs-PLATFORM-CORE-IDEAS.md index 100c4cf..5f0a60d 100644 --- a/Repo-docs-PLATFORM-CORE-IDEAS.md +++ b/Repo-docs-PLATFORM-CORE-IDEAS.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/PLATFORM_CORE_IDEAS.md`. > Origin: `repository`. @@ -68,6 +68,12 @@ next responsible action, reason, deadline, consequence, and completion evidence. Workflow Engine coordinates machine and human transitions; focused views guide people through the relevant platform surfaces. +Tasks owns explicit work items and the unified work inbox. Workflow Engine owns +process execution and resumable handoffs. Notifications attract attention, and +domain modules retain their business objects. These boundaries prevent an +inbox, workflow, or notification from becoming a second copy of institutional +state. + ### 7. Views reduce complexity without changing authority The interface is a task- and role-sensitive projection of installed @@ -91,6 +97,11 @@ records who entered information, for whom, from which source, with which attestation, and how the affected person receives a usable receipt and correction path. +Responsive, mobile, desktop, and embedded launch surfaces are additional ways +to enter the same governed context, not separate products with weaker authority +or evidence. Common task-local actions may open in bounded overlays while their +owning modules retain validation, policy, and persistence. + ### 10. Successful configurations are portable products Modules are ingredients. A usable product is a signed configuration package @@ -113,6 +124,10 @@ deployment tiers. | Data and integration | Connectors, datasources, dataflow, search, external references, provider health, and reconciliation | | Runtime and assurance | Module composition, operations, deployment, recovery, security evidence, and signed packages | +Collected product ideas and normalized actor outcomes are preserved in the +[Product Input Register](PRODUCT_INPUT_REGISTER.md). They enter implementation +only through a named journey, package, or explicit discovery issue. + ## Canonical Distinctions The platform must not collapse these pairs: diff --git a/Repo-docs-PRODUCT-INPUT-REGISTER.md b/Repo-docs-PRODUCT-INPUT-REGISTER.md new file mode 100644 index 0000000..5a779a1 --- /dev/null +++ b/Repo-docs-PRODUCT-INPUT-REGISTER.md @@ -0,0 +1,202 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan/docs/PRODUCT_INPUT_REGISTER.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Product Input Register + +## Purpose + +This document preserves and normalizes product ideas and user-story notes that +inform GovOPlaN without turning a private note file into a second backlog. +Gitea issues remain the source of live work state; the stable platform direction +remains in [Platform Core Ideas](PLATFORM_CORE_IDEAS.md), the +[Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md), +and the [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md). + +The register was reconciled on 2026-08-06 from: + +- `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/ideas.md`; +- `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/user_stories.txt`. + +The source notes remain useful as the original capture. This maintained version +uses consistent terminology, makes ownership explicit, and records where an +idea enters the product program. + +## Product Themes + +### Operable and scalable installation + +An operator should be able to install, update, reconfigure, scale, back up, +restore, pause, and retire GovOPlaN through one explainable control plane. +Existing infrastructure may be reused or managed components may be provisioned. +The WebUI and CLI must invoke the same governed operations, show the planned and +completed effects, preserve recovery evidence, and never claim rollback for an +external effect that cannot actually be reversed. + +This theme is owned by Core, Admin, Ops, Policy, Files, and the signed product +package. It is tracked primarily by GovOPlaN #13 and the production evidence +issues. It advances in parallel with, but does not replace, actor-facing +reference journeys. + +### Focused, consistent work + +People should see the work and tools relevant to the current task, not the +installed module graph. Views may be defined by administrators, groups, or +users within policy. Workflow instances may pin a governed View. Contextual +help, predictable action placement, consistent central components, visible +intermediate results, and plain institutional terminology are product +requirements. + +Small task-local actions such as writing a Mail or Postbox message, completing +a Template, or manipulating Files should be launchable without abandoning the +current context. These actions remain owned by their modules and use bounded +overlays or workspaces; the shell supplies discovery and return context rather +than reimplementing them. + +This theme is owned by Core experience contracts, Views, Dashboard, Tasks, +Workflow Engine, Docs, and the contributing feature modules. The first proof is +the resumable service-to-decision/eAkte journey in GovOPlaN #42. + +### Governed human work + +An intake or event becomes owned work with a responsible actor or function, +priority, deadline, current action, consequence, source context, and completion +evidence. Tasks owns explicit work items and the unified work inbox. Workflow +Engine owns process execution, waits, retries, and handoffs. Domain modules own +the business objects and commands. Notifications attract attention but do not +replace durable work state. + +This distinction applies to service requests, technical support, approvals, +data reconciliation, campaigns, meetings, decisions, records, and failed +automation. It is the immediate shared implementation priority because users +must be able to leave work and resume it safely. + +### Institutional responsibility and workforce context + +Organization units, functions, mandates, assignments, delegations, and acting +context determine institutional responsibility. Presence, absence, illness, +availability, and similar status are effective-dated operational facts used to +route work, suppress or redirect notifications, explain planning, and trigger +policy. They are not merely profile decorations and they do not replace the IDM +lifecycle status of an identity or account. + +Time recording, absence management, sickness reporting, return-to-work +management, and applicant management form a possible workforce package. The +first implementation must be driven by a real journey and legal/privacy +profile; no new module boundary is implied solely by this register. + +### Integration-first and provider-neutral operation + +GovOPlaN should integrate tightly with software already used by an institution +and offer native alternatives only where that produces a better governed +outcome. Core-mediated provider contracts expose stable, vendor-neutral +capabilities; adapters encapsulate specific products. Authority, synchronized +fields, conflict behavior, health, credential custody, provenance, and +retirement must be explicit. + +The LBV Baden-Wuerttemberg idea is retained as a candidate workforce/payroll +integration profile and as a test of provider-neutral contracts. Desktop and +groupware integration for Microsoft Office, Outlook, LibreOffice, Thunderbird, +file managers, Windows, Unix, and macOS should use standards, deep links, +protocol handlers, synchronization, and governed connectors before custom +desktop software is introduced. + +### Inclusive channels and device surfaces + +Portal, Postbox, Mail, telephone, paper, in-person assistance, API, desktop, +and mobile are channels around the same governed work. A responsive or native +mobile surface must not create a second authority or data model. Assisted work +records representation, source, attestation, receipt, correction, and delivery +choice. People may opt into permitted distribution channels while policy keeps +mandatory channels and legal delivery requirements explicit. + +Video meetings, chat, instant messaging, and forums are retained as governed +collaboration-channel candidates. The default direction is integration with an +established provider through typed message, meeting, participant, evidence, and +retention contracts before building another communications stack. + +### Meetings, deliberation, decisions, and voting + +An institutional meeting spans scheduling, participants and mandates, +documents, agenda, discussion, formal motions, votes, decisions, minutes, +follow-up work, publication, and eligible expense settlement. Committee owns +the meeting and deliberation semantics while Calendar, Scheduling, Files, +Templates, Decisions, Tasks, Reporting, Ledger, and Voting contribute optional +capabilities. + +Voting requiring certified assurance remains a provider program. POLYAS is the +first external profile; a native provider may progress only through the +controlled assurance and certification program already tracked in Voting. + +### Controlled data work and understandable reporting + +People should manipulate data through immutable inputs, previewed operations, +intermediate materializations, reversible definition changes, durable review +decisions, quality rules, and complete lineage. Reports expose their definitions +and source revisions so controllers can understand and change how a result is +produced. Technical support may package controlled workflows that let +non-technical users safely operate otherwise hidden data. + +The monthly-data journey is the first proof. Sanctions screening follows on the +same source, snapshot, transformation, review, reporting, workflow, and +delivery contracts. + +### Institutional memory and consequence + +Decisions should be prepared, discussed, made, communicated, implemented, and +filed with their authority and consequences visible. A record/eAkte provides +the familiar administrative context across exact source revisions without +copying ownership from Cases, Decisions, Files, Forms, Campaign, Postbox, or +other modules. The institutional digital twin may later use governed +projections to model and simulate organizational change, but simulation output +never becomes authority without an explicit adoption decision. + +## Normalized Story Catalogue + +The following catalogue preserves the intent of the collected notes. It is an +orientation index, not a completion checklist. + +| Actor and desired outcome | Product owner or composition | First proof | +| --- | --- | --- | +| Operator installs, updates, scales, backs up, restores, and rolls back through one explainable workflow | Core, Admin, Ops, signed package | GovOPlaN #13 and target-evidence lane | +| System and tenant module administrators govern module availability and lifecycle | Core, Admin, Policy, Tenancy | Module entitlement and lifecycle composition | +| User works in a decluttered, consistent and task-sensitive interface | Views, Core, Dashboard, Workflow, Docs | Service-to-decision workspace | +| Policy maker defines inherited, explainable and enforced rules | Policy plus every consequential owner | Information-governance adoption gate | +| Controller and auditor reconstruct results, rules, evidence and correction paths | Audit, Reporting, Records, Dataflow | Monthly-data and eAkte journeys | +| User sees institutional terminology, current progress, intermediate results and consequences | Domain owner, Tasks, Workflow, Views | All reference journey acceptance tests | +| Voting body and voter obtain independently assured democratic voting | Voting, Committee, Identity Trust, Encryption | POLYAS profile and controlled native-provider program | +| Support staff packages safe guided manipulation of hidden data | Workflow, Dataflow, Tasks, Views | Monthly reconciliation workflow | +| Data worker performs controlled, understandable and recoverable transformations | Datasources, Connectors, Dataflow, Reporting | GovOPlaN #8 | +| Decision maker prepares, deliberates, decides, records and follows consequences | Committee, Decisions, Tasks, Records, Reporting | Service-to-decision journey | +| Management delegates responsibility and receives governed activity reports | Organizations, IDM, Access, Policy, Reporting | Function-bound Postbox and work inbox | +| Institution models and simulates organizational change | Organizations, Policy, Dataflow, Reporting, Digital Twin | Later governed digital-twin package | +| Sender distributes generated files to functions without knowing incumbents | Campaign, Distribution Lists, Postbox, Organizations, IDM | Governed communication package | +| Function holder receives current and policy-selected historical work and information | IDM, Access, Postbox, Tasks, Records | Postbox reassignment/history tests | +| Administrative worker accesses one familiar eAkte context across exact owned objects | Records and record-source providers | GovOPlaN #42 and Records #8 | +| User invokes common message, template and file actions without leaving the current task | Core shell, Views, Workflow and contributing modules | Task-local action contract and service workspace | + +## Idea Preservation Map + +| Original idea cluster | Preserved direction | +| --- | --- | +| Time recording, absence, sickness, reintegration, applicant management | Governed workforce-context journey; effective-dated status and privacy profile before module expansion | +| LBV BW interface | Candidate provider-neutral workforce/payroll connector profile | +| Abstract interfaces | Versioned Core contracts with product adapters and explicit source authority | +| Desktop and groupware integration | Standards, connectors, deep launch and synchronization before custom clients | +| GovOPlaN app/mobile-first pages | Responsive shared semantics; native shell only when a proven journey needs device capabilities | +| Video, chat, instant messaging and forum | Optional governed collaboration providers with retention/evidence contracts | +| Somacos Session-style meeting management | Committee-led meeting composition across Calendar, Files, Decisions, Templates, Tasks, Reporting and Ledger | +| Stronger software integration | Integration-first roadmap rule and first full external product connectors | + +## Maintenance + +When a source idea becomes actionable: + +1. link it to a named reference journey or explicit discovery issue; +2. identify the owning module and external authority; +3. create or update the Gitea issue with acceptance criteria; +4. keep live status out of this document; +5. update this register only when the durable interpretation changes. diff --git a/Repo-docs-README.md b/Repo-docs-README.md index f907a97..65533d2 100644 --- a/Repo-docs-README.md +++ b/Repo-docs-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/README.md`. > Origin: `repository`. @@ -21,6 +21,7 @@ volatile repository, issue, release, or maturity counts as current facts. | Which institutional concepts and owners form the target architecture? | [Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) | | Which end-to-end proofs should guide implementation? | [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md) | | What is the reconciled state now? | [Strategy Status](STRATEGY_STATUS.md) | +| Which collected ideas and user stories inform the product direction? | [Product Input Register](PRODUCT_INPUT_REGISTER.md) | The dated [Strategic Review](STRATEGIC_REVIEW_2026-08-05.md) explains why the current reset and sequencing were chosen. It is an assessment record, not a @@ -46,6 +47,7 @@ second live status page. - [Platform Control Plane](PLATFORM_CONTROL_PLANE.md) - [Installation and Deployment Architecture](INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md) - [Kubernetes VM Test Lab](KUBERNETES_TEST_LAB.md) +- [Deployment Profiles](DEPLOYMENT_PROFILES.md) - [Scaling and Multi-Host Deployment](SCALING_AND_MULTI_HOST_DEPLOYMENT.md) - [Recovery and Rollback Guarantees](RECOVERY_AND_ROLLBACK_GUARANTEES.md) - [Recovery Ledger Adoption](RECOVERY_LEDGER_ADOPTION.md) @@ -80,3 +82,5 @@ be edited manually. repository. Meta documentation defines cross-module outcomes and contracts. 6. A new strategy document must replace, narrow, or link an existing source; it must not introduce a parallel roadmap. +7. The Product Input Register preserves external idea and story notes, but only + Gitea issues carry live priority, ownership, and implementation state. diff --git a/Repo-docs-REFERENCE-JOURNEY-PROGRAM.md b/Repo-docs-REFERENCE-JOURNEY-PROGRAM.md index 27f941b..16f40a2 100644 --- a/Repo-docs-REFERENCE-JOURNEY-PROGRAM.md +++ b/Repo-docs-REFERENCE-JOURNEY-PROGRAM.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/REFERENCE_JOURNEY_PROGRAM.md`. > Origin: `repository`. @@ -46,6 +46,19 @@ identify the journey it improves, or provide security, operability, recovery, accessibility, or usability evidence that those journeys require. Work that does neither stays in the backlog until a concrete consumer exists. +The Records vertical now supplies the journey's native file plan, immutable +record and item revisions, chronology, close/reopen, retention calculation, +holds, appraisal, independent disposition approval, recovery-ledger evidence, +and archive-neutral package simulation. Forms Runtime, Cases, and Decisions +expose exact, permission-rechecked source revisions for explicit filing, and +all three contribute metadata-only native Search projections that can be +rebuilt from authoritative state. The executable fixtures prove those native +transitions without claiming archival custody. A persisted Workflow Engine +handoff is now reloaded through the Tasks aggregation surface and remains +visible until the authoritative Workflow transition completes. The journey +still needs pinned-composition reconstruction evidence and one target-tested +archive profile. + ## Why this sequence The sequence grows one connected product rather than advancing repositories in @@ -120,6 +133,14 @@ journey needs and supplies contracts shared by all five stages. Module manifests state `contract_only`, `partial`, `enforced`, or `not_applicable` adoption with evidence; supported maturity is blocked until every applicable dimension is enforced. +11. **Durable human work.** Tasks aggregates explicit work and module-owned + attention items; Workflow Engine persists process state and handoffs; + Notifications attracts attention; Views focuses the relevant surfaces. + Leaving or refreshing the browser never becomes the only record that work + remains unfinished. +12. **Task-local tools.** Mail, Postbox, Templates, Files, and other common + actions may contribute bounded launch surfaces with return context. The + shell and Workflow compose them without copying their data or validation. ## Documentation contract for every reference stage diff --git a/Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT.md b/Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT.md index 2fea9af..1904ee7 100644 --- a/Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT.md +++ b/Repo-docs-SCALING-AND-MULTI-HOST-DEPLOYMENT.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md`. > Origin: `repository`. @@ -107,10 +107,18 @@ migration and database-wait containers. It does not disable certificate verification or replace the WebUI trust store. The generated containers run as non-root with a read-only root filesystem and -an ephemeral `/tmp`. Runtime Deployments wait for the exact configured database -migration heads before starting. The API exposes `/health/ready`, which fails -while that API node is draining or cannot prove its runtime-coordination -heartbeat. +an ephemeral `/tmp`. Celery Beat keeps its replaceable schedule database there; +durable schedule definitions remain in shared state. The WebUI resolves its +configured API Service when the container starts, so Kubernetes deployments do +not inherit the Compose-only `load-balancer` hostname. Runtime Deployments wait +for the exact dependency-resolved database migration heads before starting. +The API exposes `/health/ready`, which fails while that API node is draining or +cannot prove its runtime-coordination heartbeat. + +Replicated API, WebUI, and worker Deployments use a hard hostname-spread +constraint scoped to the current pod-template hash. A rollout therefore keeps +each replica set distributed across independently schedulable nodes instead of +allowing all replacement pods to settle on one node after the old set exits. ## Runtime Coordination @@ -269,6 +277,10 @@ record under the installation evidence directory and never retains the API key. Use `--exercise-api-pod-loss` in an approved drill window to delete one API pod, observe the public readiness path continuously, and record its replacement. +Generated API workloads use a ten-second pre-stop drain so Kubernetes can remove +the terminating endpoint from ingress and service routing before Uvicorn exits. +Do not remove or shorten this drain without repeating the public-path pod-loss +test against the target ingress controller and network implementation. This proves the bounded stateless-node-loss slice only. Session continuity, accepted-job redelivery, state-service failover, and coordinated restore remain separate target exercises whose signed evidence is governed by diff --git a/Repo-docs-STRATEGY-STATUS.md b/Repo-docs-STRATEGY-STATUS.md index a41f196..b4b91af 100644 --- a/Repo-docs-STRATEGY-STATUS.md +++ b/Repo-docs-STRATEGY-STATUS.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/STRATEGY_STATUS.md`. > Origin: `repository`. @@ -11,9 +11,10 @@ | Field | Value | | --- | --- | -| Reconciled on | 2026-08-05 | +| Reconciled on | 2026-08-06 | | Source scope | Local workspace manifests, source inventory, focused journey checks, signed release evidence, and live Gitea issue state | | Stable direction | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) and [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) | +| Collected product input | [Product Input Register](PRODUCT_INPUT_REGISTER.md) | | Delivery source | Gitea issues | This is the only prose source for current cross-product status. It is a @@ -22,8 +23,8 @@ evidence remain authoritative for specific maturity claims. ## Portfolio Snapshot -- 65 source module manifests were loadable and architecture-declared. -- 47 modules declared `vertical_slice`; 18 declared `scaffold`. +- 66 source module manifests were loadable and architecture-declared. +- 48 modules declared `vertical_slice`; 18 declared `scaffold`. - No module declared `reference_ready`, `supported`, or `lts`. - The live portfolio had 133 open issues, including 39 priority-P1 items. - 117 open issues had no milestone, so issue labels do not yet express a @@ -37,19 +38,20 @@ document. ## Interface And Contract Evidence -The 2026-08-05 source inventory found: +The 2026-08-06 source inventory found: -- 1,247 UI fields and 1,220 UI actions; -- 7,929 stable interface declarations with no duplicate IDs; -- 39 frontend routes and 872 backend endpoints; +- 1,307 UI fields and 1,291 UI actions; +- 8,157 stable interface declarations with no duplicate IDs; +- 43 frontend routes and 920 backend endpoints; - no public WebUI surfaces missing runtime declarations; - no stale runtime route declarations; - no unclassified endpoint without a static UI reference; -- all 1,247 fields with a resolvable F1 context; 1,087 remain candidates for +- all 1,307 fields with a resolvable F1 context; 1,143 remain candidates for richer field-specific content beyond page/module fallback; - German (`de`) as the complete reference locale and no used key missing from the required German or English catalogs; -- 260 module information-governance dimensions classified as `contract_only`. +- 3 module information-governance dimensions classified as `enforced`, 1 as + `partial`, and 260 as `contract_only`. This is an honest platform-wide baseline, not a claim that temporal, purpose, retention, and institutional-context adoption is complete. @@ -74,24 +76,32 @@ prevent a reference-ready claim. Services, Forms, Forms Runtime, Cases, Parties, Mandates, Approvals, Committee, Voting, Decisions, Portal, Postbox, and Audit have an executable service-to- -decision fixture. Browser-complete assisted intake, production identity, -records, delivery, and target evidence remain. +decision fixture. Public and invitation intake can retain Files-backed +evidence; Forms submissions, Cases, and formal Decisions can be explicitly +filed as exact eAkte source revisions and reconstructed through permission- +rechecked native Search projections. A durable Workflow Engine handoff now +survives session restart and appears through the Tasks work inbox until the +authoritative transition completes. Browser-complete assisted intake, broader +work projections and escalation, production identity and delivery, a named +archive profile, and target evidence remain. ### Governed data and assurance Connectors, Datasources, Dataflow, Reporting, Search, Policy, Risk Compliance, and Workflow provide source governance, immutable snapshots, transformation, quality, semantic reporting, and provenance foundations. The monthly-data and -sanctions journeys still need real connectors, complete interactive -reconciliation, publication/export, and guided handoff evidence. +sanctions compositions now prove immutable connector snapshots, pinned +Dataflow publication, Risk Compliance review, and rescreening in process. The +journeys still need target connector profiles, complete interactive +reconciliation, governed export/delivery, and browser-level handoff evidence. ## Material Gaps | Gap | Consequence | Next proof | | --- | --- | --- | | No reference-ready product package | The platform cannot yet make a bounded supported-product claim | Complete one named target composition and evidence bundle | -| Human-work spine incomplete | Users still navigate modules and remember unfinished work | Task/work inbox, resumable guided journey, deadlines and handoffs | -| Records/eAkte shallow | Institutional memory and disposition remain fragmented | Native record lifecycle plus external DMS/archive overlay | +| Human-work spine is only an MVP | Tasks aggregates explicit work plus Workflow, Approval, and unread Postbox projections, but broad domain coverage, deadline escalation, assignment lifecycle, and focused product UX remain | Extend source providers through the three reference journeys and prove overdue/reassignment behavior in browser tests | +| Records/eAkte target integration incomplete | Native lifecycle, retention, holds, approval, recovery, and transfer simulation are implemented, but real custody is not proved | Target-test one archive/xdomea profile and complete the assisted reference journey | | Cross-cutting governance adoption uneven | Historical and purpose-sensitive behavior varies by module | Enforced adoption declarations and route/query/effect migration | | Explicit help/accessibility depth incomplete | German/reference and F1 association gates now pass, but generic fallback remains too common | High-risk German help content and browser/a11y matrix | | Real federation absent | Cross-institution exchange remains connector-specific | Paired-instance signed exchange and reconciliation proof | @@ -104,9 +114,13 @@ reconciliation, publication/export, and guided handoff evidence. 2. Complete governed communication and Postbox against a named target. 3. Complete the monthly-data flow and use it as the data foundation for sanctions screening. -4. Complete one digital and assisted service-to-decision journey with an eAkte. -5. Add native PostgreSQL search coverage for the objects used by those - journeys; keep OpenSearch optional. +4. Complete the browser and resumable-work proof for the digital and assisted + service-to-decision journey with its existing exact eAkte filing contracts. +5. Complete native PostgreSQL search coverage for remaining journey-owned + objects and prove reauthorization and reindex operations at target volume; + keep OpenSearch optional. Communication, Records, service-to-decision, + Dataflow, Reporting, Risk Compliance, and Datasource catalogue sources now + exist. 6. Prove one external product connector and one GovOPlaN federation exchange. 7. Finish multi-host, restore, provider, accessibility, and independent signed target evidence before increasing maturity claims.