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