govoplan/docs/README.md

# GovOPlaN Documentation

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

| Document | Role |
| --- | --- |
| [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 |

## Architecture

| Topic | Canonical source |
| --- | --- |
| 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) |

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`.

## Operations

| 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) |

## Project Reference

- [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.

## 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.

- [Generated Campaign capability and infrastructure fit, 2026-07-22](evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.generated.md)
- [Supporting narrative for the 2026-07-22 assessment](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.

Regenerate and verify the human fit report from its JSON input with:

```sh
./.venv/bin/python tools/assessments/generate-capability-fit-report.py
./.venv/bin/python tools/assessments/generate-capability-fit-report.py --check
```

## Maintenance Rules

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 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
```