# Public-Sector Integration Strategy

GovOPlaN should integrate with the existing public-sector software landscape
before deciding to replace specialist workflows. This document is the core
strategy index. The executable connector catalogue lives in
`govoplan-connectors/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md`.

## Strategy Labels

Use one or more of these labels for every external system family:

- `integrate`: GovOPlaN talks to the system through a stable API/protocol.
- `link`: GovOPlaN stores external references and opens the external system for
  source-of-truth work.
- `import`: GovOPlaN consumes data or files into governed module storage.
- `synchronize`: GovOPlaN keeps selected records aligned both ways or through a
  source-of-truth rule.
- `replace selected workflow`: GovOPlaN may own a narrow workflow where the
  external product is weak, but does not replace the whole product family.
- `no first-class support`: GovOPlaN only stores manual references unless a
  deployment project creates a specific connector.

## Initial Classification

| System family | Examples | Default strategy | Likely owner |
| --- | --- | --- | --- |
| File providers | SMB/CIFS, WebDAV, Nextcloud, Seafile, SFTP, S3 | integrate, import, link | `govoplan-files`, connector inventory in `govoplan-connectors` |
| Project/task management | OpenProject, Jira, Redmine, Microsoft Planner | link, synchronize selected records, replace selected workflow only after proof | `govoplan-connectors`, later `govoplan-tasks` or workflow modules |
| Identity providers | LDAP, Active Directory, OIDC, SAML, OpenDesk IDM | integrate, synchronize | `govoplan-idm`, `govoplan-access` |
| Mail and groupware | IMAP/SMTP, Open-Xchange, Exchange/M365, CalDAV/CardDAV | integrate, link | `govoplan-mail`, `govoplan-calendar`, `govoplan-connectors` |
| DMS/e-file/archive | d.velop/d.3, enaio, ELO, Fabasoft, CMIS, VIS/eAkte | link, import, synchronize selected metadata | `govoplan-dms`, `govoplan-files`, `govoplan-records` |
| ERP/finance/procurement | SAP, MACH, Infoma, DATEV, procurement feeds | export, import, synchronize; do not replace by default | `govoplan-erp`, `govoplan-procurement`, `govoplan-ledger`, `govoplan-payments` |
| Public-sector transport | FIT-Connect, XTA/OSCI, Peppol access points | integrate, publish, receive | dedicated protocol modules plus `govoplan-connectors` inventory |
| Standards registries | XRepository, XOE/V catalogues | link, import metadata/cache | `govoplan-connectors`, `govoplan-xoev` |
| Publication/data exchange | RSS, open-data APIs, API feeds, CSV/Excel drops | consume, publish, transform | proposed `govoplan-datasources`, proposed `govoplan-dataflow`, `govoplan-reporting` |
| Collaboration suites | Matrix, Jitsi, BigBlueButton, Nextcloud Talk, Collabora/OnlyOffice | integrate, link; native behavior only for governed evidence | `govoplan-connectors`, `govoplan-dms`, `govoplan-workflow` |
| Specialist Fachverfahren | register-specific and domain-specific systems | link first; integrate/import when a real project supplies contracts | domain module or deployment-specific connector |

## Landscape Catalogue

This catalogue is intentionally implementation-oriented. Each entry records the
first API/auth/data assumptions needed to turn an inventory entry into a
connector or module issue.

### Citizen And Service Portals

- Strategy: integrate/link first; replace selected intake workflow only when a
  GovOPlaN portal package owns the complete journey.
- Protocol/API surface: REST/JSON APIs, form submission webhooks, OIDC/SAML
  login, eID interfaces where available, file-upload callbacks, case-status
  callbacks.
- Auth model: OIDC/SAML service clients, signed webhook secrets, tenant-scoped
  API keys, later eID/trust-provider handoff.
- Data shape: applicant identity reference, application form payload,
  attachment references, consent declarations, status events, receipt IDs.
- Deployment assumptions: externally reachable HTTPS, reverse proxy, portal DMZ
  separation, strict CSRF/origin settings, large upload path.
- Risks: personal data exposure, duplicate identity mapping, partial
  submissions, upload malware, inconsistent portal status models.
- MVP test path: submit a test application with one file, create a form
  submission/case/task stub, return a receipt and status reference.
- Owner/priority: `govoplan-portal`, `govoplan-forms-runtime`,
  `govoplan-files`, Wave 1.

### DMS, E-File, Records, And Archives

- Strategy: link/import/synchronize selected metadata; do not replace the DMS by
  default.
- Protocol/API surface: CMIS, WebDAV, vendor REST APIs, S3/object archive
  staging, file-plan export/import, archive handoff APIs.
- Auth model: service accounts, OAuth/OIDC where supported, mTLS for regulated
  archives, secret references for vendor tokens.
- Data shape: document ID, version, file-plan/classification code, retention
  metadata, owner/case reference, external URL, checksum, lock/legal-hold state.
- Deployment assumptions: usually internal network or VPN, strict storage
  quotas, existing retention policies, archive immutability requirements.
- Risks: record duplication, broken legal hold, permission mismatch, version
  drift, destructive retention/export mistakes.
- MVP test path: create a connector inventory entry, test read-only metadata
  lookup, link one GovOPlaN file/case evidence item to an external document.
- Owner/priority: `govoplan-dms`, `govoplan-records`, `govoplan-files`,
  `govoplan-connectors`, Wave 2/5.

### ERP, Finance, Procurement, And Accounting

- Strategy: export/import/synchronize selected records; replacement only by
  narrow domain decision.
- Protocol/API surface: vendor REST/SOAP APIs, CSV/XML batch exchange, SFTP,
  XRechnung/Peppol, XBestellung/procurement feeds, payment reconciliation files.
- Auth model: service accounts, client certificates, mTLS, SFTP keys, token
  references, environment-specific account separation.
- Data shape: debtor/creditor reference, payment request, invoice, order,
  budget/cost-center code, booking status, receipt/evidence reference.
- Deployment assumptions: batch windows, finance-system approval workflows,
  test tenants often separated from production by vendor process.
- Risks: financial posting errors, double export, tax/legal data retention,
  inconsistent master data, irreversible accounting handoff.
- MVP test path: dry-run export of one payment/accounting handoff file with
  checksum, validation report, and no remote posting.
- Owner/priority: `govoplan-payments`, `govoplan-ledger`,
  `govoplan-xrechnung`, `govoplan-erp`, `govoplan-procurement`, Wave 1/6.

### Identity, IAM, And Directory Services

- Strategy: integrate/synchronize; access remains GovOPlaN's local
  authorization boundary.
- Protocol/API surface: LDAP, Active Directory, SCIM, OIDC, SAML, OpenDesk IDM
  APIs, group membership sync, account deactivation feeds.
- Auth model: bind accounts, service clients, OIDC/SAML metadata, SCIM tokens,
  certificate-backed clients where required.
- Data shape: account, user, group, membership, role claim, tenant/org-unit
  mapping, status, external directory ID.
- Deployment assumptions: directory is usually internal; identity provider may
  be organization-wide and not GovOPlaN-owned.
- Risks: privilege escalation through group mapping, stale memberships, account
  collision, deprovisioning latency, tenant-boundary mistakes.
- MVP test path: read-only directory profile test, map one external group to a
  tenant group, show a dry-run membership diff.
- Owner/priority: `govoplan-idm`, `govoplan-access`, Wave 1.

### Groupware, Mail, Calendar, And Collaboration

- Strategy: integrate/link; native behavior only where GovOPlaN needs governed
  evidence or process state.
- Protocol/API surface: IMAP/SMTP, CalDAV/CardDAV, Open-Xchange APIs, Microsoft
  Graph/EWS, Matrix APIs, Jitsi/BigBlueButton APIs, Collabora/OnlyOffice
  integration points.
- Auth model: service accounts, delegated OAuth/OIDC, app passwords, mailbox
  credentials, groupware-specific tokens, secret references.
- Data shape: mailbox folder/message references, event/free-busy data, meeting
  URL, chat room ID, participant list, document-editing session reference.
- Deployment assumptions: often internal/existing tenant infrastructure; mail
  and calendar may be separate from identity even in OpenDesk-style stacks.
- Risks: mail credential exposure, calendar privacy, double invitations, room
  booking conflicts, chat/document data escaping retention rules.
- MVP test path: profile test for mailbox/calendar reachability, read-only
  folder/free-busy lookup, create a non-production event/message draft.
- Owner/priority: `govoplan-mail`, `govoplan-calendar`,
  `govoplan-connectors`, Wave 1/2.

### Payment And Public Cashier Systems

- Strategy: integrate/export/import; keep the payment provider or cashier as
  source of settlement truth.
- Protocol/API surface: payment provider APIs, redirect/callback flows,
  reconciliation files, SEPA/export formats, cash-register/cashier interfaces.
- Auth model: provider API keys, signed webhooks, client certificates, mTLS,
  tenant-specific merchant accounts.
- Data shape: payment intent, amount/currency, payer reference, provider
  transaction ID, settlement status, receipt, refund/cancellation reference.
- Deployment assumptions: public callback URLs, strict environment separation,
  PCI-sensitive providers, finance reconciliation cadence.
- Risks: duplicate charges, callback replay, amount mismatch, refund workflow
  gaps, evidence-retention mistakes.
- MVP test path: sandbox payment intent, signed callback verification, receipt
  evidence link, reconciliation dry-run.
- Owner/priority: `govoplan-payments`, `govoplan-ledger`, Wave 1/6.

### Reporting, BI, Open Data, And Publication

- Strategy: consume/publish/transform; native reporting owns GovOPlaN views, not
  every external BI product.
- Protocol/API surface: SQL read replicas, CSV/Excel export/import, REST APIs,
  RSS/Atom, open-data APIs, SFTP/WebDAV publication targets.
- Auth model: read-only DB users, API tokens, SFTP keys, OAuth clients, public
  anonymous publication profiles where appropriate.
- Data shape: dataset metadata, schema/version, report parameters, generated
  file references, publication URL, freshness/lineage, validation results.
- Deployment assumptions: publication can be public or internal; generated
  datasets need retention and provenance.
- Risks: leaking restricted data, stale publications, schema drift, expensive
  queries, untraceable manual transformations.
- MVP test path: publish one report/export as a governed file plus RSS/Atom
  entry with checksum, timestamp, and permission check.
- Owner/priority: `govoplan-reporting`, `govoplan-connectors`, possible future
  `govoplan-datasources`/`govoplan-dataflow`, Wave 2.

### Public-Sector Protocols And Registries

- Strategy: integrate/publish/receive; protocol modules own protocol semantics.
- Protocol/API surface: FIT-Connect, XTA/OSCI, XRepository, XOE/V, XRechnung,
  XBestellung, Peppol, registry-specific Fachverfahren APIs.
- Auth model: certificates, mTLS, service accounts, destination credentials,
  protocol-specific trust anchors and key rotation.
- Data shape: transport envelope, payload schema/version, destination IDs,
  receipt/acknowledgement, message status, standard-specific metadata.
- Deployment assumptions: regulated trust chains, test/prod endpoint
  separation, formal onboarding, strict logging and retention expectations.
- Risks: invalid schemas, failed delivery receipts, certificate expiry, wrong
  destination routing, protocol version drift.
- MVP test path: validate a sample payload against a schema, test endpoint
  reachability in sandbox, store receipt/evidence reference.
- Owner/priority: `govoplan-fit-connect`, `govoplan-xoev`,
  `govoplan-xrechnung`, `govoplan-xta-osci`, `govoplan-connectors`, Wave 1/2.

### File Providers And Shared Storage

- Strategy: integrate/import/link; files module owns GovOPlaN file semantics.
- Protocol/API surface: SMB/CIFS, WebDAV, Nextcloud, Seafile, SFTP, S3,
  local/object storage profiles.
- Auth model: service accounts, user credentials, app tokens, OAuth where
  supported, secret references, environment variables for deployment-managed
  credentials.
- Data shape: file ID/path, provider object ID, checksum, MIME type, size,
  version/ETag, owner, permission snapshot, imported file reference.
- Deployment assumptions: internal networks, large files, existing shares,
  variable permissions, provider-specific rate limits.
- Risks: permission mismatch, stale imports, overwrites, duplicate files, path
  traversal, storage growth.
- MVP test path: profile test, list folder, import one file into governed
  storage, keep provider reference and checksum.
- Owner/priority: `govoplan-files`, `govoplan-connectors`, Wave 0/1.

### Project, Task, And Case-Adjacent Systems

- Strategy: connector-first for OpenProject/Jira/Redmine; native module only
  when GovOPlaN owns project semantics.
- Protocol/API surface: OpenProject API v3, webhooks, Jira/Redmine REST APIs,
  Microsoft Graph for Planner/Project where applicable.
- Auth model: API tokens, OAuth/OIDC apps, webhook secrets, service accounts.
- Data shape: project ID, work package/task ID, status, assignee reference,
  external URL, version/lock token, publish/sync trace.
- Deployment assumptions: external project tool remains source of truth for
  broad project management; GovOPlaN links selected records.
- Risks: task duplication, bidirectional sync conflicts, permission mismatch,
  over-mirroring comments/attachments.
- MVP test path: OpenProject profile test, project/work-package lookup,
  external-reference round-trip.
- Owner/priority: `govoplan-connectors`, later `govoplan-tasks`/workflow/cases
  consumers, Wave 0/2.

### Specialist Fachverfahren

- Strategy: link first; integrate/import only when a deployment project supplies
  concrete contracts and a domain owner.
- Protocol/API surface: vendor APIs, CSV/XML batch imports, SFTP, database
  views, message queues, protocol-specific transports.
- Auth model: usually service accounts, VPN, mTLS, SFTP keys, or vendor tokens.
- Data shape: domain-specific record IDs, status, applicant/person references,
  file/evidence references, case/status events.
- Deployment assumptions: strongly local/vendor-specific, often no stable test
  API, data model differs by jurisdiction.
- Risks: brittle vendor contracts, legal source-of-truth ambiguity, high
  customization cost, migration expectations.
- MVP test path: inventory entry and manual external-reference link; require a
  project-specific connector issue before automation.
- Owner/priority: domain module or deployment-specific connector, case by case.

## Prioritization Rules

1. Start with connectors that unblock Wave 0 or Wave 1 reference journeys.
2. Prefer open standards and self-hosted/open-source APIs where they are common
   in public-sector deployments.
3. Treat inventory-only entries as useful because operators need a map of their
   software landscape even before automation exists.
4. Keep connector code in the owning connector/protocol module. Domain modules
   consume capabilities, DTOs, external references, and events through core.
5. Every executable connector needs health diagnostics, secret-reference
   handling, lifecycle state, audit events, and retirement behavior.

## Connector Catalogue Handoff

`govoplan-connectors` owns the detailed catalogue entry shape:

- connector type key
- category and owner module
- supported directions and trigger modes
- credential and secret handling
- health check and diagnostics payload
- external-reference shape
- required capabilities and optional module combinations
- lifecycle support

Core should only keep strategy, routing, and cross-module architecture notes.
Connector implementation and public-sector target inventory belong in
`govoplan-connectors`.