{"slug":"architecture/CONNECTIVITY","title":"Connectivity","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/CONNECTIVITY.mdx","bytes":3566,"description":"How SpineWorkspace connects to external systems — connector contracts, sync, communication hierarchy, and fallback rules.","updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nConnectivity is how SpineWorkspace connects to external systems. External applications are execution providers. They are not workspaces.\n\n## Connector Contract\n\nEvery connector defines:\n\n```typescript\ninterface ConnectorContract {\n  id: ConnectorId;\n  name: string;\n  category: ConnectorCategory;\n  auth: {\n    type: \"oauth2\" | \"apikey\" | \"mcp\" | \"direct\";\n    scopes: string[];\n    refreshPolicy: string;\n  };\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: {\n    entities: EntityMapping[];\n    fields: FieldMapping[];\n    transforms: Transform[];\n  };\n}\n```\n\n## Communication Hierarchy\n\nExecution follows a strict communication hierarchy:\n\n| Priority | Method | Scope |\n|----------|--------|-------|\n| 1 | In-process function call | Same Worker |\n| 2 | Repository access | D1/KV/R2/DO |\n| 3 | Service binding | Same-account Worker |\n| 4 | Queue | Async propagation |\n| 5 | External HTTP | Browser/SaaS boundary only |\n\n**Rule:** Worker-to-Worker HTTP on the same account is an anti-pattern.\n\n## 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## 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 external dependencies\n\n## 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\n## Connector Lifecycle\n\n```text\nDISCOVER → VALIDATE → INSTALL → AUTHORIZE → REGISTER → GOVERN → EXECUTE\n```\n\n| Phase | Description |\n|-------|-------------|\n| **Discover** | Find connector in marketplace |\n| **Validate** | Verify compatibility and requirements |\n| **Install** | Add connector to tenant |\n| **Authorize** | Grant OAuth/API access |\n| **Register** | Register capabilities in registry |\n| **Govern** | Apply policies to connector usage |\n| **Execute** | Use connector for operations |\n\n## Three Marketplaces\n\n| Marketplace | Purpose |\n|-------------|---------|\n| **Integration Marketplace** | External system connectors |\n| **Plugin Marketplace** | Workbench extensions |\n| **MCP Marketplace** | AI tool capabilities |\n\n**Rules:**\n- Marketplace is capability discovery/distribution\n- Marketplace is not canonical truth\n- Plugin installed ≠ permission\n- MCP available ≠ authority\n\n## Communication Bridge\n\nThe Communication Bridge preserves:\n\n- Tenant identity\n- Work context\n- Purpose and provenance\n- Correlation and authority\n\nThe Bridge is NOT:\n- Canonical memory\n- Authority\n- A replacement database\n- An unrestricted agent bus\n\n## Related\n\n- [Capability Fabric](/architecture/CAPABILITY_FABRIC) — what connectors enable\n- [Execution Fabric](/architecture/EXECUTION_FABRIC) — how connectors are used\n- [Spine Schema](/architecture/SPINE_SCHEMA) — what connectors produce\n- [Reconciliation](/architecture/RECONCILIATION) — how connector results are verified\n"}