Add shared GovOPlaN gitignore

.gitignore

@@ -0,0 +1,276 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+node_modules/
+webui/node_modules/
+webui/dist/
+*.tsbuildinfo
+.component-test-build/
+.module-test-build/
+.policy-test-build/
+.template-preview-test-build/
+.import-test-build/
+webui/.component-test-build/
+webui/.module-test-build/
+webui/.policy-test-build/
+webui/.template-preview-test-build/
+webui/.import-test-build/
+
+# GovOPlaN shared ignore rules from govoplan-core
+# ---> Node
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+# nyc test coverage
+.nyc_output
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+# Bower dependency directory (https://bower.io/)
+bower_components
+# node-waf configuration
+.lock-wscript
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+# Dependency directories
+jspm_packages/
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+# TypeScript cache
+# Optional npm cache directory
+.npm
+# Optional eslint cache
+.eslintcache
+# Optional stylelint cache
+.stylelintcache
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+# Optional REPL history
+.node_repl_history
+# Output of 'npm pack'
+*.tgz
+# Yarn Integrity file
+.yarn-integrity
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+# Next.js build output
+.next
+out
+# Nuxt.js build / generate output
+.nuxt
+dist
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+# vuepress build output
+.vuepress/dist
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+# vitepress build output
+**/.vitepress/dist
+# vitepress cache directory
+**/.vitepress/cache
+# Docusaurus cache and generated files
+.docusaurus
+# Serverless directories
+.serverless/
+# FuseBox cache
+.fusebox/
+# DynamoDB Local files
+.dynamodb/
+# TernJS port file
+.tern-port
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+# Local WebUI test/build scratch directories
+# ---> Python
+# Byte-compiled / optimized / DLL files
+*$py.class
+# C extensions
+*.so
+# Distribution / packaging
+.Python
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+.installed.cfg
+*.egg
+MANIFEST
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+cover/
+# Translations
+*.mo
+*.pot
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+# Flask stuff:
+instance/
+.webassets-cache
+# Scrapy stuff:
+.scrapy
+# Sphinx documentation
+docs/_build/
+# PyBuilder
+.pybuilder/
+target/
+# Jupyter Notebook
+.ipynb_checkpoints
+# IPython
+profile_default/
+ipython_config.py
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+# SageMath parsed files
+*.sage.py
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+# Spyder project settings
+.spyderproject
+.spyproject
+# Rope project settings
+.ropeproject
+# mkdocs documentation
+/site
+# mypy
+.dmypy.json
+dmypy.json
+# Pyre type checker
+.pyre/
+# pytype static type analyzer
+.pytype/
+# Cython debug symbols
+cython_debug/
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+# Ruff stuff:
+# PyPI configuration file
+.pypirc
+# ---> VisualStudioCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+# Local History for Visual Studio Code
+.history/
+# Built Visual Studio Code Extensions
+*.vsix
+*.db
+# GovOPlaN local runtime state
+runtime/
+# GovOPlaN WebUI test output

README.md

@@ -0,0 +1,17 @@
+# govoplan-connectors
+
+`govoplan-connectors` will own integration catalogues and generic external
+system connection patterns for GovOPlaN.
+
+The module should make external systems discoverable, testable, and usable
+without taking ownership of their business semantics. Domain-specific modules
+remain responsible for case, file, workflow, payment, mail, identity, document,
+or reporting behavior.
+
+See:
+
+- [Connector concept](docs/CONCEPT.md)
+- [Public-sector integration catalogue](docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md)
+- [Connector source lifecycle](docs/CONNECTOR_SOURCE_LIFECYCLE.md)
+- [OpenProject connector concept](docs/OPENPROJECT_CONNECTOR.md)
+- [OpenDesk integration map](docs/OPENDESK_INTEGRATION_MAP.md)

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.

docs/CONNECTOR_SOURCE_LIFECYCLE.md

@@ -0,0 +1,159 @@
+# Connector Source Lifecycle
+
+GovOPlaN modules should treat external systems as sources with explicit
+lifecycle state. A connector profile can consume records from a source, publish
+records into a source, or do both. The lifecycle below keeps connectors
+predictable and avoids hidden module imports.
+
+## Source Directions
+
+- `consume`: GovOPlaN reads external records, normalizes them, and exposes them
+  to modules as external references, events, or staged imports.
+- `publish`: GovOPlaN creates or updates external records and stores the external
+  identifiers as immutable references.
+- `bidirectional`: GovOPlaN supports both directions with conflict detection and
+  reconciliation rules.
+
+## Source Data Lifecycle
+
+Connector profiles have operational states, while individual external records
+or source datasets move through a data lifecycle:
+
+1. `discovered`
+   A source, record, file, feed item, webhook event, or remote object is known
+   but not yet trusted for domain use.
+2. `connected`
+   GovOPlaN can authenticate and fetch or publish against the source profile.
+3. `imported`
+   Minimal source data has been staged with external id, version/ETag, source
+   timestamp, and provenance.
+4. `validated`
+   Shape, permissions, freshness, and required fields passed connector and
+   domain validation.
+5. `transformed`
+   A dataflow, workflow, or domain module normalized the staged payload into a
+   domain-specific form.
+6. `published`
+   GovOPlaN exposed or wrote an output through API, RSS, report, export, or a
+   downstream connector.
+7. `archived`
+   The source/output is no longer active but remains available under retention,
+   audit, and external-reference rules.
+8. `deprecated`
+   The source/output remains readable for history but must not be used for new
+   workflows.
+
+Every transition must preserve provenance, permissions context, freshness, and
+audit trace. Domain modules may add stricter states, but they should map back to
+this lifecycle when a connector publishes status.
+
+## Lifecycle States
+
+1. `draft`
+   Profile exists but is not used by runtime jobs.
+2. `configured`
+   Required endpoint and credential references are present.
+3. `tested`
+   A health/test run succeeded and recorded non-secret diagnostics.
+4. `active`
+   Runtime jobs may consume or publish data.
+5. `degraded`
+   The connector is active but health checks or recent jobs show failures.
+6. `paused`
+   Operators intentionally stop scheduled connector activity.
+7. `retiring`
+   The connector is being removed from active workflows while references remain
+   readable.
+8. `retired`
+   No new runtime activity is allowed. Historical references remain available.
+
+## State Transition Gates
+
+| Transition | Required Evidence | Blockers |
+| --- | --- | --- |
+| `draft` -> `configured` | endpoint fields are valid, credential references exist, owner/tenant scope is set | plaintext secret in profile payload, unsupported connector type |
+| `configured` -> `tested` | latest profile test succeeded and diagnostics were redacted | failed auth, unreachable endpoint, TLS/policy error |
+| `tested` -> `active` | operator enabled runtime use, required modules/capabilities are present, schedule/webhook is valid | missing module, missing permission, no idempotency strategy for publish jobs |
+| `active` -> `degraded` | health check or job telemetry reports failures | none; this is automatic diagnostic state |
+| `degraded` -> `active` | health/test succeeds or failed jobs are reconciled | unresolved conflict or repeated failure threshold |
+| any running state -> `paused` | operator pause request or maintenance preflight | active critical transaction that cannot be interrupted |
+| `paused` -> `active` | successful re-test when credentials/endpoints changed | failed profile test |
+| any state -> `retiring` | uninstall/disable plan accepted, schedulers/workers stopped | active domain references that require operator decision |
+| `retiring` -> `retired` | non-destructive retirement complete, references remain readable | destructive retirement requested without provider and backup |
+
+## Consume Flow
+
+1. Discover changes through polling, webhook, batch upload, or manual operator
+   action.
+2. Fetch only the minimal remote data required for the declared use case.
+3. Normalize into a connector-owned staging payload.
+4. Validate shape, required fields, and source trust level.
+5. Emit a core-mediated event such as `connector.record_discovered`.
+6. Let domain modules claim or transform staged data through capabilities, not
+   imports.
+7. Store external references with source system, object type, object id, version
+   or ETag, and last-seen timestamp.
+
+## Publish Flow
+
+1. Domain module requests publish through a core-mediated connector capability.
+2. Connector validates profile state, permission, idempotency key, and payload
+   shape.
+3. Connector sends the remote request.
+4. Connector stores the remote id, version/ETag, and response diagnostics.
+5. Connector emits `connector.record_published` or `connector.publish_failed`.
+6. Domain module stores only the external-reference DTO and any domain result.
+
+## Reconciliation
+
+Every connector that writes to an external system needs a reconciliation story:
+
+- idempotency key for create/update jobs
+- remote object version, ETag, or last-modified value where available
+- conflict state when local and remote records diverge
+- retry policy for temporary failures
+- explicit operator action for destructive overwrite or deletion
+- audit trace from GovOPlaN record to external request and response summary
+
+## Capability Boundary
+
+Domain modules must not import connector implementation packages directly. They
+should ask core for capabilities such as:
+
+- `connectors.catalog`
+- `connectors.profileTester`
+- `connectors.health`
+- `connectors.externalReferences`
+- `connectors.sourceConsumer`
+- `connectors.sourcePublisher`
+
+Connector payloads should be DTOs or protocol objects from kernel/core
+contracts. Protocol-specific clients stay inside the connector module that owns
+them.
+
+## Safety Rules
+
+- Secret values never leave the secret contract and are never stored in test
+  result payloads.
+- Runtime jobs must include profile id, connector type, direction, idempotency
+  key, and triggering principal/system actor.
+- Profile tests must redact tokens, passwords, cookies, authorization headers,
+  and remote personal data not needed for diagnostics.
+- Deactivation must stop schedulers/workers before profile removal.
+- Uninstall defaults to non-destructive retirement; domain data and external
+  references remain readable.
+- Destructive retirement requires a module-owned retirement provider and an
+  explicit operator choice.
+
+## Release Checklist
+
+Before shipping an executable connector type:
+
+- Add catalogue metadata and capability names.
+- Add profile schema validation that rejects plaintext secrets.
+- Add redaction tests for success and failure diagnostics.
+- Add unavailable-optional-module tests for every consuming domain module.
+- Add profile test and health status fixtures.
+- Add external-reference DTO tests.
+- Add lifecycle transition tests for pause, retry, retirement, and uninstall
+  guard behavior.

docs/GOVERNED_CONNECTOR_CONFIGURATION.md

@@ -0,0 +1,48 @@
+# Governed Connector Configuration
+
+GovOPlaN connectors should make integration behavior inspectable and testable.
+The target is not hardcoded glue hidden in module code, but governed connector
+definitions with schemas, mappings, test runs, simulation, versioning, and
+audit-visible execution.
+
+## Connector Definition
+
+A connector definition should describe:
+
+- provider type and protocol
+- endpoint and credential requirements
+- supported capabilities
+- input and output schemas
+- mapping and transformation versions
+- validation rules
+- dry-run and test operations
+- privacy and retention classification
+- expected events and audit records
+- operational limits and retry behavior
+
+Provider-specific code may still be required, but the configured integration
+logic should remain visible and reviewable.
+
+## Runtime Expectations
+
+Connectors should support:
+
+- discovery where possible
+- typed configuration through UI-managed controls
+- secret references instead of plaintext secrets
+- dry-run plans before writes
+- simulation with sample payloads
+- provenance for consumed and produced data
+- idempotent external writes where supported
+- quarantine/manual-review state for unsafe or ambiguous results
+
+Configuration packages may install connector definitions, but local overrides
+must be protected from accidental package updates.
+
+## Relationship To Datasources And Dataflow
+
+Recurring extraction and transformation should start as configuration across
+connectors, files, workflow, reporting, and templates. Create dedicated
+datasource or dataflow modules only when repeated source-catalog, lineage,
+mapping, scheduling, or publication contracts clearly outgrow connector
+ownership.

docs/OPENDESK_INTEGRATION_MAP.md

@@ -0,0 +1,71 @@
+# OpenDesk Integration Map
+
+OpenDesk is an integration profile across GovOPlaN modules, not a monolithic
+GovOPlaN module. The profile should let an operator see which OpenDesk
+components are connected, which GovOPlaN module owns each behavior, and which
+optional capabilities are available.
+
+The core boundary decision register is in
+`/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`.
+
+## Component Routing
+
+| OpenDesk area | Example component | GovOPlaN owner | Integration behavior |
+| --- | --- | --- | --- |
+| Identity and directory | OpenDesk IDM, LDAP, AD, OIDC, SAML, SCIM | `govoplan-idm`, `govoplan-access` | integrate, synchronize selected accounts/groups, map principals and memberships |
+| Mail/groupware | Open-Xchange mail | `govoplan-mail` | integrate, link profiles, test mailbox/send/append, keep mail semantics in mail |
+| Calendar/groupware | Open-Xchange calendar, CalDAV/CardDAV | `govoplan-calendar` | integrate, free/busy lookup, selected event sync, resource calendars |
+| Files/documents | Nextcloud/WebDAV/files, office integrations | `govoplan-files`, later `govoplan-dms` | integrate, import/link files, keep document lifecycle in DMS |
+| Project management | OpenProject | `govoplan-connectors`, consumers in tasks/workflow/cases | connector-first, link/synchronize selected work packages |
+| Portal/collaboration | Portal/chat/video/office services where present | `govoplan-portal`, `govoplan-connectors`, `govoplan-dms`, `govoplan-workflow` | link/integrate only when a process needs it |
+| Inventory and diagnostics | endpoint catalogue, profile health, version checks | `govoplan-connectors` | catalogue, profile test, health summary, optional capability discovery |
+
+## Integration Behavior
+
+- `integrate`: call a stable API or protocol for the component.
+- `link`: store external references and open the external tool for
+  source-of-truth work.
+- `import`: bring selected files/records into GovOPlaN-owned storage or
+  evidence.
+- `synchronize`: keep selected records aligned through explicit source-of-truth
+  rules.
+- `replace selected workflow`: only when GovOPlaN owns tighter governance,
+  audit, retention, or configuration-package state than the OpenDesk component.
+
+## Shared Assumptions
+
+- Identity is the first dependency. Mail, calendar, files, and project
+  connectors should record which identity profile or tenant mapping they expect.
+- Connector profiles store references to secrets, never secret values.
+- Module consumers discover optional behavior through core capabilities and
+  module metadata.
+- The profile must work partially: an installation can have OpenProject without
+  Open-Xchange, or calendar without files.
+
+## Candidate Profile Shape
+
+```json
+{
+  "id": "opendesk-main",
+  "display_name": "OpenDesk",
+  "components": {
+    "identity": {"profile_id": "opendesk-idm", "owner": "govoplan-idm"},
+    "mail": {"profile_id": "ox-mail", "owner": "govoplan-mail"},
+    "calendar": {"profile_id": "ox-calendar", "owner": "govoplan-calendar"},
+    "files": {"profile_id": "nextcloud-main", "owner": "govoplan-files"},
+    "projects": {"profile_id": "openproject-main", "owner": "govoplan-connectors"}
+  }
+}
+```
+
+## Follow-Up Implementation Issues
+
+Existing high-priority module issues:
+
+- `govoplan-idm#1`: LDAP, Active Directory, OpenDesk identity services.
+- `govoplan-mail#5`: Open-Xchange mail/groupware adapter boundary.
+- `govoplan-calendar#2`: Open-Xchange calendar adapter boundary.
+- `govoplan-connectors#1`: OpenProject connector.
+
+Future executable connector issues should be created in the owning module
+repository when the first concrete API/profile slice is selected.

docs/OPENPROJECT_CONNECTOR.md

@@ -0,0 +1,170 @@
+# OpenProject Connector Concept
+
+OpenProject is the first proposed concrete connector for
+`govoplan-connectors`. It gives GovOPlaN a public-sector-friendly project and
+work-package integration target without making project management a core
+platform dependency.
+
+## Goals
+
+- Register OpenProject connection profiles.
+- Test API reachability and authentication without exposing secrets.
+- Read projects, users, statuses, and work packages for linking.
+- Create or update work packages from GovOPlaN tasks/cases/workflows once those
+  modules request the capability.
+- Receive or poll changes for external-reference synchronization.
+- Keep all OpenProject-specific client code inside the connector module.
+
+## Non-Goals
+
+- Replacing a future native GovOPlaN project-management module.
+- Importing workflow, tasks, cases, or access implementation modules directly.
+- Mirroring complete OpenProject project state into GovOPlaN by default.
+- Storing OpenProject tokens outside the platform secret contract.
+
+## Profile Fields
+
+Candidate profile payload:
+
+- `base_url`
+- `api_version`, default `v3`
+- `credential_ref`
+- `verify_tls`
+- `timeout_seconds`
+- `allowed_project_ids`
+- `default_project_id`
+- `webhook_secret_ref`, optional
+- `poll_interval_seconds`, optional
+
+## Health Check
+
+The connection test should:
+
+1. Normalize and validate `base_url`.
+2. Resolve the credential reference.
+3. Call the OpenProject API root or a small read-only endpoint.
+4. Record API version, authenticated principal where available, latency,
+   response status, and safe capability hints.
+5. Redact token, Authorization headers, cookies, and any server-provided secret
+   fields from diagnostics.
+
+## Candidate Capabilities
+
+- `connectors.openproject.profileTester`
+- `connectors.openproject.projects`
+- `connectors.openproject.workPackages.read`
+- `connectors.openproject.workPackages.write`
+- `connectors.openproject.webhooks`
+- `connectors.openproject.externalReferences`
+
+Domain modules request these through core-mediated capabilities. For example,
+`govoplan-tasks` can publish a task as an OpenProject work package without
+importing OpenProject client code.
+
+## Data Boundary Decision
+
+OpenProject should be referenced live by default, not mirrored wholesale into
+GovOPlaN. The connector stores stable external references and safe metadata:
+
+- profile id and connector type
+- project id and work-package id
+- external URL
+- remote version, ETag, or lock version where available
+- last-seen timestamp and safe status/type labels
+- GovOPlaN trace id for publish or synchronization jobs
+
+GovOPlaN should import only the subset needed by a requesting domain module,
+for example a work-package title/status for display, a link-back reference for a
+task, or evidence that a publish operation succeeded. Full project state,
+comments, attachments, membership lists, and custom fields remain remote unless
+a future domain module explicitly owns that synchronization. This keeps cases,
+tasks, workflow, and reporting decoupled from OpenProject while still allowing
+link-out, link-back, selected publish, and selected read views.
+
+## Runtime Events
+
+- `openproject.profile_tested`
+- `openproject.project_seen`
+- `openproject.work_package_seen`
+- `openproject.work_package_published`
+- `openproject.webhook_received`
+- `openproject.sync_failed`
+
+Events should carry GovOPlaN ids, external ids, safe diagnostics, and trace
+context. They must not contain credentials or raw personal data beyond what the
+requesting domain module is authorized to process.
+
+## Webhook And Polling Strategy
+
+OpenProject supports API and webhook administration. The connector should allow
+both:
+
+- Webhook-first when an operator registers a webhook for selected project/work
+  package events.
+- Polling fallback for installations where webhooks cannot be exposed.
+
+The first implementation can start with manual test plus read-only project/work
+package lookup, then add publishing, then webhook/polling synchronization.
+
+## First Implementation Slice
+
+1. Add connector type metadata for `openproject`.
+2. Add connection profile CRUD using secret references.
+3. Add a read-only test endpoint.
+4. Add project/work-package lookup DTOs.
+5. Add external-reference storage for linked OpenProject work packages.
+6. Add a WebUI profile page with last-test diagnostics.
+7. Add tests for redaction, unavailable connector behavior, and optional module
+   capability discovery.
+
+## Minimum DTOs
+
+Profile summary:
+
+```json
+{
+  "id": "openproject-main",
+  "connector_type": "openproject",
+  "name": "OpenProject",
+  "base_url": "https://openproject.example",
+  "state": "tested",
+  "last_test_at": "2026-07-09T10:00:00Z",
+  "last_test_status": "success"
+}
+```
+
+External reference:
+
+```json
+{
+  "connector_type": "openproject",
+  "profile_id": "openproject-main",
+  "object_type": "work_package",
+  "external_id": "1234",
+  "external_url": "https://openproject.example/work_packages/1234",
+  "version": "etag-or-lock-version",
+  "metadata": {
+    "project_id": "42"
+  }
+}
+```
+
+Diagnostics must be redacted and should include only endpoint, version,
+authenticated principal label where safe, latency, status code, and capability
+hints.
+
+## First Tests To Add
+
+- profile create/update rejects plaintext token fields
+- profile test redacts Authorization, cookies, and token-like response fields
+- lookup capabilities are absent when the connector module is disabled
+- a task/workflow/case module can detect OpenProject capabilities without
+  importing connector internals
+- external-reference round-trip stores profile id, object type, external id,
+  version/ETag, URL, and safe metadata
+
+## Reference Sources
+
+- OpenProject API v3 documentation: https://www.openproject.org/docs/api/
+- OpenProject API introduction: https://www.openproject.org/docs/api/introduction/
+- OpenProject API and webhooks administration: https://www.openproject.org/docs/system-admin-guide/api-and-webhooks/

docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md

@@ -0,0 +1,156 @@
+# Public-Sector Integration Catalogue
+
+`govoplan-connectors` should maintain an operator-visible catalogue of common
+external systems, protocols, and integration patterns. The catalogue is not a
+promise that GovOPlaN replaces those systems. It is the map that lets modules
+discover what exists, test connections, and decide which optional behavior can
+be enabled.
+
+## Catalogue Entry Shape
+
+Each connector type should define:
+
+- stable connector type key, for example `openproject`, `fit-connect`,
+  `xrepository`, or `sap`
+- category and owning GovOPlaN module, if any
+- supported direction: consume, publish, or bidirectional
+- supported trigger modes: manual test, polling, webhook, batch import, export
+- credential method and whether secrets are stored through the platform secret
+  contract
+- health check and diagnostic payload shape
+- external reference shape for records created or linked through the connector
+- required capabilities and optional module combinations
+- lifecycle support: activate, pause, re-test, rotate credential, retire
+
+## Initial Target Categories
+
+The catalogue should be maintained as a ranked inventory. A target can start as
+an inventory entry before there is executable connector code.
+
+| Target | Scope/Jurisdiction | Category | Mode | Likely Owner | First Useful Capability | Priority |
+| --- | --- | --- | --- | --- | --- | --- |
+| OpenProject | international/open source | Project/task management | link, synchronize selected records, publish tasks | `govoplan-connectors`, later tasks/workflow/projects | profile test, project/work-package lookup, external references | Wave 0 |
+| Nextcloud/WebDAV/SMB/Seafile | broad public-sector/self-hosted | File providers | integrate, import, link | `govoplan-files` with connector inventory | profile health and managed-file provenance | Wave 0/in progress |
+| OpenDesk IDM, LDAP, Active Directory, OIDC, SAML | Germany/EU and general enterprise | Identity | integrate, synchronize | `govoplan-idm`, `govoplan-access` | endpoint inventory, login/provisioning preflight | Wave 1 |
+| Open-Xchange mail/calendar | Germany/OpenDesk and groupware deployments | Groupware | integrate, link | `govoplan-mail`, `govoplan-calendar` | profile test, mailbox/calendar diagnostics | Wave 1 |
+| FIT-Connect | German public-sector transport | Public-sector transport | integrate, publish, receive | dedicated protocol module with connectors inventory | destination profile, test, receipt reference | Wave 1 |
+| XRepository/XÖV lookup | German public-sector standards | Standards registry | link, import schema metadata | `govoplan-connectors`, later XÖV modules | read-only catalogue lookup/cache | Wave 1 |
+| RSS/API publication | public data/external services | Publication/data exchange | consume, publish | `govoplan-connectors`, `govoplan-dataflow` | consume/publish feed profiles | Wave 2 |
+| DMS/e-file/archive systems | German municipal/state/federal administration | DMS/records | link, import, synchronize selected metadata | `govoplan-dms`, `govoplan-files` | external document reference and health | Wave 2 |
+| ERP/finance/procurement/payment systems | German municipal finance/procurement plus EU standards | ERP/payment | export, import, synchronize, replace only by domain decision | dedicated modules | profile inventory and export/import staging | Wave 2 |
+
+### Project And Task Management
+
+- OpenProject
+- Jira or Jira-compatible APIs
+- Redmine
+- Microsoft Planner/Project where available through Microsoft Graph
+
+GovOPlaN should start with OpenProject because it is open source, common in
+public-sector environments, and has API/webhook documentation suitable for a
+first connector.
+
+### DMS, E-File, Records, And Archive
+
+- d.velop/d.3
+- enaio
+- Fabasoft eGov-Suite
+- ELO
+- VIS/eAkte environments
+- CMIS-capable repositories
+- S3/object storage used as archive staging
+
+These targets should usually be owned by DMS/files/records modules once a
+domain module exists. `govoplan-connectors` should still provide inventory,
+profiles, and generic health checks.
+
+### File Providers
+
+- SMB/CIFS
+- WebDAV
+- Nextcloud
+- Seafile
+- S3-compatible object storage
+- SFTP
+
+The files module owns file semantics. The connectors catalogue should record
+profile metadata and health, but must not import files-module internals.
+
+### Identity And Access
+
+- LDAP
+- Active Directory
+- OIDC
+- SAML
+- OpenDesk IDM and comparable identity platforms
+
+The access/IDM modules own principal synchronization and authorization effects.
+Connectors own endpoint inventory and diagnostics.
+
+### Mail, Calendar, And Collaboration
+
+- Microsoft Exchange/M365
+- Open-Xchange
+- IMAP/SMTP where represented as external infrastructure
+- CalDAV/CardDAV
+- chat, video, and collaboration systems such as Matrix, Jitsi, BigBlueButton,
+  Nextcloud Talk, or Collabora/OnlyOffice environments
+
+Mail/calendar/collaboration modules own business semantics. Connector profiles
+can expose reachability and version diagnostics.
+
+### ERP, Finance, Procurement, And Payment
+
+- SAP
+- MACH
+- Infoma/new system
+- DATEV interfaces
+- XRechnung/Peppol access points
+- XBestellung and procurement feeds
+- payment providers and cash-register systems
+
+Protocol-heavy parts should move into dedicated modules such as
+`govoplan-xrechnung`, `govoplan-erp`, `govoplan-procurement`, or
+`govoplan-payments`.
+
+### Public-Sector Protocols And Registries
+
+- FIT-Connect
+- XTA/OSCI
+- XÖV standards and XRepository lookup
+- XRechnung/XBestellung
+- register and Fachverfahren interfaces discovered by implementation projects
+
+These are integration priorities because they model common administrative
+processes. They should be represented as connector categories even when a
+dedicated module later owns the actual protocol implementation.
+
+## Wave 0 Catalogue Priorities
+
+1. OpenProject connector concept and profile shape.
+2. Generic connector profile, health, and secret-reference model.
+3. Public-sector target inventory table with category, owner module, and
+   priority.
+4. Consume/publish source lifecycle contract.
+5. External-reference DTO shared through kernel/core contracts.
+6. Configuration-package declaration for required connector profiles.
+
+## Catalogue Maintenance Rules
+
+- Prefer one stable connector type key per external product or protocol family.
+- Record when GovOPlaN should integrate with an existing product instead of
+  replacing it.
+- Keep protocol/client implementation in the owning connector or protocol
+  module; domain modules consume capabilities and DTOs only.
+- Treat "inventory only" entries as useful: operators can document a landscape
+  before GovOPlaN can automate it.
+- Every executable connector type needs a redaction-safe test plan, lifecycle
+  states, external-reference shape, and uninstall/retirement behavior.
+
+## Reference Sources
+
+- OpenProject API v3 documentation: https://www.openproject.org/docs/api/
+- OpenProject API and webhooks administration: https://www.openproject.org/docs/system-admin-guide/api-and-webhooks/
+- FIT-Connect Destination API documentation: https://docs.fitko.de/en/resources/fit-connect-destination-api/
+- XÖV overview by KoSIT: https://www.xoev.de/xoev-4987
+- XRepository overview: https://www.xrepository.de/