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.

Detailed follow-up documents:

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

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.