{"slug":"connectors/ONE_CONNECTOR_ARCHITECTURE","title":"One Single Connector Architecture","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/ONE_CONNECTOR_ARCHITECTURE.mdx","bytes":13110,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Vision\n\n**One Single Connector** serving as the unified entry point and central nervous system for the entire IntegrateWise ecosystem. All services, providers, and MCP connections flow through this single connector, connected via the Spine architecture.\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                   ONE SINGLE CONNECTOR                          │\n│                                                                 │\n│  ┌──────────┐  ┌──────────┐  ┌──────┐  ┌─────────┐            │\n│  │   Auth   │  │ Database │  │  AI  │  │  Agent  │            │\n│  │ Service  │  │ Service  │  │Serv. │  │Serv.    │            │\n│  └──────────┘  └──────────┘  └──────┘  └─────────┘            │\n│        │              │           │          │                 │\n│        └──────────────┴───────────┴──────────┘                 │\n│                      │                                          │\n│              (Factory Pattern)                                  │\n│                      │                                          │\n│  ┌─────────────────────────────────────────────────────────┐  │\n│  │              SPINE (Central Nervous System)             │  │\n│  │  • Tenant Management                                    │  │\n│  │  • Connection Lifecycle                                │  │\n│  │  • Heartbeat & Health Monitoring                       │  │\n│  │  • Signal Broadcasting                                 │  │\n│  │  • Knowledge Base                                      │  │\n│  │  • Memory Management                                   │  │\n│  └─────────────────────────────────────────────────────────┘  │\n│                      │                                          │\n│              ┌───────┴───────────────┐                          │\n│              │   MCP POOL            │                          │\n│              │                       │                          │\n│  ┌──────┐┌──────────┐┌───────┐┌────────┐  ┌─────────┐          │\n│  │GitHub││Figma   ││Notion││Supabase│  │Cloudfl. │          │\n│  └──────┘└──────────┘└───────┘└────────┘  └─────────┘          │\n│  ┌────────┐┌──────────┐┌───────────┐┌────────────┐             │\n│  │Slack   ││Stripe   ││Firebase   ││AWS Services│             │\n│  └────────┘└──────────┘└───────────┘└────────────┘             │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Architecture\n\n### Core Components\n\n#### 1. One Connector (lib/connector/index.ts)\n- **Single instance** - Singleton pattern\n- **Central hub** - All services route through here\n- **Lifecycle management** - Connect, disconnect, heartbeat\n- **Health monitoring** - Real-time status tracking\n- **MCP bridge management** - Unified interface to all external services\n\n#### 2. Provider Abstractions (4 layers)\n```typescript\n// All factories return through Connector\nconst auth = connector.getService('auth')      // Supabase or Clerk\nconst db = connector.getService('database')    // PostgreSQL or D1\nconst ai = connector.getService('ai')          // Claude, GPT, or Groq\nconst agent = connector.getService('agent')    // Vercel AI or LangChain\n```\n\n#### 3. Spine Connection\n- Registers connector with Spine\n- Sends periodic heartbeats\n- Reports health status\n- Receives commands/signals\n- Manages tenant context\n\n#### 4. MCP Pool\n- All external services connected via MCP\n- GitHub, Figma, Notion, Supabase, Cloudflare\n- Slack, Stripe, Firebase, AWS, etc.\n- Unified interface for tool access\n\n### Connection Flow\n\n```\nApplication\n    │\n    ├─→ useConnector()              (React hook)\n    │\n    ├─→ getConnector()              (Singleton)\n    │\n    ├─→ connector.getService()      (Get auth/db/ai/agent)\n    │\n    ├─→ Service Factory             (Returns provider instance)\n    │\n    └─→ Provider Implementation     (Actual service)\n         │\n         ├─→ Spine API              (Health, lifecycle)\n         │\n         └─→ MCP Bridges            (External services)\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\n\n// Get connector instance (singleton)\nconst connector = getConnector({\n  tenantId: 'integratewise',\n  clientId: 'app-frontend',\n  environment: 'production',\n  spineUrl: 'https://spine.integratewise.ai',\n  mcpUrl: 'https://mcp.integratewise.ai',\n})\n\n// Connect to Spine and MCP ecosystem\nawait connector.connect()\n```\n\n### In React Components\n\n```typescript\n\n  // Get connector instance\n  const connector = useConnector()\n\n  // Get connector status\n  const { status, isLoading } = useConnectorStatus()\n\n  // Access specific services\n  const auth = connector.getService('auth')\n  const db = connector.getService('database')\n  const ai = connector.getService('ai')\n\n  return (\n    <div>\n      {isLoading ? (\n        <p>Connecting to ecosystem...</p>\n      ) : (\n        <div>\n          <p>Auth: {status?.services.auth.healthy ? '✅' : '❌'}</p>\n          <p>Database: {status?.services.database.healthy ? '✅' : '❌'}</p>\n          <p>AI: {status?.services.ai.healthy ? '✅' : '❌'}</p>\n          <p>Agent: {status?.services.agent.healthy ? '✅' : '❌'}</p>\n          <p>Connected MCP Bridges: {status?.mcpBridges}</p>\n        </div>\n      )}\n    </div>\n  )\n}\n```\n\n### Execute Operations\n\n```typescript\n// Method 1: Direct service access\nconst user = await connector.getService('auth').getCurrentUser()\n\n// Method 2: Execute through connector\nconst user = await connector.execute('auth.getCurrentUser')\n\n// Method 3: In React hook\nconst execute = useConnectorExecute()\nconst result = await execute('database.query', 'SELECT * FROM users')\n```\n\n### Service Access Hooks\n\n```typescript\n// Specific service hooks\nconst auth = useConnectorAuth()\nconst db = useConnectorDatabase()\nconst ai = useConnectorAI()\nconst agent = useConnectorAgent()\n\n// Or generic service hook\nconst service = useConnectorService('auth')\n```\n\n### Lifecycle Management\n\n```typescript\nconst { isConnected, connect, disconnect } = useConnectorLifecycle()\n\n// Connect on mount\nuseEffect(() => {\n  connect()\n  return () => disconnect()\n}, [connect, disconnect])\n```\n\n### MCP Bridge Access\n\n```typescript\n// List connected MCP bridges\nconst bridges = connector.listMCPBridges()\n// Returns: ['integratewise', 'github', 'figma', 'notion', 'supabase', ...]\n\n// Get specific MCP bridge\nconst github = connector.getMCPBridge('github')\n```\n\n## Status Monitoring\n\n### Health Check Structure\n\n```typescript\ninterface ConnectorStatus {\n  healthy: boolean\n  services: {\n    auth: { healthy: boolean; provider: string }\n    database: { healthy: boolean; provider: string }\n    ai: { healthy: boolean; provider: string }\n    agent: { healthy: boolean; provider: string }\n  }\n  mcpBridges: {\n    integratewise: {\n      knowledge: boolean\n      memory: boolean\n      spine: boolean\n      signals: boolean\n      proposals: boolean\n      books: boolean\n    }\n    github: boolean\n    figma: boolean\n    notion: boolean\n    supabase: boolean\n    cloudflare: boolean\n    slack: boolean\n    stripe: boolean\n  }\n  connectedAt: number\n  lastHeartbeat: number\n}\n```\n\n### Heartbeat Mechanism\n\n- **Interval**: 30 seconds\n- **Content**: Full status + timestamp\n- **Destination**: Spine API\n- **Triggered by**: Service health checks\n- **Purpose**: Real-time system monitoring\n\n## Integration with Spine\n\n### Connector Registration\n\n```\nPOST /spine/api/connector\n{\n  tenantId: \"integratewise\",\n  clientId: \"app-frontend\",\n  environment: \"production\",\n  timestamp: 1234567890\n}\n```\n\n### Heartbeat Report\n\n```\nPOST /spine/api/connector/heartbeat\n{\n  tenantId: \"integratewise\",\n  clientId: \"app-frontend\",\n  status: { /* full status object */ },\n  timestamp: 1234567890\n}\n```\n\n### Disconnection\n\n```\nPOST /spine/api/connector/disconnect\n{\n  tenantId: \"integratewise\",\n  clientId: \"app-frontend\",\n  timestamp: 1234567890\n}\n```\n\n## MCP Pool Configuration\n\nAll MCP servers are configured in `mcp-pool.json`:\n\n- **IntegrateWise Platform** (SSE + Stdio)\n  - Knowledge Base, Memory, Spine, Signals, Proposals, Books\n\n- **Development Tools**\n  - GitHub, Figma, Notion, Playwright, VS Code\n\n- **Infrastructure**\n  - Cloudflare (Workers, Pages, D1, KV, R2)\n  - AWS (DynamoDB, S3, SQS, Lambda)\n  - Firebase (Realtime DB, Auth, Cloud Functions)\n\n- **Services**\n  - Supabase (PostgreSQL, Auth)\n  - Stripe (Payments, Subscriptions)\n  - Slack (Chat, Workflows)\n\n- **Knowledge**\n  - AWS Knowledge Base\n  - Cloudflare Docs\n  - Context7 (Extended Memory)\n  - Hugging Face (Models)\n\n## Environment Configuration\n\n```bash\n# Connector Configuration\nINTEGRATEWISE_TENANT_ID=integratewise\nINTEGRATEWISE_CLIENT_ID=app-frontend\nSPINE_URL=https://spine.integratewise.ai\nMCP_URL=https://mcp.integratewise.ai\nSPINE_API_KEY=...\nMCP_TOKEN=...\n\n# Provider Configuration (Auth/DB/AI/Agent)\nNEXT_PUBLIC_AUTH_PROVIDER=clerk\nNEXT_PUBLIC_DB_PROVIDER=d1\nNEXT_PUBLIC_AI_PROVIDER=claude\nNEXT_PUBLIC_AGENT_PROVIDER=vercel-ai\n\n# Provider-Specific Keys\nCLERK_SECRET_KEY=...\nANTHROPIC_API_KEY=...\n# etc.\n```\n\n## Benefits\n\n### Single Entry Point\n- No scattered imports across codebase\n- One place to understand ecosystem\n- Easy to add new services\n\n### Unified Lifecycle\n- Single connect/disconnect\n- Coordinated health checks\n- Synchronized heartbeat\n\n### Provider Agnostic\n- Swap providers via env vars\n- All code works with any provider\n- Factory pattern for clean abstraction\n\n### Comprehensive Monitoring\n- Real-time health status\n- Service availability tracking\n- MCP bridge connectivity\n- Spine integration status\n\n### Type Safe\n- Full TypeScript support\n- Autocompletion for all services\n- Interface definitions for all operations\n\n## File Structure\n\n```\napps/web/lib/connector/\n├── index.ts          (397 lines - OneConnector class)\n├── hooks.ts          (170 lines - React hooks)\n└── __tests__/\n    └── connector.test.ts\n\nONE_CONNECTOR_ARCHITECTURE.md (this file)\n```\n\n## Integration Checklist\n\n- [x] Connector singleton created\n- [x] Service factory integration\n- [x] Spine connection implemented\n- [x] MCP pool bridge initialization\n- [x] Health check mechanism\n- [x] Heartbeat system\n- [x] React hooks for component usage\n- [x] Status monitoring\n- [x] TypeScript type safety\n- [ ] Deployment testing\n- [ ] E2E tests\n- [ ] Production monitoring\n\n## Next Steps\n\n1. **Deploy to production** - Test with real Spine instance\n2. **Add E2E tests** - Verify all 24 provider combinations through connector\n3. **Monitor heartbeats** - Track connector health metrics\n4. **Expand MCP pool** - Add more service integrations\n5. **Implement signal handlers** - Respond to Spine signals\n6. **Add metrics** - Track operation latencies per service\n\n## Summary\n\nThe **One Single Connector** provides:\n\n✅ **Unified interface** to entire ecosystem\n✅ **Central lifecycle** management for all services\n✅ **Type-safe** access to all providers (4 layers)\n✅ **Real-time monitoring** via Spine integration\n✅ **MCP pool access** to 20+ external services\n✅ **React hooks** for seamless component integration\n✅ **Singleton pattern** for efficient resource management\n✅ **Provider agnostic** - switch via environment variables\n\n**Result: One connection. Entire ecosystem. Infinite possibilities.**\n"}