Document integration foundation API and security model
epic-external-system-integration-configuration-foundation-task-014 — Write technical documentation covering: database schema with column descriptions, RLS policy matrix (role vs operation), Vault usage contract (how to store/retrieve credentials, what is never persisted), IntegrationTypeRegistry extension guide for adding new integration types, and FieldMappings schema evolution guidelines. Documentation targets backend and integration specialist agents consuming this foundation.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 7 - 84 tasks
Can start after Tier 6 completes
Handles integration between different epics or system components. Requires coordination across multiple development streams.
Implementation Notes
Structure the documentation as four separate Markdown files under `docs/integration-foundation/`: `schema-reference.md`, `security-model.md`, `extending-integration-types.md`, and `field-mappings-evolution.md`. Use Markdown tables for the schema reference and RLS matrix — they render well in GitHub and most documentation tools. For the Vault usage contract, use a numbered list for the lifecycle steps and a clear 'NEVER store' callout block (Markdown `> ⚠️ WARNING:` blockquote). For the IntegrationTypeRegistry extension guide, show a complete before/after diff: the existing registry with two integration types, then the same file after adding a third.
For FieldMappings evolution, reference semantic versioning of the JSONB schema using a `schema_version` field if one exists, or recommend adding one. Keep each file under 300 lines — if longer, split into sub-sections. These docs serve as the primary onboarding material for AI agents implementing tasks in downstream epics (Xledger, Dynamics, Cornerstone integrations), so precision and completeness are more important than brevity.
Testing Requirements
Documentation quality review rather than automated tests. Verification steps: (1) Have a peer developer unfamiliar with this module attempt to add a new integration type following only the extension guide — they should succeed without asking questions; (2) Verify all code examples compile by running `dart analyze` on extracted snippets; (3) Confirm the RLS matrix matches the actual policies applied in task-005 by cross-referencing the migration SQL; (4) Confirm the Vault usage contract accurately reflects the vault client implementation from task-010. No automated test runner required, but documentation accuracy is a merge gate.
Supabase Vault API has limited documentation for Dart/Flutter clients; wrapping it correctly for credential rotation and secret reference management may require significant trial and error, delaying the vault component and blocking all downstream credential-dependent work.
Mitigation & Contingency
Mitigation: Spike the Vault integration in the first sprint using a minimal proof-of-concept (store, retrieve, rotate one secret). Document the API surface before building the full vault client. Identify any missing Dart SDK bindings early.
Contingency: If Supabase Vault is too complex, fall back to Supabase's encrypted column approach (pgcrypto) for credential storage as a temporary measure, with a planned migration path to Vault once the API is understood.
Incorrect RLS policy configuration on organization_integrations could allow org admins of one organization to read or modify another organization's integration credentials, creating a serious data breach and compliance violation.
Mitigation & Contingency
Mitigation: Write integration tests that explicitly attempt cross-org data access using different JWT tokens and assert 0 rows returned. Include RLS policy review in PR checklist. Use Supabase's local development stack for policy validation before deployment.
Contingency: If a breach is discovered post-deployment, immediately revoke all integration credentials, rotate vault secrets, notify affected organizations, and apply emergency RLS patches.
JSONB columns for field_mappings and sync_schedule lack database-level schema enforcement; AI-generated or malformed JSON could silently corrupt integration configurations, causing export failures that are hard to diagnose.
Mitigation & Contingency
Mitigation: Define TypeScript/Dart model classes with strict deserialization and validation. Add database check constraints or triggers that validate JSONB structure at write time. Version the JSONB schema to enable forward-compatible migrations.
Contingency: Build a repair script that scans organization_integrations for invalid JSONB and resets corrupted records to a safe default state, alerting the admin of the affected organization.