{"slug":"strategy/product-strategy/TWO_LAYER_CONNECTION_MODEL","title":"Two-Layer Connection Model: The Complete GTM Motion","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/TWO_LAYER_CONNECTION_MODEL.mdx","bytes":14714,"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## Overview\n\nIntegrateWise operates on a **two-layer connection model**:\n\n1. **Identity Layer** - AI Client ↔ IntegrateWise (user identity)\n2. **Connectivity Layer** - IntegrateWise ↔ Customer Systems (system credentials)\n\nThis creates a **multiplicative effect**: One AI client connected to IntegrateWise automatically gets access to ALL systems IntegrateWise is connected to.\n\n---\n\n## Layer 1: Identity (AI Client → IntegrateWise)\n\n### What Happens\nUser clicks IntegrateWise in marketplace app (Claude, ChatGPT, Perplexity, Replit, Lovable):\n\n```\nStep 1: Marketplace App\n  User: \"Click IntegrateWise\"\n  → Redirects to: https://integratewise.com/auth/authorize?app=claude&redirect_uri=...\n\nStep 2: Identity Creation\n  User enters: email@company.com + organization_name\n  → Backend creates:\n     • Tenant (if new)\n     • User record\n     • OAuth token for this specific AI client\n  → Issues JWT token\n\nStep 3: Return to Marketplace\n  → Redirects back: claude-extension://callback?token=eyJhbGc...\n  → Claude stores token locally\n  → MCP client now has authentication\n\nStep 4: AI Client Ready\n  → Claude can now make MPC calls\n  → All calls include: Authorization: Bearer {JWT}\n```\n\n**Result**: IntegrateWise knows which user/tenant is using Claude. Claude has a persistent identity in IntegrateWise.\n\n---\n\n## Layer 2: Connectivity (IntegrateWise ↔ Customer Systems)\n\n### What Happens\nMeanwhile, the company's admin has already connected customer systems to IntegrateWise:\n\n```\nStep 1: Admin Connects HubSpot\n  Admin: \"Connect HubSpot\"\n  → Redirects to HubSpot OAuth\n  → User authorizes\n  → IntegrateWise receives HubSpot OAuth token\n  → Creates \"Connectivity\" record: tenant_id=X → hubspot_token=abc123\n\nStep 2: Admin Connects Salesforce\n  Admin: \"Connect Salesforce\"\n  → Same flow\n  → IntegrateWise receives Salesforce OAuth token\n  → Creates \"Connectivity\" record: tenant_id=X → salesforce_token=def456\n\nStep 3: Admin Connects Stripe\n  Admin: \"Connect Stripe\"\n  → Same flow\n  → IntegrateWise receives Stripe OAuth token\n  → Creates \"Connectivity\" record: tenant_id=X → stripe_token=ghi789\n\nStep 4: Admin Connects 7 More Systems\n  → Zendesk, Slack, GitHub, Jira, Google Workspace, Microsoft 365, Notion\n  → Each creates a \"Connectivity\" record\n  → Total: 10 systems connected to IntegrateWise for this tenant\n```\n\n**Result**: IntegrateWise has credentials for 10 customer systems. IntegrateWise can query/write to all of them on behalf of the tenant.\n\n---\n\n## The Multiplicative Effect\n\n### Scenario\n\n**Company A**:\n- Has Claude connected (Layer 1: Identity)\n- Has HubSpot, Salesforce, Stripe connected (Layer 2: Connectivity)\n\nWhen Claude user asks: \"Show me top 5 deals\"\n\n```\nClaude (in MPC): GET /api/v1/spine/opportunities?limit=5\n\nIntegrateWise receives:\n  • JWT token: identifies tenant=CompanyA, user=alice@companyA.com\n  • Request: opportunities (deals)\n\nIntegrateWise logic:\n  1. Validate JWT → Tenant=CompanyA\n  2. Look up Connectivity records for CompanyA\n     → Found: HubSpot, Salesforce, Stripe\n  3. Query Spine → Opportunities table\n  4. Spin hydrates from:\n     → Salesforce (deals/opportunities)\n     → HubSpot (deals)\n     → Stripe (subscriptions → opportunities)\n  5. Return merged + normalized data to Claude\n\nClaude displays: Top 5 deals\n```\n\n---\n\n## The Power: Multi-Client Cascade\n\n### Scenario: Company B has 3 AI Clients Connected\n\n**Layer 1 (Identity)**: 3 different AI clients, same tenant\n- Claude Desktop connected (alice@companyB.com)\n- ChatGPT connected (alice@companyB.com)\n- Perplexity connected (alice@companyB.com)\n\n**Layer 2 (Connectivity)**: 10 systems connected\n- HubSpot, Salesforce, Stripe, Zendesk, Slack, GitHub, Jira, Google Workspace, Microsoft 365, Notion\n\n**Result**: Each AI client can independently query all 10 systems\n\n```\nClaude asks: \"What's our revenue this month?\"\n  → Queries Stripe (payment data)\n  → Returns: $500k\n\nChatGPT asks: \"Which deals are closing this week?\"\n  → Queries Salesforce (opportunity data)\n  → Returns: 3 deals worth $2M\n\nPerplexity asks: \"Who is at risk of churning?\"\n  → Queries Zendesk + Stripe + HubSpot (support + churn signals)\n  → Returns: 5 accounts at risk\n\nAll 3 AI clients see the SAME Spine data.\nAll 3 AI clients have access to ALL 10 systems.\n```\n\n---\n\n## The Connection Flow: Step-by-Step\n\n### For First-Time User (Identity Layer)\n\n```\n1. User opens Claude Desktop\n2. Searches for \"IntegrateWise\"\n3. Clicks \"Connect IntegrateWise\"\n4. Redirected to: https://integratewise.com/auth/authorize?app=claude&redirect_uri=claude-extension://callback\n5. User enters:\n   - Email: alice@company.com\n   - Organization: Acme Corp\n6. User clicks \"Authorize\"\n7. Backend creates:\n   - Tenant(\"Acme Corp\") if new\n   - User(\"alice@company.com\", tenant_id=X)\n   - Creates OAuth token\n8. Issues JWT: eyJhbGc...\n9. Redirects back: claude-extension://callback?token=eyJhbGc...\n10. Claude stores token\n11. All future MPC calls include token\n```\n\n**Time**: 2 minutes\n**Result**: Claude can make authenticated calls to IntegrateWise\n\n---\n\n### For Admin Connecting Systems (Connectivity Layer)\n\n```\n1. Admin goes to IntegrateWise dashboard (e.g., CloudFlare Pages frontend)\n2. Clicks \"Connect Salesforce\"\n3. Redirected to Salesforce OAuth\n4. Admin authorizes\n5. Salesforce redirects back with auth code\n6. Backend exchanges auth code for Salesforce token\n7. Backend stores: Connectivity(tenant_id=X, system=\"salesforce\", token=abc123)\n8. Dashboard shows: \"Salesforce ✓ Connected\"\n9. Admin repeats for HubSpot, Stripe, etc.\n```\n\n**Time**: 5 minutes per system (10 systems = 50 minutes)\n**Result**: IntegrateWise has credentials for 10 systems\n\n---\n\n## The Data Flow: End-to-End\n\n### Example: Claude Asking \"What's Our Cash Position?\"\n\n```\n1. Claude (on user's laptop):\n   MPC Call: GET /api/v1/spine/metrics/cash_position\n   Headers: Authorization: Bearer {JWT_token}\n\n2. IntegrateWise Gateway (Cloudflare Worker):\n   • Validates JWT\n   • Identifies: tenant=\"Acme Corp\", user=\"alice@company.com\"\n   • Applies tenant_id filter automatically\n\n3. Spine Query Service:\n   Query: SELECT * FROM metrics WHERE tenant_id=X AND metric=\"cash_position\"\n   \n4. Normalizer:\n   \"cash_position\" metric depends on:\n   • stripe_mrr (Monthly Recurring Revenue from Stripe)\n   • bank_balance (from Bank API if connected)\n   • payroll_run (from Gusto if connected)\n   \n5. Hydration:\n   • Looks up Connectivity records: tenant=X\n   • Finds: Stripe connected, Bank API connected, Gusto connected\n   • Fetches:\n     - Stripe: SELECT SUM(amount) FROM subscriptions\n       → $500k MRR\n     - Bank: GET /balance\n       → $2M cash on hand\n     - Gusto: GET /payroll_forecasted\n       → $500k next 30 days\n\n6. Calculation:\n   cash_position = $2M (on hand) + $500k (MRR) - $500k (payroll)\n                 = $2M runway\n\n7. Return to Claude:\n   { cash_position: 2000000, breakdown: {...}, currency: \"USD\" }\n\n8. Claude (on user's laptop):\n   Displays: \"Your cash position is $2M\"\n```\n\n**Key Insight**: Claude doesn't need to know about Stripe, Bank API, or Gusto. Claude just asks Spine. IntegrateWise figures out where to get the data.\n\n---\n\n## Architecture: Three Layers\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ LAYER 1: IDENTITY (AI Clients)                              │\n├─────────────────────────────────────────────────────────────┤\n│ Claude Desktop  │ ChatGPT  │ Perplexity  │ Replit  │ Lovable│\n│                                                              │\n│ Each has:                                                   │\n│ • JWT token (tenant + user scoped)                         │\n│ • MPC client                                               │\n│ • OAuth app configuration                                 │\n│ • Redirect URI whitelisted                                │\n└──────────────────────────┬──────────────────────────────────┘\n                           │\n                    OAuth Endpoint\n              (CONTINUITY_BRIDGE_SIMPLE.md)\n                           │\n┌──────────────────────────┴──────────────────────────────────┐\n│ LAYER 2: GATEWAY (Identity Validation)                     │\n├─────────────────────────────────────────────────────────────┤\n│ JWT Validator Middleware                                   │\n│ • Validates token signature                                │\n│ • Extracts tenant_id + user_id                             │\n│ • Applies automatic tenant scoping                         │\n│ • Forwards to service                                      │\n└──────────────────────────┬──────────────────────────────────┘\n                           │\n┌──────────────────────────┴──────────────────────────────────┐\n│ LAYER 3: CONNECTIVITY (Customer Systems)                   │\n├─────────────────────────────────────────────────────────────┤\n│ Spine (Tenant-Scoped Data)                                │\n│                           │                                │\n│    ┌─────────────────────┼─────────────────────┐          │\n│    ▼                      ▼                      ▼          │\n│ HubSpot              Salesforce              Stripe         │\n│ (credentials)       (credentials)         (credentials)    │\n│ Connected via       Connected via          Connected via   │\n│ OAuth token         OAuth token            OAuth token     │\n│                                                             │\n│ Result: All data queried, normalized, merged into Spine   │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Key Points\n\n### 1. Identity is User + Tenant Scoped\n```\nJWT payload:\n{\n  \"tenant_id\": \"acme-corp-123\",\n  \"user_id\": \"alice@company.com\",\n  \"app\": \"claude\",\n  \"exp\": 1719432000\n}\n```\n\nEvery API call filtered automatically by tenant_id.\n\n### 2. Connectivity is Admin Configured\nAdmin connects HubSpot, Salesforce, Stripe once per company.\nAll users in that company can query those systems (if they have permission).\n\n### 3. Multiplicative Effect\n- 1 AI client × 10 connected systems = 10 data sources\n- 5 AI clients × 10 connected systems = 50 combinations, but same Spine\n- 5 AI clients × 28 connectors = 140 combinations, same Spine\n\n### 4. Data Freshness\n- Real-time queries (Stripe balance, Salesforce opportunities)\n- Cached queries (company history, metrics)\n- Mixed: Some from cache, some real-time\n\n### 5. Failure Isolation\n- If Stripe is down, Spine still returns HubSpot + Salesforce data\n- If HubSpot is down, Spine still returns Salesforce + Stripe data\n- Users see partial data, not errors\n\n---\n\n## Deployment Checklist\n\n### Identity Layer (Day 1)\n- [ ] OAuth endpoint deployed (CONTINUITY_BRIDGE_SIMPLE.md)\n- [ ] JWT generation working\n- [ ] All 5 marketplace apps configured\n- [ ] Redirect URIs whitelisted\n- [ ] Manual OAuth flow tested\n\n### Gateway Layer (Day 1)\n- [ ] JWT validator middleware added\n- [ ] Feature gate middleware added\n- [ ] Tenant scoping automatic on all queries\n- [ ] No data leakage between tenants\n\n### Connectivity Layer (Day 2)\n- [ ] Connector handlers updated to store OAuth tokens\n- [ ] Connectivity records created for each connected system\n- [ ] Hydration logic updated to query connected systems\n- [ ] Normalizer handles missing systems gracefully\n\n### Verification (Day 2)\n- [ ] Claude → IntegrateWise → Salesforce (full chain)\n- [ ] ChatGPT → IntegrateWise → HubSpot (full chain)\n- [ ] Multiple AI clients see same Spine data\n- [ ] Failover: One system down, others still work\n\n---\n\n## What's Different (vs. Individual Integrations)\n\n### Old Way (Direct Integration)\n```\nClaude → Salesforce (direct OAuth)\nChatGPT → Salesforce (direct OAuth)\nPerplexity → Salesforce (direct OAuth)\nSlack → Salesforce (direct OAuth)\n\nEach connection: Separate OAuth, separate credentials, separate logic\n```\n\n### New Way (Via IntegrateWise)\n```\nClaude → IntegrateWise → Salesforce (OAuth once at Salesforce level)\nChatGPT → IntegrateWise → Salesforce (same Salesforce credentials)\nPerplexity → IntegrateWise → Salesforce (same Salesforce credentials)\nSlack → IntegrateWise → Salesforce (same Salesforce credentials)\n\nOne connection: Shared OAuth, shared credentials, merged logic\n```\n\n---\n\n## Success Metrics\n\n### Identity Layer\n- OAuth success rate: > 99%\n- JWT token validity: 24 hours\n- Redirect success: 100% to all 5 apps\n\n### Connectivity Layer\n- Connected systems per tenant: 1-28\n- Query time (Spine → System): < 500ms\n- Failure isolation: Partial data returned\n\n### Overall\n- Time from \"Click\" to \"Features Available\": < 2 minutes\n- AI clients seeing same Spine: 100%\n- Data consistency: No stale data in Spine\n\n---\n\n## Summary\n\n**Layer 1 (Identity)**: ChatGPT connects to IntegrateWise (user authenticated)\n**Layer 2 (Connectivity)**: IntegrateWise connects to HubSpot, Salesforce, Stripe (company authorized)\n\n**Result**: ChatGPT can query all 10 systems through IntegrateWise Spine.\n\n**Multiplicative**: Add 5 AI clients and all 5 can query all 10 systems.\n\n**Simple**: No complexity at AI client level. Just click → OAuth → Features.\n"}