govoplan/docs/REPOSITORY_STRUCTURE.md

GovOPlaN Repository Structure

GovOPlaN uses separate repositories for runtime modules, connector modules, system orchestration, and public website/catalog publication.

Categories

system

System repositories are not optional runtime modules. They provide platform execution, orchestration, development entry points, installer tooling, or core runtime contracts.

Current system repositories:

• govoplan: meta repository for whole-product orchestration.
• govoplan-core: runtime kernel/server runner, module registry, shared UI shell, installer, migration orchestration, and core contracts.

module

Runtime modules provide user-visible product behavior. They can include backend routes, database migrations, frontend contributions, permissions, docs, workers, and lifecycle hooks.

Modules must communicate through core contracts, capabilities, providers, and routes. They must not import another module's internal implementation directly.

connector

Connector repositories adapt GovOPlaN capabilities to external protocols, platforms, and integration formats. A connector may be a runtime module, but its business responsibility is transport/integration, not product semantics.

Examples:

• govoplan-rest
• govoplan-soap
• govoplan-fit-connect
• govoplan-xoev
• govoplan-xrechnung
• govoplan-xta-osci
• govoplan-connectors

website

Website repositories are public content or publication targets. They are not installed into a GovOPlaN runtime.

Current website repository:

• addideas-govoplan-website: public website and release catalog publication target.

Meta Repository Role

govoplan is the canonical operator entry point. Whole-product commands should be available here first:

• development launch
• repository bootstrap/status
• whole-product Docker composition
• release tagging
• catalog publication
• installer/daemon orchestration
• cross-repository Gitea issue/wiki/label helpers
• security and dependency audit tooling

Whole-product command implementations live under govoplan/tools.

Core keeps runtime-specific commands only.

Repositories are linked through repositories.json and scripts rather than git submodules. Development checkouts can keep their own branches and dirty state, while release/catalog tooling can still resolve the exact repository list from one place. If a deployment profile later needs pinned SHAs for every repository, generate that lock as a release artifact instead of making day-to-day development depend on submodule updates.

Docker Placement

Whole-product Docker and production-like deployment composition belongs in govoplan.

Current shared profiles:

• dev/postgres
• dev/production-like

Website-specific serving profiles stay with addideas-govoplan-website.

Module-specific test beds stay in the owning module repository. Examples:

• govoplan-files/dev/connectors
• govoplan-campaign/dev/mail-testbed
• connector protocol test beds in their connector repositories

This keeps local module tests close to the code while giving operators one repository for product deployment.

addideas-govoplan-website and Release Logic

addideas-govoplan-website should be treated as the public website and catalog publication target, not as the release orchestrator.

The release workflow should be invoked from govoplan. It may write signed catalog artifacts into addideas-govoplan-website/public/catalogs/... and then build or deploy the website.

A separate govoplan-release repository should only be introduced if release logic becomes an independently versioned service or toolchain. For now, a separate repository would add coordination overhead without a clear boundary.

If embeddable public widgets become a runtime capability later, create a separate installable module for that. The public website repository should stay website/publication content only.

Config Import/Export

Configuration import/export is runtime administration behavior. It should stay with core/admin until it grows into a separately installable product capability.

Create a govoplan-config module only if configuration packages need their own module lifecycle, permissions, migrations, background jobs, or public API.

No govoplan-meta Runtime Module

Do not add a govoplan-meta runtime module for repository metadata. Repository metadata belongs in this meta repository. Installed runtime metadata belongs in the core module registry and module manifests.

If a runtime "system" surface is needed, it should be a core/admin/ops feature backed by explicit capabilities, not a pseudo-module that mirrors repository state.