GovOPlaN/govoplan
2
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: organize cross-product documentation
Dependency Audit / dependency-audit (push) Successful in 1m46s
Details
Deployment Installer / deployment-installer (push) Successful in 9s
Details
Security Audit / security-audit (push) Successful in 11m48s
Details

Browse Source
This commit is contained in:
zemion
2026-08-17 16:52:51 +02:00
parent 209a43592f
commit c66e1b768d
46 changed files with 384 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+100 -61
View File
@@ -1,80 +1,119 @@
# GovOPlaN Documentation Map
# GovOPlaN Documentation
This directory contains cross-repository product, architecture, release, and
operational documentation. The map below defines which document answers which
question. A document not listed as the current status source must not present
volatile repository, issue, release, or maturity counts as current facts.
This directory contains cross-repository product, architecture, delivery, and
project documentation. Start here instead of browsing every file.
## Read First
| Need | Source |
| --- | --- |
| Understand the platform in ten minutes | [Platform Core Ideas](strategy/PLATFORM_CORE_IDEAS.md) |
| See the intended product sequence | [Roadmap](strategy/ROADMAP.md) |
| Check the reconciled state and material gaps | [Strategy Status](strategy/STRATEGY_STATUS.md) |
| Find active work, priority, or ownership | [Gitea issue workflow](project/GITEA_ISSUES.md) and Gitea issues |
| Understand the selected end-to-end proofs | [Reference Journey Program](strategy/REFERENCE_JOURNEY_PROGRAM.md) |
The first three documents are the normal entry points. Detailed architecture,
runbooks, evidence, and historical assessments support them; they are not
parallel roadmaps.
## Strategy
| Question | Canonical source |
| Document | Role |
| --- | --- |
| What are the stable ideas and boundaries of the platform? | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) |
| What product outcomes should GovOPlaN pursue? | [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) |
| 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) |
| [Platform Core Ideas](strategy/PLATFORM_CORE_IDEAS.md) | Stable purpose, principles, planes, distinctions, and non-goals |
| [Roadmap](strategy/ROADMAP.md) | Concise product outcomes, horizons, and current sequence |
| [Strategy Status](strategy/STRATEGY_STATUS.md) | Only prose source for current cross-product status |
| [Reference Journey Program](strategy/REFERENCE_JOURNEY_PROGRAM.md) | Acceptance journeys and their gates |
| [Product Input Register](strategy/PRODUCT_INPUT_REGISTER.md) | Normalized ideas and user-story source material |
| [System Administrator Lifecycle](strategy/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md) | Installation and lifecycle outcome story |
| [Detailed Connected-Platform Vision](strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) | Long-form stakeholder, configuration, and outcome catalogue |
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
second live status page.
## Product Architecture
## Architecture
| Topic | Canonical source |
| --- | --- |
| Product-facing experience and hiding technical module boundaries | [Product Experience and Module Boundaries](PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md) |
| Configurable product areas and task-local tools | [Quick Access and Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md) |
| Federation between autonomous installations | [Federated GovOPlaN Architecture](FEDERATED_GOVOPLAN_ARCHITECTURE.md) |
| Institutional digital twin and continuous assurance | [Institutional Digital Twin](INSTITUTIONAL_DIGITAL_TWIN.md) |
| Assisted and non-digital channels | [Assisted and Non-Digital Channels](ASSISTED_AND_NON_DIGITAL_CHANNELS.md) |
| Cross-module temporal, purpose, retention, and institutional-context adoption | `govoplan-core/docs/INFORMATION_GOVERNANCE_ADOPTION.md` |
| eAkte and digital-record ownership | `govoplan-records/docs/EAKTE_ARCHITECTURE.md` |
| Data source, definition, and transformation graph | [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md) |
| Focused task views | [Views Architecture](VIEWS_ARCHITECTURE.md) |
| Shared interface patterns | [Interface Pattern Language](INTERFACE_PATTERN_LANGUAGE.md) |
| Institutional model and ownership | [Institutional Governance Target Architecture](architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) |
| Product experience and technical boundaries | [Product Experience and Module Boundaries](architecture/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md) |
| Shared interface and layout rules | [Interface Pattern Language](architecture/INTERFACE_PATTERN_LANGUAGE.md) |
| Focused task views | [Views Architecture](architecture/VIEWS_ARCHITECTURE.md) |
| Product areas and task-local tools | [Quick Access and Product Areas](architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md) |
| Platform self-description and configuration | [Platform Control Plane](architecture/PLATFORM_CONTROL_PLANE.md) |
| Data sources, definitions, and graph execution | [Datasource and Definition Graph Architecture](architecture/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md) |
| Federation between autonomous installations | [Federated GovOPlaN Architecture](architecture/FEDERATED_GOVOPLAN_ARCHITECTURE.md) |
| Institutional digital twin | [Institutional Digital Twin](architecture/INSTITUTIONAL_DIGITAL_TWIN.md) |
| Assisted and non-digital participation | [Assisted and Non-Digital Channels](architecture/ASSISTED_AND_NON_DIGITAL_CHANNELS.md) |
## Runtime And Delivery
Module-specific architecture remains in the owning repository. In particular,
information-governance adoption is in
`govoplan-core/docs/INFORMATION_GOVERNANCE_ADOPTION.md`, and the eAkte model is
in `govoplan-records/docs/EAKTE_ARCHITECTURE.md`.
- [Module Contracts and Installs](MODULE_CONTRACTS_AND_INSTALLS.md)
- [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)
- [Package Registry Releases](PACKAGE_REGISTRY_RELEASES.md)
## Operations
## Evidence And Snapshots
| Need | Source |
| --- | --- |
| Installation model and managed components | [Installation and Deployment Architecture](operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md) |
| Supported operating modes | [Deployment Profiles](operations/DEPLOYMENT_PROFILES.md) |
| Horizontal scaling and multi-host topology | [Scaling and Multi-Host Deployment](operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md) |
| Local Kubernetes evidence target | [Kubernetes VM Test Lab](operations/KUBERNETES_TEST_LAB.md) |
| Recovery guarantees and state machine | [Recovery and Rollback Guarantees](operations/RECOVERY_AND_ROLLBACK_GUARANTEES.md) |
| Recovery-ledger rollout | [Recovery Ledger Adoption](operations/RECOVERY_LEDGER_ADOPTION.md) |
| Backup evidence contract | [Backup and Restore Evidence](operations/BACKUP_AND_RESTORE_EVIDENCE.md) |
| Target handoff and independent evidence | [Production Target Handoff](operations/PRODUCTION_TARGET_HANDOFF.md) |
| Evidence collection and promotion | [Target Maturity Evidence Runbook](operations/TARGET_MATURITY_EVIDENCE_RUNBOOK.md) |
| Package publication and consumption | [Package Registry Releases](operations/PACKAGE_REGISTRY_RELEASES.md) |
| Release-console operation | [Release Console](operations/RELEASE_CONSOLE.md) |
| Module compatibility and install behavior | [Module Contracts and Installs](operations/MODULE_CONTRACTS_AND_INSTALLS.md) |
| Security-audit toolchain | [Security Audit](operations/SECURITY_AUDIT.md) |
These documents are intentionally dated or pinned. They may remain useful even
after the product changes, but they do not override `STRATEGY_STATUS.md`.
## Project Reference
- [Capability and Infrastructure Fit Assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md), pinned to the 2026-07-22 Campaign composition
- [Strategic Review 2026-08-05](STRATEGIC_REVIEW_2026-08-05.md)
- [Backup and Restore Evidence](BACKUP_AND_RESTORE_EVIDENCE.md)
- [Production Target Handoff](PRODUCTION_TARGET_HANDOFF.md)
- [Target Maturity Evidence Runbook](TARGET_MATURITY_EVIDENCE_RUNBOOK.md)
- [Repository Index](project/REPOSITORY_INDEX.md) is the human-readable module
and repository directory; `../repositories.json` is authoritative for tools.
- [Repository Structure](project/REPOSITORY_STRUCTURE.md) defines ownership of
meta, module, deployment, and website content.
- [Gitea Issues](project/GITEA_ISSUES.md) defines labels, templates, import, and
state-update conventions.
Machine-readable schemas and evidence files belong beside the document that
defines them. Generated inventories belong in `audit-reports/` and should not
be edited manually.
## Evidence And Archive
Pinned evidence is retained under `evidence/`; completed reviews and migration
inventories are under `archive/`. They explain or prove a dated state and must
not be read as current product status.
- [Campaign capability and infrastructure fit, 2026-07-22](evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md)
- [Interface surface inventory, 2026-08-03](evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md)
- [Strategic review, 2026-08-05](archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md)
- [Meta repository scan, 2026-07-13](archive/2026-07/META_REPO_SCAN.md)
- [Meta repository migration audit](archive/2026-07/META_REPOSITORY_MIGRATION_AUDIT.md)
The JSON files at the root of this directory are machine-readable schemas,
evidence inputs, and project configuration. Their paths are intentionally
stable because tools and published schema identifiers consume them; they are
not additional reading-list entries.
## Maintenance Rules
1. Gitea issues are the only live work-state source.
2. `STRATEGY_STATUS.md` is the only prose reconciliation of current portfolio
state. Refresh it from manifests, inventories, tests, and Gitea; do not copy
its counts into durable architecture pages.
1. Gitea issues are the only live source for work state, priority, and owner.
2. `strategy/STRATEGY_STATUS.md` is the only prose reconciliation of current
portfolio state. Do not copy its volatile counts into durable documents.
3. Durable documents state decisions, invariants, ownership, and acceptance
gates. They link to status and issues for implementation depth.
4. Dated assessments retain their original composition and conclusion. Add a
snapshot notice rather than silently updating their claims.
5. Module-specific behavior and user/admin documentation remain in the owning
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.
gates. They link to Gitea for implementation detail.
4. Dated evidence and archive documents retain their original composition and
conclusion. Add a snapshot notice instead of silently modernizing them.
5. Module-specific behavior and user/admin documentation stay in the owning
repository. Meta documentation covers cross-module outcomes and contracts.
6. Do not add another top-level Markdown file. Place new content in the
appropriate directory and add it to this map only when it has a distinct
canonical purpose.
7. A new strategy document must replace, narrow, or become a reference for an
existing source; it must not introduce a parallel roadmap.
8. The Product Input Register preserves source ideas. Only a named journey,
package, or Gitea issue turns an idea into implementation work.
After moving or adding documentation, run:
```sh
./.venv/bin/python -m unittest tests.test_documentation_structure
```