chore: consolidate platform split checks

docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md

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