# GovOPlaN

<!-- govoplan-repository-type:start -->
**Repository type:** system (meta).
<!-- govoplan-repository-type:end -->

[![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)
[![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
```

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

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