govoplan-files/docs/CONNECTOR_BOUNDARY.md

File Connector Boundary

GovOPlaN Files owns the managed-file boundary: frozen blobs, versions, shares, campaign attachment evidence, provenance, connector policy, connector profiles, and read-only browse/import APIs that turn external files into managed GovOPlaN files.

The built-in connector layer is intentionally on-demand. It does not run remote indexing, background sync, remote mutation, or upstream permission management. Connectors may browse an external source, import one selected file, freeze it as a managed file, record provenance, and audit the access.

Built-In Baseline

The files module may keep small baseline providers when they are needed for normal product workflows and can share the same governance model:

• Seafile through the native read/download API
• Nextcloud through WebDAV
• generic WebDAV
• SMB through the optional smb extra

These providers are surfaced through connector descriptors at GET /api/v1/files/connectors/providers. Provider descriptors declare whether the provider is implemented, whether its optional dependency is installed, and which browse/import behaviors are available.

Separate Connector Module Candidates

A separate connector module becomes appropriate when integration needs exceed on-demand browse/import:

• background indexing or synchronization
• bidirectional remote mutation
• long-running transfer workers
• provider-specific credential lifecycle or OAuth flows
• DMS/eAkte metadata models, registers, retention, or filing plans
• S3-compatible object store administration
• NFS host-mount lifecycle or sidecar coordination
• provider-specific WebUI administration beyond profile fields

In that model, govoplan-files should keep the managed-file import contract, policy checks, provenance model, and audit events. A connector module should own provider-specific discovery, synchronization, credentials, health checks, and any remote write behavior.

Provider Responsibilities

Every provider must:

• enforce GovOPlaN profile visibility and connector policy before browse/import
• keep credentials as environment variables or secret references, never API response values
• import external files into managed storage before they are used in campaigns or workflows
• preserve source provenance and revision metadata
• emit connector audit events for imported or accessed files
• treat remote ACLs as upstream checks, not as a replacement for GovOPlaN policy

Non-Goals For Files

Files does not own collaborative editing, comments, document review workflows, remote lock orchestration, DMS records management, or external system data models. Those belong to future document, workflow, DMS, or connector modules and should integrate through capabilities and managed-file imports.