govoplan-connectors/README.md

# govoplan-connectors

<!-- govoplan-repository-type:start -->
**Repository type:** connector (connector-hub).
<!-- govoplan-repository-type:end -->

`govoplan-connectors` owns 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.

## Executable First Slice

The executable connector capability provides tenant-isolated tabular origins.
Operators can import bounded JSON or CSV snapshots, bind an exact managed Files
CSV/XLSX version, or discover a table through an active governed PostgreSQL
configuration. Every origin exposes a reviewed schema, opaque reference, and
content/discovery fingerprint through `connectors.datasource_origins@0.1.0`.
Preview reads enforce provider ceilings for rows, serialized bytes, and elapsed
time and report the effective limits and any truncation as structured
diagnostics.

Connectors owns acquisition, connection profiles, credentials, discovery, and
provider health. `govoplan-datasources` registers an origin as a governed live
or cached datasource and owns staging, materializations, frozen states, and
consumer access. Dataflow consumes that Datasources contract and never imports
connector implementations or stores connector credentials.

Each origin declares whether it is live, cached, file-backed, or static, its
structured health state, and which projection, filter, aggregation, sorting,
and pagination operations it can push down. The snapshot, managed-file, and
PostgreSQL providers currently support projection and pagination only;
consumers must keep other operations in Dataflow rather than assuming
transport-side execution.

Managed-file sources are authorized and opened through
`files.tabular_content@1.0.0`; Files remains authoritative for ownership,
shares, download permission, exact versions, integrity, quarantine, encryption,
retention, and legal holds. CSV must be UTF-8. XLSX input is protected by
compressed-entry, expanded-byte, compression-ratio, row, and column limits.
A newer current version is reported but never silently replaces the pinned
version.

The PostgreSQL adapter accepts only an active governed connector configuration
whose secret-free endpoint uses the PostgreSQL driver. Authentication is
resolved from a tenant/scope/module/server-restricted Core credential envelope.
The adapter reflects a simple schema/table identifier, uses read-only
transactions and a statement timeout, and blocks configuration, credential, or
schema drift until an operator refreshes and reviews the source. Secrets are
never copied into source metadata or diagnostics. Other database, REST/HTTP,
directory, and warehouse providers can implement the same origin contract
without changing Datasources or Dataflow.

Governed sanctions and feed snapshot acquisitions use Core recovery operations.
The source revision/cursor, redacted dry-run decision, canonical request digest,
and distributed lease are durable before network I/O. Immutable snapshot rows
and the terminal recovery checkpoint commit atomically, and an
`Idempotency-Key` replays the committed result without contacting the provider.
Most acquisition transports are read-only. The MediaWiki/BlueSpice knowledge
adapter is the first governed publication path: it requires an expected remote
revision, a stable idempotency key, a scoped credential envelope, and durable
forward-recovery evidence. A timeout after dispatch becomes outcome-unknown and
blocks replay until the provider revision has been reconciled.

The knowledge adapter discovers MediaWiki or BlueSpice product/version and
capabilities, maps namespaces, pages, revisions, users, categories, links,
files, discussions, redirects, and permissions into identity-stable connector
snapshots, and consumes bounded full or recent-change deltas. Optional Search
integration indexes active pages and rechecks current profile state and ACLs on
every result. Migration into native Wiki is preview-only: conflicts, attachment
collisions, unsupported macros, truncation, and source fingerprints are
reported before a target-side write is considered.

The Znuny/OTRS-compatible service-desk adapter uses deployment-defined
GenericInterface REST routes. It supports identity-only links, bounded snapshot
imports, and ongoing synchronization with explicit authority, queue, ACL, and
dynamic-field mappings. Stable tickets, articles, and attachment references are
preserved with mapping-loss diagnostics; attachment bytes remain provider-side.
Optional Search integration rechecks the current profile, tenant, scope, and ACL
for every result. Revision-checked external updates are limited to governed-sync
profiles and use durable recovery evidence. Tickets, Helpdesk, and Cases remain
authoritative for their own business records and conversion workflows.

RSS and Atom emission is a bounded renderer, not an authority shortcut. Every
selected entry declares whether it came from a GovOPlaN event, publication,
case, or report and carries an opaque owning-module reference and optional
revision. Public-feed permission can render only public entries. Tenant and
private audiences require a separate restricted-feed permission, and the API
derives the allowed visibility set from that audience instead of accepting a
caller-controlled allow-list. Portal or Reporting remains responsible for any
durable public or authenticated route and must re-authorize restricted access.

The governed connector runtime adds immutable definition revisions,
revision-pinned tenant configurations, protected local overrides, explicit
package-update adoption, bounded dry-runs and simulations, redacted provenance,
idempotency, and configurable ambiguity handling through review, quarantine,
or rejection. Its administration surface is contributed to the shared system
administration workspace. Provider-specific adapters still own live writes.

Development:

```bash
/mnt/DATA/git/govoplan/.venv/bin/python -m pip install -e .
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
```

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)
- [Governed connector configuration](docs/GOVERNED_CONNECTOR_CONFIGURATION.md)
- [MediaWiki and BlueSpice connector](docs/MEDIAWIKI_BLUESPICE_CONNECTOR.md)
- [Znuny and OTRS-compatible service-desk connector](docs/ZNUNY_OTRS_CONNECTOR.md)

## Git-source WebUI package

The repository root exposes `@govoplan/connectors-webui` for Git-tagged release
dependencies. It mirrors the owning `webui/package.json` version, public
TypeScript/CSS exports and peer requirements, with entry paths under
`webui/src`. Consumers provide the shared Core/React peers; the facade runs no
development or install scripts. The source archive contains `webui/src`, this
README and any repository license file. Run module development checks from `webui/`; Python
installation remains governed by `pyproject.toml`.

Das Repository stellt `@govoplan/connectors-webui` am Wurzelpfad für versionierte
Git-Abhängigkeiten bereit. Version, öffentliche TypeScript-/CSS-Exporte und
Peer-Anforderungen entsprechen `webui/package.json`; die Einstiegspfade liegen
unter `webui/src`. Gemeinsame Core-/React-Peers stellt die einbindende Anwendung
bereit. Die Fassade führt keine Entwicklungs- oder Installationsskripte aus.
Entwicklungsprüfungen bleiben in `webui/`, die Python-Installation weiterhin in
`pyproject.toml` definiert.