diff --git a/Repo-README.-.md b/Repo-README.-.md new file mode 100644 index 0000000..c558548 --- /dev/null +++ b/Repo-README.-.md @@ -0,0 +1,241 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan/README.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN + + +**Repository type:** system (meta). + + +[![Module Matrix](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/module-matrix.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=module-matrix.yml&actor=0&status=0) +[![Release Integration](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/release-integration.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=release-integration.yml&actor=0&status=0) +[![Deployment Installer](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/deployment-installer.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=deployment-installer.yml&actor=0&status=0) +[![Dependency Audit](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/dependency-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=dependency-audit.yml&actor=0&status=0) +[![Security Audit](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/security-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=security-audit.yml&actor=0&status=0) + +This is the GovOPlaN meta repository. It is the operator entry point for +whole-product development, release orchestration, repository bootstrap, and +system-level Docker composition. + +It is not a runtime module. Runtime behavior belongs to `govoplan-core` and the +installed modules/connectors discovered by core. + +## Common Commands + +Create the whole-product development virtualenv in this meta repository: + +```sh +python3 -m venv .venv +./.venv/bin/python tools/repo/sync-python-environment.py --requirements requirements-dev.txt --python ./.venv/bin/python --upgrade-pip +``` + +The meta venv is the default Python environment for launch, check, release, and +Gitea tooling. `GOVOPLAN_VENV_ROOT` or `PYTHON` can override it for special +cases. + +Start the development stack through the meta repository: + +```sh +./tools/launch/launch-dev.sh +``` + +Open the WebUI in a browser after launch only when explicitly requested: + +```sh +GOVOPLAN_OPEN_BROWSER=1 ./tools/launch/launch-dev.sh +``` + +Limit backend reload triggers during focused module work without changing the +enabled module graph: + +```sh +GOVOPLAN_BACKEND_RELOAD_MODULES=calendar,campaign ./tools/launch/launch-dev.sh +``` + +Set `GOVOPLAN_BACKEND_RELOAD_MODULES=none` to watch only core/config sources. +Leaving it unset keeps the broad default and watches all enabled modules. + +Start the shared development PostgreSQL service: + +```sh +./tools/launch/start-dev-postgres.sh +``` + +Check which GovOPlaN repositories are present and dirty: + +```sh +./tools/repo/repo-status.sh +``` + +Clone missing repositories listed in `repositories.json`: + +```sh +./tools/repo/bootstrap-repositories.py +``` + +Update generated repository type notes in all READMEs: + +```sh +./tools/repo/update-repository-type-notes.py +``` + +Regenerate the human-readable repository link index: + +```sh +./tools/repo/generate-repository-index.py +``` + +Synchronize the Python environment after package metadata changes: + +```sh +./.venv/bin/python tools/repo/sync-python-environment.py --requirements requirements-dev.txt --python ./.venv/bin/python +``` + +Run the static cross-repository module contract check: + +```sh +./tools/checks/check-contracts.sh +``` + +Require backend, manifest, frontend, lockfile, and release-composition versions +to agree before a release: + +```sh +./.venv/bin/python tools/checks/check-version-alignment.py --release-composition +``` + +Generate the CycloneDX dependency inventory from a resolved release environment: + +```sh +./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python +``` + +For reproducible release artifacts, set `SOURCE_DATE_EPOCH` to the release +commit timestamp (or pass an explicit timezone-qualified `--timestamp`): + +```sh +SOURCE_DATE_EPOCH="$(git -C ../govoplan-core show -s --format=%ct HEAD)" \ + ./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python +``` + +Run the consolidated focused verification suite: + +```sh +./tools/checks/check-focused.sh +``` + +Run the cross-repository dependency boundary gate: + +```sh +./tools/checks/check_dependency_boundaries.py +``` + +Run installer rollback drills: + +```sh +./tools/checks/module-installer-rollback-drill.py --format json +``` + +Release, catalog, Gitea, security-audit, and cross-repository maintenance +commands should also be called from this repository through `tools/`. + +Start the local release console: + +```sh +./.venv/bin/python tools/release/release-console.py +``` + +Create and validate a private, declarative installation bundle: + +```sh +./.venv/bin/python tools/deployment/govoplan-deploy.py init \ + --directory ~/.local/share/govoplan/installations/default +./.venv/bin/python tools/deployment/govoplan-deploy.py doctor \ + --directory ~/.local/share/govoplan/installations/default +``` + +The current executable slice and remaining production gates are documented in +[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.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). +The recovery state machine, migration rollback boundary, and required restore +drills are documented in +[Recovery and Rollback Guarantees](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md). + +## Configuration + +The repository root `.env.example` is the self-hosted operator template for a +full GovOPlaN installation. Development profile examples live below `dev/`, for +example `dev/postgres/.env.example` and `dev/production-like/.env.example`. + +Do not commit populated `.env` files. Gitea tokens should stay in a local file +such as `~/.config/gitea/gitea.env` and be passed with `--env-file`. + +## Structure + +The repository categories are documented in +`docs/REPOSITORY_STRUCTURE.md`. The machine-readable list lives in +`repositories.json`; the clickable human-readable index is +`docs/REPOSITORY_INDEX.md`. + +Meta ownership and module install/contract boundaries are documented in +`docs/META_REPO_SCAN.md` and `docs/MODULE_CONTRACTS_AND_INSTALLS.md`. +Frontend layout principles for module pages are documented in +`docs/FRONTEND_LAYOUT_PRINCIPLES.md`. +The provider-neutral datasource boundary and reusable Dataflow/Workflow graph +contract are documented in +`docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md`. +The cross-product destination, stakeholder visions, configuration archetypes, +connected outcome stories, and capability horizons are documented in +the [Connected Governance Platform Roadmap](docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md). +The reconciled institutional semantics, source-authority modes, module layers, +candidate Mandates/Services/Parties/Decisions boundaries, and migration +sequence are documented in the +[Institutional Governance Target Architecture](docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md). +The selected Campaign-to-Postbox-to-data-to-collaboration implementation path, +including stage gates and shared documentation expectations, is in the +[Reference Journey Program](docs/REFERENCE_JOURNEY_PROGRAM.md). +The administrator journey from Core-only bootstrap through online module +installation, scale-out, and reversible environment promotion is defined in +[System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). +The corresponding host deployment compiler, managed/external component choices, +reconfiguration semantics, and safe Web update boundary are defined in +[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). +The concrete replica, worker-node, load-balancer, and shared-state topology is +defined in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). +Durable deployment journals, Core recovery evidence, and the distinction +between pre-migration configuration restore and post-migration forward recovery +are defined in +[Recovery and Rollback Guarantees](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md). +The first Campaign-centric capability and infrastructure fit assessment is in +`docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. Its rerun tooling can collect and +verify a bounded installed composition; target, provider and production claims +remain separate, expiring attestations signed by independently scoped proof +authorities. + +# GovOPlaN Docker + +Whole-product Docker composition belongs in this meta repository. + +Current module-specific Docker test beds remain in their owning repositories +until they are migrated or wrapped here: + +- `govoplan/dev/postgres` +- `govoplan/dev/production-like` +- `govoplan-campaign/dev/mail-testbed` +- `govoplan-files/dev/connectors` + +The target shape is: + +- `govoplan/dev/postgres`: shared local development PostgreSQL service. +- `govoplan/dev/production-like`: production-like validation composition. +- module repositories keep only narrow connector or protocol test beds. + +What doesn't belong here: + +- `addideas-govoplan-website/docker-compose.yml`: public website serving +profile; this one stays with the website repository.