{"slug":"architecture/SPINE_CONNECTION_POOL_ARCHITECTURE","title":"Spine Connection Pool Architecture","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/SPINE_CONNECTION_POOL_ARCHITECTURE.mdx","bytes":16365,"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## The Problem: Independent Connections\n\n**Without connection pooling:**\n```\nClaude establishes 100 connections\n  ├─ System A, System B, System C, ... (100 systems)\n\nGPT establishes 100 connections  \n  ├─ System A, System B, System C, ... (100 systems)\n\nGroq establishes 100 connections\n  ├─ System A, System B, System C, ... (100 systems)\n\nTOTAL: 300 connections, duplicate overhead, credential management nightmare\n```\n\n## The Solution: Shared Connection Pool via Spine\n\n**With connection pooling (the shared connector pattern):**\n```\nClaude establishes core connection to Spine (1 connection)\n  └─ Gets access to 100 systems through Spine broker\n\nGPT queries Spine for available tools (0 new connections)\n  └─ Uses Claude's connections via Spine proxy\n\nGroq queries Spine for available tools (0 new connections)\n  └─ Uses Claude's connections via Spine proxy\n\nTOTAL: 1 core connection + Spine-mediated indirect access\n```\n\n## Architecture\n\n### Three Tiers\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ AI PROVIDERS (Claude, GPT, Groq)                                 │\n│ • No direct connections needed                                   │\n│ • Query Spine for tools (tool probing)                          │\n│ • Execute through Spine (secure proxy)                          │\n│ • Full access to all connected systems                          │\n└──────────────────────────────────────────────────────────────────┘\n                           ↓\n┌──────────────────────────────────────────────────────────────────┐\n│ SPINE CONNECTION POOL (Connection Broker)                        │\n│ • Manages core connections (who connected to what)              │\n│ • Manages indirect accesses (who can access what)               │\n│ • Handles tool probing requests                                 │\n│ • Proxies secure data access                                    │\n│ • Enforces security policies                                    │\n│ • Maintains audit logs                                          │\n└──────────────────────────────────────────────────────────────────┘\n                           ↓\n┌──────────────────────────────────────────────────────────────────┐\n│ EXTERNAL SYSTEMS (GitHub, Figma, Notion, Supabase, etc.)        │\n│ • Connected by first provider (e.g., Claude)                    │\n│ • Reused by other providers via Spine                           │\n│ • No knowledge of multiple providers                            │\n│ • Only communicates with Spine                                  │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n## Concepts\n\n### 1. Core Connection\n\nA direct connection established by an AI provider to a system. Only created once, then shared.\n\n```typescript\n// Claude establishes core connection\nconst claudeConnector = new AIProviderConnector({\n  provider: 'claude',\n  connectorId: 'claude-main-1',\n  credentialId: 'cred-github-123', // GitHub API token\n  systemId: 'github',\n  spineUrl: 'https://spine.api.com',\n  spineApiKey: 'key-xxx',\n})\n\n// Register core connection to 100 systems\nawait claudeConnector.registerCoreConnection('github', 'cred-github-123')\nawait claudeConnector.registerCoreConnection('figma', 'cred-figma-456')\nawait claudeConnector.registerCoreConnection('notion', 'cred-notion-789')\n// ... 97 more systems\n```\n\n**Spine stores:**\n```typescript\nConnectionPoolEntry {\n  systemId: 'github',\n  connectorId: 'claude-main-1',\n  provider: 'claude',\n  connectedAt: 1699564800000,\n  credentials: {\n    credentialId: 'cred-github-123',\n    encryptionKey: '...' // Never expose raw credential\n  },\n  isActive: true,\n}\n```\n\n### 2. Indirect Access\n\nWhen another provider (GPT, Groq) requests access to a system already connected by Claude.\nNo new connection needed - Spine validates and proxies.\n\n```typescript\n// GPT requests indirect access to GitHub\nconst gptConnector = new AIProviderConnector({\n  provider: 'gpt',\n  connectorId: 'gpt-main-1',\n  // ... same config\n})\n\n// Request indirect access to GitHub (connected by Claude)\nawait gptConnector.requestIndirectAccess(\n  'claude',        // Provider who connected to GitHub\n  'github',        // System ID\n  'read',          // Access level\n  3600             // TTL: 1 hour\n)\n\n// Spine stores:\nIndirectTenantAccess {\n  provider: 'gpt',\n  systemId: 'github',\n  accessLevel: 'read',\n  grantedBy: 'claude-main-1',\n  expiresAt: 1699568400000,\n  permissions: ['read', 'probe']\n}\n```\n\n### 3. Tool Probing\n\nDiscover available tools without direct connections. Queries Spine, which returns tool definitions from connected systems.\n\n```typescript\n// GPT discovers tools in GitHub (via Spine)\nconst tools = await gptConnector.discoverTools({\n  category: 'repository',\n  capability: 'list'\n})\n\n// Spine queries: \"Which tools does GitHub have?\"\n// Returns:\n[\n  {\n    id: 'list-repos',\n    name: 'List Repositories',\n    description: 'List repositories accessible to authenticated user',\n    category: 'repository',\n    capabilities: ['list', 'filter', 'search'],\n    accessLevel: 'read',\n    // ... tool schema\n  },\n  // ... more tools\n]\n```\n\n### 4. Secure Data Access\n\nExecute tools securely through Spine. All requests validated and logged.\n\n```typescript\n// GPT executes tool through Spine\nconst result = await gptConnector.executeTool(\n  'github',           // systemId\n  'list-repos',       // toolId\n  { sort: 'updated' } // input data\n)\n\n// Spine:\n// 1. Validates: Can GPT access GitHub? (check indirect access)\n// 2. Validates: Is 'list-repos' callable? (check permissions)\n// 3. Retrieves: GitHub credential from secure storage\n// 4. Executes: Calls GitHub API with credential\n// 5. Returns: Result to GPT\n// 6. Logs: Request for audit trail\n```\n\n## Flow Diagrams\n\n### Initial Setup (Claude connects to 100 systems)\n\n```\nClaude Connector\n    ↓\nregisterCoreConnection(github, cred-xxx)\n    ↓\nSpine Connection Pool\n    ├─ Store: claude → github (credential ID)\n    ├─ Notify Spine API\n    └─ Return: entry + pool status\n```\n\n### Indirect Access (GPT accesses GitHub without new connection)\n\n```\nGPT Connector\n    ↓\nrequestIndirectAccess('claude', 'github', 'read')\n    ↓\nSpine Connection Pool\n    ├─ Verify: Claude connected to GitHub? YES\n    ├─ Store: gpt → github (read access)\n    ├─ TTL: 1 hour\n    └─ Return: access grant\n```\n\n### Tool Discovery (Groq finds tools without connection)\n\n```\nGroq Connector\n    ↓\ndiscoverTools({ category: 'repository' })\n    ↓\nTool Discovery Service\n    ├─ Get systems Groq can access\n    ├─ For each system:\n    │   └─ Query Spine: listTools(systemId)\n    └─ Return: aggregated tools\n    ↓\nSpine Connection Pool\n    ├─ Check: Groq has indirect access? YES\n    ├─ Query: GitHub tools\n    └─ Return: tool definitions\n```\n\n### Secure Execution (GPT executes tool through Spine)\n\n```\nGPT Connector\n    ↓\nexecuteTool('github', 'list-repos', { sort: 'updated' })\n    ↓\nTool Discovery Service\n    ↓\nSpine Connection Pool\n    ├─ Validate: GPT → GitHub access? (check indirect grant)\n    ├─ Validate: 'list-repos' permissions? (check tool ACL)\n    ├─ Get: GitHub credential (encrypted)\n    ├─ Execute: Call GitHub API\n    ├─ Log: Audit record\n    └─ Return: Result + audit log\n```\n\n## Implementation\n\n### Files Created\n\n**Core Pool Management (459 lines):**\n- `lib/spine/connection-pool.ts`\n  - `SpineConnectionPool` class\n  - Core connection registration\n  - Indirect access granting\n  - Tool probing interface\n  - Secure data access proxy\n\n**Tool Discovery (340 lines):**\n- `lib/spine/tool-discovery.ts`\n  - `ToolDiscoveryService` class\n  - Tool discovery without connections\n  - Access validation\n  - Statistics and monitoring\n\n**AI Provider Adapter (269 lines):**\n- `lib/ai/provider-connector.ts`\n  - `AIProviderConnector` class\n  - Wrapper for Claude, GPT, Groq\n  - Core connection registration\n  - Indirect access requests\n  - Tool execution interface\n\n### Usage Example: Complete Flow\n\n```typescript\n\n// ============ PHASE 1: CLAUDE CONNECTS ============\n\nconst claudeConfig = {\n  provider: 'claude',\n  connectorId: 'claude-1',\n  credentialId: 'claude-key',\n  spineUrl: 'https://spine.api.com',\n  spineApiKey: 'spine-key',\n  systemId: 'integratewise',\n}\n\nconst claudeConnector = createAIProviderConnector(claudeConfig)\n\n// Register core connections to 100 systems\nconst systems = [\n  'github', 'figma', 'notion', 'supabase', 'cloudflare',\n  // ... 95 more\n]\n\nfor (const systemId of systems) {\n  const credentialId = `cred-${systemId}-${Date.now()}`\n  await claudeConnector.registerCoreConnection(systemId, credentialId)\n}\n\nconsole.log('Claude connected to 100 systems via Spine')\n\n// ============ PHASE 2: GPT REQUESTS INDIRECT ACCESS ============\n\nconst gptConfig = {\n  provider: 'gpt',\n  connectorId: 'gpt-1',\n  credentialId: 'gpt-key',\n  spineUrl: 'https://spine.api.com',\n  spineApiKey: 'spine-key',\n  systemId: 'integratewise',\n}\n\nconst gptConnector = createAIProviderConnector(gptConfig)\n\n// Request indirect access to systems Claude connected to\nfor (const systemId of systems) {\n  await gptConnector.requestIndirectAccess('claude', systemId, 'read')\n}\n\nconsole.log('GPT granted indirect access to 100 systems (no new connections)')\n\n// ============ PHASE 3: GROQ REQUESTS INDIRECT ACCESS ============\n\nconst groqConfig = {\n  provider: 'groq',\n  connectorId: 'groq-1',\n  credentialId: 'groq-key',\n  spineUrl: 'https://spine.api.com',\n  spineApiKey: 'spine-key',\n  systemId: 'integratewise',\n}\n\nconst groqConnector = createAIProviderConnector(groqConfig)\n\n// Request indirect access to systems Claude connected to\nfor (const systemId of systems) {\n  await groqConnector.requestIndirectAccess('claude', systemId, 'read')\n}\n\nconsole.log('Groq granted indirect access to 100 systems (no new connections)')\n\n// ============ PHASE 4: ALL PROVIDERS USE SHARED POOL ============\n\n// Claude discovers tools\nconst claudeTools = await claudeConnector.discoverTools({\n  category: 'repository',\n})\n\n// GPT discovers same tools (no new connection!)\nconst gptTools = await gptConnector.discoverTools({\n  category: 'repository',\n})\n\n// Groq discovers same tools (no new connection!)\nconst groqTools = await groqConnector.discoverTools({\n  category: 'repository',\n})\n\n// All providers execute through Spine\nconst claudeRepos = await claudeConnector.executeTool(\n  'github',\n  'list-repos',\n  { sort: 'stars' }\n)\n\nconst gptRepos = await gptConnector.executeTool(\n  'github',\n  'list-repos',\n  { sort: 'updated' }\n)\n\nconst groqRepos = await groqConnector.executeTool(\n  'github',\n  'list-repos',\n  { sort: 'forks' }\n)\n\n// ============ PHASE 5: POOL STATISTICS ============\n\nconst claudeStatus = await claudeConnector.getPoolStatus()\n// {\n//   provider: 'claude',\n//   connectorId: 'claude-1',\n//   connectedSystems: 100,\n//   accessStats: {\n//     provider: 'claude',\n//     accessibleSystems: 100,\n//     accessibleTools: 1250,\n//     permissions: ['read', 'write', 'execute']\n//   }\n// }\n\nconst gptStatus = await gptConnector.getPoolStatus()\n// {\n//   provider: 'gpt',\n//   connectorId: 'gpt-1',\n//   connectedSystems: 100,\n//   accessStats: {\n//     provider: 'gpt',\n//     accessibleSystems: 100,\n//     accessibleTools: 1250,\n//     permissions: ['read']  // Only read access\n//   }\n// }\n```\n\n## Benefits\n\n### Reduced Overhead\n- **Before**: 300 connections (100 × 3 providers)\n- **After**: ~100 connections (1 core + shared access)\n- **Savings**: 66% connection reduction\n\n### Simplified Credential Management\n- Store credentials once in Spine\n- Never expose to client code\n- Encrypt with unique keys per connection\n- Audit all access\n\n### Flexible Access Control\n- Grant different access levels per provider\n- Time-limited indirect access (TTL)\n- Per-system permission scoping\n- Audit trail for compliance\n\n### Provider Independence\n- External systems don't know about multiple providers\n- Claude's connection invisible to GPT/Groq\n- Providers can't leak each other's credentials\n- Data flows through Spine validation\n\n### Efficient Resource Usage\n- Reuse established connections\n- Lazy initialization of indirect access\n- Connection pooling at Spine level\n- Automatic cleanup of expired access\n\n### Security\n- No credentials in client code\n- Encryption keys per connection\n- Access validation on every request\n- Audit logging for compliance\n- Rate limiting at Spine level\n\n## Security Model\n\n### Credential Isolation\n\n```\nSpine Secure Storage:\n┌─ System: GitHub\n│  ├─ Credential: cred-github-123 (encrypted)\n│  ├─ Encryption Key: key-xxx-yyy (isolated)\n│  ├─ Connected By: claude-main-1\n│  └─ Access Grants:\n│     ├─ gpt-main-1: read access, expires 1h\n│     └─ groq-main-1: read access, expires 1h\n\nAccess Request Flow:\n1. GPT: \"I want to call list-repos on GitHub\"\n2. Spine: \"Do you have indirect access?\" YES ✓\n3. Spine: \"Is this tool callable?\" YES ✓\n4. Spine: \"Retrieve credential\" → cred-github-123\n5. Spine: \"Execute with credential\"\n6. Spine: \"Log audit entry\"\n7. Spine: \"Return result to GPT\"\n\nGPT never sees credential ✓\n```\n\n### Access Control Matrix\n\n```\nProvider  | GitHub | Figma | Notion | AWS   | Stripe\n----------|--------|-------|--------|-------|--------\nClaude    | RWE    | RWE   | RWE    | RWE   | RWE\nGPT       | R      | R     | R      | R     | R\nGroq      | R      | R     | R      | R     | R\n```\n\nR = Read, W = Write, E = Execute\n\n## Monitoring\n\n### Pool Statistics\n\n```typescript\n// Get pool status\nconst status = await claudeConnector.getPoolStatus()\n// {\n//   provider: 'claude',\n//   connectorId: 'claude-main-1',\n//   connectedSystems: 100,\n//   accessStats: {\n//     provider: 'claude',\n//     accessibleSystems: 100,\n//     accessibleTools: 1250,\n//     permissions: ['read', 'write', 'execute']\n//   }\n// }\n```\n\n### Audit Logging\n\n```typescript\n// Each access is logged\nSecureDataAccessResponse {\n  success: true,\n  data: { /* result */ },\n  auditLog: {\n    requestId: 'req-123',\n    provider: 'gpt',\n    toolId: 'list-repos',\n    timestamp: 1699568400000,\n    status: 'approved'\n  }\n}\n```\n\n## Deployment\n\n### Environment Variables\n\n```bash\nSPINE_URL=https://spine.api.com\nSPINE_API_KEY=...\nINTEGRATEWISE_SYSTEM_ID=integratewise\n```\n\n### Configuration\n\n```typescript\nconst config = {\n  spineUrl: process.env.SPINE_URL,\n  spineApiKey: process.env.SPINE_API_KEY,\n  systemId: process.env.INTEGRATEWISE_SYSTEM_ID,\n}\n```\n\n## Summary\n\n**Spine Connection Pool** implements the **shared connector pattern**:\n\n✓ One AI provider establishes core connections (100 systems)\n✓ Other providers access via Spine (no new connections)\n✓ Tool discovery via Spine (not direct)\n✓ Secure data access via Spine (proxied, encrypted)\n✓ Audit logging for compliance\n✓ Access control per provider and system\n\n**Result:**\n- 66% reduction in connections\n- Centralized credential management\n- Flexible access control\n- Complete audit trail\n- Production-ready shared pool\n\n---\n\n*Pattern: Shared Connector Pool via Spine*\n*Benefit: One connection to 100 systems shared by 3+ providers*\n*Outcome: Efficient, secure, scalable ecosystem access*\n"}