{"slug":"connectors/CONNECTOR_CONSTITUTION","title":"Connector Constitution","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/CONNECTOR_CONSTITUTION.mdx","bytes":2054,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nStatus: SUPERSEDED / ABSORBED — historical subsystem constitution. Current authority: [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2.\nScope: Provider adapter contracts, auth, sync, health, mapping, fallback, and lifecycle.\nCanonical Owner: IntegrateWise Platform\nLast Verified: 2026-07-20\n\n---\n\n## 1. Purpose\n\nThis document defines how IntegrateWise connects to external applications.\n\nExternal applications are execution providers. They are not workspaces.\n\n---\n\n## 2. Contract\n\n```typescript\ninterface ConnectorContract {\n  id: ConnectorId;\n  name: string;\n  category: ConnectorCategory;\n  auth: { type: \"oauth2\" | \"apikey\" | \"mcp\" | \"direct\"; scopes: string[]; refreshPolicy: string };\n  capabilities: {\n    provided: CapabilityId[];\n    read: EntityType[];\n    write: EntityType[];\n    sync: SyncMode;\n  };\n  health: {\n    checkInterval: number;\n    timeout: number;\n    retryPolicy: RetryPolicy;\n    circuitBreaker: boolean;\n  };\n  mapping: { entities: EntityMapping[]; fields: FieldMapping[]; transforms: Transform[] };\n}\n```\n\n---\n\n## 3. Communication Hierarchy\n\n1. In-process function call\n2. Repository access — D1/KV/R2/DO\n3. Service binding — same-account Worker\n4. Queue — async propagation\n5. External HTTP — browser/SaaS boundary only\n\nWorker-to-Worker HTTP on the same account is an anti-pattern.\n\n---\n\n## 4. Sync Rules\n\n- Sync runs after Spine commit.\n- Sync failures do not invalidate successful execution.\n- Sync status is surfaced explicitly in UI.\n- Retry uses exponential backoff with circuit breaker.\n\n---\n\n## 5. Fallback Rules\n\n- UI fails open with realistic data when connectors are unavailable.\n- UI never surfaces raw provider errors as product state.\n- Marketplace catalog remains loadable without Nango.\n\n---\n\n## 6. Invariants\n\n1. The UI never depends on external application UIs.\n2. The UI never imports provider SDKs directly.\n3. Authoritative field mapping lives in the connector contract, not in views.\n4. Connector health is observable, retryable, and auditable.\n"}