govoplan-connectors/docs/CONCEPT.md

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.

Connector capability is not source ownership. Each configured binding also declares whether GovOPlaN is authoritative, the external system is authoritative, GovOPlaN keeps a mirror, both sides use governed synchronization, GovOPlaN supplies only a governance overlay, or the object is link-only. The same connector may be configured differently by tenant, service, object type, or field group.

Detailed follow-up documents:

• Public-sector integration catalogue
• Connector source lifecycle
• OpenProject connector concept
• OpenDesk integration map

Shared runtime boundary

Connector transports use the versioned Core runtime contract for bounded dry runs and diagnostics. Connectors owns endpoint discovery, authentication hand-off, protocol reads, retry/backoff, and source health. A consuming module owns domain mappings and mutations: Addresses, for example, owns contact and vCard semantics even when Connectors supplies reusable LDAP, CardDAV, Exchange, or Google transport patterns.

Dry runs carry an immutable input hash, source revision and fingerprint, redacted effects, diagnostics, truncation state, and an apply token. Apply must reject a changed input or source revision. URLs and diagnostics never contain credential material; they retain only credential-envelope references.

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
• supported integration maturity, source-authority modes, operation limits, and effect/reconciliation behavior for each connector type

The module does not own:

• governed datasource identity, staging, materializations, frozen states, or consumer read semantics, owned by govoplan-datasources
• 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
• a provider declaration that composes authority mode, maturity, supported operations, revisions/freshness, health, limits, idempotency, conflicts, evidence, and reconciliation behavior
• 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.

Data-oriented consumers use a two-layer path: Connectors publishes a provider-specific datasource origin, then Datasources registers and governs it. Dataflow, Workflow, Reporting, and other consumers use Datasources rather than calling the connector origin 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
• source-authority binding and provider-operation metadata
• 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.