Initialize GovOPlaN meta repository

docs/REPOSITORY_STRUCTURE.md

@@ -0,0 +1,133 @@
+# 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.