chore: sync GovOPlaN module split state

docs/CONCEPT.md

@@ -0,0 +1,163 @@
+# govoplan-connectors Concept
+
+## Purpose
+
+`govoplan-connectors` is the integration catalogue and connector coordination
+module. It helps GovOPlaN connect to existing public-sector and organizational
+systems without pretending to replace every specialist platform.
+
+The module owns connector metadata, connection profiles, health checks, test
+results, credential references, and generic integration events. Protocol-heavy
+or domain-heavy integrations may live in dedicated modules once their scope is
+clear.
+
+Detailed follow-up documents:
+
+- [Public-sector integration catalogue](PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md)
+- [Connector source lifecycle](CONNECTOR_SOURCE_LIFECYCLE.md)
+- [OpenProject connector concept](OPENPROJECT_CONNECTOR.md)
+- [OpenDesk integration map](OPENDESK_INTEGRATION_MAP.md)
+
+## Ownership
+
+The module owns:
+
+- connector catalogue entries and capability metadata
+- connection profiles and endpoint configuration
+- credential references and test diagnostics
+- generic webhook/polling/job coordination metadata
+- connector health status and last-test evidence
+- operator-visible integration inventory
+- cross-module discovery of available external capabilities
+
+The module does not own:
+
+- file storage semantics, owned by files/DMS
+- identity provisioning semantics, owned by IDM/access
+- mail/calendar semantics, owned by mail/calendar
+- case/workflow/task/domain records
+- payment, ledger, XRechnung, XTA/OSCI, FIT-Connect, or XOE/V protocol
+  semantics once those are dedicated modules
+
+## Connector Categories
+
+Initial catalogue categories:
+
+- project management and task systems such as OpenProject
+- DMS/e-file/archive systems
+- file providers such as Nextcloud, Seafile, WebDAV, SMB/NFS, object storage
+- identity providers such as LDAP, Active Directory, OIDC, SAML, OpenDesk IDM
+- groupware such as Open-Xchange mail/calendar
+- ERP, finance, accounting, payment, and cash-register systems
+- public-sector protocols such as FIT-Connect, XTA/OSCI, XRechnung, XOE/V
+- reporting, BI, RSS/API publication, and open-data endpoints
+
+## Core Contracts
+
+The module should integrate through:
+
+- module manifest metadata, route factories, permissions, and migrations
+- a connector catalogue API for listing available connector types
+- a connection profile API with secret references, not plaintext secrets
+- capability declarations such as `connectors.catalog`,
+  `connectors.profileTester`, and `connectors.health`
+- events such as `connector.profile_created`, `connector.test_succeeded`,
+  `connector.test_failed`, and `connector.health_changed`
+- configuration-package fragments for required external systems
+
+Domain modules should ask whether a connector capability exists and request a
+profile/test result through core-mediated capabilities. They must not import
+connector implementation modules directly.
+
+## Reference Journeys
+
+### OpenProject Connector First
+
+1. Operator registers an OpenProject connection profile.
+2. Connector tests API reachability and authentication.
+3. A future project-management decision can use the connector before a native
+   `govoplan-projects` module exists.
+4. Cases/tasks/workflow may link to external project/task references through
+   stable external-reference DTOs.
+
+### Public-Sector Integration Catalogue
+
+1. Operator records which external systems exist in an organization.
+2. GovOPlaN identifies common protocols and missing connectors.
+3. Configuration packages can declare required connector profiles.
+4. Health/status pages show whether required integrations are ready.
+
+### OpenDesk Profile
+
+1. Operator records OpenDesk component profiles for identity, mail, calendar,
+   files/documents, and OpenProject where present.
+2. Connectors shows which components are configured, tested, degraded, or
+   missing.
+3. Domain modules enable optional behavior by checking capabilities through
+   core, not by importing connector or OpenDesk-specific implementation code.
+
+## MVP Slice
+
+The first implementation should provide:
+
+- connector type registry
+- connection profile CRUD with secret references
+- connection test result records
+- WebUI catalogue and profile pages
+- configuration-package fragment support
+- generic external-reference DTOs
+- health summary provider
+
+## Permissions
+
+Candidate scopes:
+
+- `connectors:catalog:read`
+- `connectors:profile:read`
+- `connectors:profile:write`
+- `connectors:profile:test`
+- `connectors:secret:manage`
+- `connectors:admin`
+
+## Data Model Sketch
+
+Candidate tables:
+
+- `connector_types`
+- `connector_profiles`
+- `connector_profile_tests`
+- `connector_health_status`
+- `external_references`
+
+Plaintext credentials must never be stored in connector tables. Use secret
+references and the platform secret contract.
+
+## WebUI
+
+Initial route contributions:
+
+- `/connectors`
+- `/connectors/profiles/:profileId`
+
+The UI should show profile status, last test result, capability labels, required
+configuration-package dependencies, and external-reference search where a
+connector supports it.
+
+## Tests
+
+Minimum tests:
+
+- core starts with connectors installed and no domain modules present
+- profile validation rejects plaintext secret echoing
+- connection tests record success/failure diagnostics without leaking secrets
+- configuration package can require a connector profile
+- domain-module optional behavior can detect connector capabilities without
+  imports
+
+## Open Decisions
+
+- Whether protocol-specific connector modules depend on `govoplan-connectors`
+  or only share kernel contracts.
+- Which connector type should be first after OpenProject.
+- How much polling/webhook scheduling belongs here versus workflow/ops.
+- Whether external-reference indexing should move to search/dataflow later.