{"slug":"architecture/01_SYSTEM_ARCHITECTURE_DOCS","title":"IntegrateWise System & Architecture Documentation","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/01_SYSTEM_ARCHITECTURE_DOCS.mdx","bytes":73901,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Engineering & IT Reference Guide\n\n**Version:** 1.0  \n**Classification:** Internal + Partner  \n**Last Updated:** January 2026  \n**Audience:** CTOs, IT Teams, Security Teams, Integration Partners\n\n---\n\n# Table of Contents\n\n1. [Executive Summary](#1-executive-summary)\n2. [High-Level Architecture](#2-high-level-architecture)\n3. [Data Flow Diagrams](#3-data-flow-diagrams)\n4. [Data Storage Architecture](#4-data-storage-architecture)\n5. [Cloud vs User Systems](#5-cloud-vs-user-systems)\n6. [Integration Architecture](#6-integration-architecture)\n7. [Failure & Retry Behavior](#7-failure--retry-behavior)\n8. [Latency Expectations](#8-latency-expectations)\n9. [Scalability Model](#9-scalability-model)\n10. [Network Architecture](#10-network-architecture)\n\n---\n\n# 1. Executive Summary\n\n## 1.1 What IntegrateWise Is\n\nIntegrateWise is a **cloud-native unified workspace platform** that:\n\n- Connects to your existing business tools via secure OAuth 2.0\n- Normalizes data into a consistent schema (one source of truth)\n- Routes data to appropriate teams with role-based permissions\n- Provides AI-powered automation suggestions (user-approved)\n- Generates documents and reports from unified data\n\n## 1.2 Architecture Philosophy\n\n| Principle            | Implementation                                           |\n| -------------------- | -------------------------------------------------------- |\n| **Edge-First**       | API runs on Cloudflare's global edge network (300+ PoPs) |\n| **Zero Trust**       | All requests authenticated, no implicit trust            |\n| **Data Isolation**   | Tenant data isolated via Row-Level Security              |\n| **User Control**     | All automations require explicit user approval           |\n| **No Data Training** | Customer data never used for AI model training           |\n\n## 1.3 Technology Stack Summary\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    TECHNOLOGY STACK                          │\n├─────────────────────────────────────────────────────────────┤\n│  Frontend        │  React 18 + Vite + TypeScript            │\n│  Mobile          │  React Native (iOS/Android)              │\n│  API Layer       │  Cloudflare Workers (Edge)               │\n│  Database        │  Supabase PostgreSQL 15                  │\n│  Vector Search   │  pgvector extension                      │\n│  Cache           │  Cloudflare KV                           │\n│  Queue           │  Cloudflare Queues                       │\n│  Storage         │  Cloudflare R2 (S3-compatible)           │\n│  Automation      │  n8n Cloud                               │\n│  AI              │  OpenAI API + Anthropic API              │\n│  Auth            │  Supabase Auth (OAuth 2.0, SAML)         │\n│  CDN             │  Cloudflare (automatic)                  │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n# 2. High-Level Architecture\n\n## 2.1 System Architecture Diagram\n\n```\n                                    ┌─────────────────────┐\n                                    │    END USERS        │\n                                    │  (Web / Mobile)     │\n                                    └──────────┬──────────┘\n                                               │\n                                               │ HTTPS\n                                               ▼\n┌──────────────────────────────────────────────────────────────────────────────┐\n│                         CLOUDFLARE EDGE NETWORK                               │\n│                        (300+ Global Points of Presence)                       │\n│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐                  │\n│  │   Cloudflare   │  │   Cloudflare   │  │   Cloudflare   │                  │\n│  │     Pages      │  │    Workers     │  │      WAF       │                  │\n│  │   (Frontend)   │  │   (API Edge)   │  │   (Security)   │                  │\n│  └───────┬────────┘  └───────┬────────┘  └────────────────┘                  │\n│          │                   │                                                │\n│          │    ┌──────────────┼──────────────┐                                │\n│          │    │              │              │                                │\n│          │    ▼              ▼              ▼                                │\n│          │  ┌──────┐    ┌──────┐    ┌──────────┐                             │\n│          │  │  KV  │    │Queues│    │    R2    │                             │\n│          │  │Cache │    │      │    │ Storage  │                             │\n│          │  └──────┘    └──────┘    └──────────┘                             │\n└──────────┼───────────────────┼───────────────────────────────────────────────┘\n           │                   │\n           │                   │ Secure Connection (mTLS)\n           │                   ▼\n           │    ┌──────────────────────────────────────────────────────────────┐\n           │    │                    SUPABASE CLOUD                             │\n           │    │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │\n           │    │  │  PostgreSQL  │  │   Realtime   │  │  Supabase    │       │\n           │    │  │   Database   │  │   (WebSocket)│  │    Auth      │       │\n           │    │  │  + pgvector  │  │              │  │              │       │\n           │    │  └──────────────┘  └──────────────┘  └──────────────┘       │\n           │    └──────────────────────────────────────────────────────────────┘\n           │                   │\n           │                   │\n           │    ┌──────────────┼──────────────┐\n           │    │              │              │\n           │    ▼              ▼              ▼\n           │  ┌──────────┐  ┌──────────┐  ┌──────────┐\n           │  │  n8n     │  │  OpenAI  │  │Anthropic │\n           │  │  Cloud   │  │   API    │  │   API    │\n           │  │(Workflow)│  │          │  │          │\n           │  └──────────┘  └──────────┘  └──────────┘\n           │\n           │\n           ▼\n┌──────────────────────────────────────────────────────────────────────────────┐\n│                         EXTERNAL INTEGRATIONS                                 │\n│                        (Customer's Existing Tools)                            │\n│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │\n│  │  Slack  │  │ HubSpot │  │  Gmail  │  │ Notion  │  │ Sheets  │            │\n│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │\n│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │\n│  │Salesforce│ │ Zendesk │  │  Jira   │  │ Stripe  │  │ GitHub  │            │\n│  │(Coming) │  │(Coming) │  │(Coming) │  │(Coming) │  │(Coming) │            │\n│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.2 Layer Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ LAYER 7: PRESENTATION                                                        │\n│ React Web App + React Native Mobile                                          │\n│ • Renders unified data views                                                 │\n│ • Role-based UI components                                                   │\n│ • Real-time updates via WebSocket                                            │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 6: RENDER ENGINE                                                       │\n│ Document Generation (Cloudflare Workers)                                     │\n│ • DOCX, PPTX, PDF, Email generation                                          │\n│ • Template merging with live data                                            │\n│ • Scheduled report generation                                                │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 5: AUTOMATION ENGINE                                                   │\n│ n8n Cloud + Cloudflare Workers                                               │\n│ • Event-driven triggers                                                      │\n│ • Condition evaluation                                                       │\n│ • Suggestion queue (user approval)                                           │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 4: BRAIN (AI MEMORY)                                                   │\n│ Vector Database (pgvector)                                                   │\n│ • Conversation storage                                                       │\n│ • Semantic search                                                            │\n│ • AI context retrieval                                                       │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 3: CONNECTORS (LOADERS)                                                │\n│ OAuth 2.0 Integration Layer                                                  │\n│ • Token management                                                           │\n│ • Data sync scheduling                                                       │\n│ • Rate limit handling                                                        │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 2: HUBS (ROUTING)                                                      │\n│ Permission & Routing Engine                                                  │\n│ • Team-based data routing                                                    │\n│ • Role-based access control                                                  │\n│ • Audit logging                                                              │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 1: SPINE (DATA LAYER)                                                  │\n│ Supabase PostgreSQL                                                          │\n│ • Normalized data schemas (Zod)                                              │\n│ • Row-level security                                                         │\n│ • Foreign key relationships                                                  │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ LAYER 0: EXTERNAL TOOLS                                                      │\n│ Customer's Existing SaaS Applications                                        │\n│ • Source systems (HubSpot, Slack, etc.)                                      │\n│ • Read via OAuth 2.0 APIs                                                    │\n│ • Optional write-back (user-enabled)                                         │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n# 3. Data Flow Diagrams\n\n## 3.1 Data Ingestion Flow (CONNECT → IMPORT)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         DATA INGESTION FLOW                                  │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│  External   │     │   OAuth     │     │    Sync     │     │  Transform  │\n│    Tool     │────▶│   Handler   │────▶│   Engine    │────▶│   Pipeline  │\n│  (HubSpot)  │     │             │     │             │     │             │\n└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘\n                                                                   │\n     Step 1:              Step 2:            Step 3:               │ Step 4:\n     User clicks      OAuth redirect      Scheduled or         Validate &\n     \"Connect\"        & token store       on-demand sync       Normalize\n                                                                   │\n                                                                   ▼\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Unified   │     │   Routing   │     │    Audit    │     │    Zod      │\n│   Storage   │◀────│    Engine   │◀────│    Logger   │◀────│   Schema    │\n│  (Supabase) │     │   (Hubs)    │     │             │     │  Validation │\n└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘\n\n     Step 8:              Step 7:            Step 6:               Step 5:\n     Store in          Route to           Log every            Validate\n     tenant DB         correct hub        operation            against\n                                                               contract\n```\n\n### Detailed Steps:\n\n| Step | Component          | Action                                | Duration     |\n| ---- | ------------------ | ------------------------------------- | ------------ |\n| 1    | Frontend           | User initiates OAuth flow             | < 1s         |\n| 2    | OAuth Handler      | Redirect to provider, receive tokens  | 5-10s        |\n| 3    | Sync Engine        | Fetch data via API, handle pagination | 10s - 5min   |\n| 4    | Transform Pipeline | Clean, dedupe, format data            | < 1s/record  |\n| 5    | Zod Validation     | Validate against schema contract      | < 1ms/record |\n| 6    | Audit Logger       | Log sync event with metadata          | < 10ms       |\n| 7    | Routing Engine     | Determine target hub(s)               | < 5ms        |\n| 8    | Database           | Insert/update with RLS                | < 50ms       |\n\n## 3.2 Automation Flow (AUTOMATE)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                          AUTOMATION FLOW                                     │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Event     │     │  Trigger    │     │  Condition  │\n│  Detected   │────▶│   Matcher   │────▶│  Evaluator  │\n│             │     │             │     │             │\n└─────────────┘     └─────────────┘     └──────┬──────┘\n                                               │\n     Events:             Match:                │ Evaluate:\n     • Record created    • Which automations   │ • All conditions\n     • Field changed     • Which triggers      │ • AND/OR logic\n     • Time elapsed                            │\n                                               │\n                         ┌─────────────────────┴─────────────────────┐\n                         │                                           │\n                         ▼                                           ▼\n              ┌─────────────────────┐                    ┌─────────────────────┐\n              │   APPROVAL MODE:    │                    │   APPROVAL MODE:    │\n              │   \"suggest_only\"    │                    │ \"auto_run_notify\"   │\n              └──────────┬──────────┘                    └──────────┬──────────┘\n                         │                                          │\n                         ▼                                          ▼\n              ┌─────────────────────┐                    ┌─────────────────────┐\n              │   Suggestion        │                    │   Execute Action    │\n              │   Queue             │                    │   Immediately       │\n              │   (Await Approval)  │                    │                     │\n              └──────────┬──────────┘                    └──────────┬──────────┘\n                         │                                          │\n                         │ User clicks                              │\n                         │ \"Approve\"                                │\n                         │                                          │\n                         └────────────────────┬─────────────────────┘\n                                              │\n                                              ▼\n                              ┌─────────────────────────┐\n                              │    Execute Actions      │\n                              │    • Update field       │\n                              │    • Create task        │\n                              │    • Send notification  │\n                              │    • Create alert       │\n                              └─────────────────────────┘\n```\n\n## 3.3 Document Generation Flow (CREATE)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                       DOCUMENT GENERATION FLOW                               │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   User      │     │  Template   │     │    Data     │     │   Render    │\n│   Request   │────▶│   Loader    │────▶│   Fetcher   │────▶│   Engine    │\n│             │     │             │     │             │     │             │\n└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘\n                                                                   │\n     Input:              Load:               Query:                │ Merge:\n     • Template ID       • DOCX/PPTX        • Accounts             │ • Replace\n     • Data filters      • Email HTML       • Metrics              │   placeholders\n     • Output format     • Placeholders     • Activities           │ • Format values\n                                                                   │\n                                                                   ▼\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   User      │     │   Signed    │     │    R2       │     │   Output    │\n│  Download   │◀────│    URL      │◀────│   Storage   │◀────│  Generator  │\n│             │     │  (15 min)   │     │             │     │             │\n└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘\n\n     Output:            Secure:              Store:              Generate:\n     • Download file    • Time-limited      • Temporary         • DOCX/PPTX\n     • Open in app      • Signed URL        • 24hr retention    • PDF/Email\n```\n\n## 3.4 AI Memory Flow (REMEMBER)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                          AI MEMORY FLOW (BRAIN)                              │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n                           STORING CONVERSATIONS\n                           ─────────────────────\n\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│  AI Chat    │     │  Browser    │     │  Embedding  │     │   Vector    │\n│ (ChatGPT/   │────▶│  Extension  │────▶│   Model     │────▶│   Store     │\n│  Claude)    │     │             │     │ (OpenAI)    │     │ (pgvector)  │\n└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘\n\n     Source:            Capture:            Convert:             Store:\n     • ChatGPT          • Conversation      • Text → Vector      • 1536-dim\n     • Claude           • Metadata          • 1536 dimensions    • Tenant isolated\n     • Gemini           • Timestamp                              • Indexed\n\n\n                           SEARCHING MEMORIES\n                           ──────────────────\n\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Search    │     │  Embedding  │     │   Vector    │     │   Results   │\n│   Query     │────▶│   Model     │────▶│   Search    │────▶│  (Ranked)   │\n│             │     │             │     │  (cosine)   │     │             │\n└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘\n\n     Input:             Convert:            Match:               Output:\n     • Natural          • Query → Vector    • Similarity > 0.7   • Top 10\n       language         • Same model        • Filter by tenant   • With scores\n```\n\n---\n\n# 4. Data Storage Architecture\n\n## 4.1 Storage Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         DATA STORAGE MAP                                     │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                              │\n│  ┌─────────────────────────────────────────────────────────────────────┐    │\n│  │                    SUPABASE POSTGRESQL                               │    │\n│  │                    (Primary Data Store)                              │    │\n│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │    │\n│  │  │   Core      │  │   Vector    │  │   Audit     │                  │    │\n│  │  │   Tables    │  │   Store     │  │   Logs      │                  │    │\n│  │  │             │  │ (pgvector)  │  │             │                  │    │\n│  │  │ • accounts  │  │             │  │ • actions   │                  │    │\n│  │  │ • contacts  │  │ • memories  │  │ • changes   │                  │    │\n│  │  │ • deals     │  │ • embeddings│  │ • logins    │                  │    │\n│  │  │ • tasks     │  │             │  │             │                  │    │\n│  │  └─────────────┘  └─────────────┘  └─────────────┘                  │    │\n│  └─────────────────────────────────────────────────────────────────────┘    │\n│                                                                              │\n│  ┌─────────────────────────────────────────────────────────────────────┐    │\n│  │                    CLOUDFLARE KV                                     │    │\n│  │                    (Edge Cache)                                      │    │\n│  │  • Session tokens        • Rate limit counters                      │    │\n│  │  • API response cache    • Feature flags                            │    │\n│  │  • User preferences      • Connector status                         │    │\n│  └─────────────────────────────────────────────────────────────────────┘    │\n│                                                                              │\n│  ┌─────────────────────────────────────────────────────────────────────┐    │\n│  │                    CLOUDFLARE R2                                     │    │\n│  │                    (Object Storage)                                  │    │\n│  │  • Generated documents   • Template files                           │    │\n│  │  • Attachments           • Export archives                          │    │\n│  │  • User uploads          • Backup snapshots                         │    │\n│  └─────────────────────────────────────────────────────────────────────┘    │\n│                                                                              │\n│  ┌─────────────────────────────────────────────────────────────────────┐    │\n│  │                    CLOUDFLARE QUEUES                                 │    │\n│  │                    (Async Processing)                                │    │\n│  │  • Sync job queue        • Email queue                              │    │\n│  │  • Webhook delivery      • Report generation                        │    │\n│  │  • Automation triggers   • Bulk operations                          │    │\n│  └─────────────────────────────────────────────────────────────────────┘    │\n│                                                                              │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 4.2 Data by Storage Type\n\n| Data Type              | Storage    | Location        | Retention       | Encryption |\n| ---------------------- | ---------- | --------------- | --------------- | ---------- |\n| **Core Business Data** | PostgreSQL | Supabase (AWS)  | Until deleted   | AES-256    |\n| **Vector Embeddings**  | pgvector   | Supabase (AWS)  | Until deleted   | AES-256    |\n| **Audit Logs**         | PostgreSQL | Supabase (AWS)  | 2 years         | AES-256    |\n| **Session Tokens**     | KV         | Cloudflare Edge | 24 hours        | TLS only   |\n| **API Cache**          | KV         | Cloudflare Edge | 5-60 min        | TLS only   |\n| **Generated Docs**     | R2         | Cloudflare      | 24 hours        | AES-256    |\n| **Attachments**        | R2         | Cloudflare      | Until deleted   | AES-256    |\n| **Sync Jobs**          | Queues     | Cloudflare      | Until processed | TLS only   |\n\n## 4.3 Database Schema (Simplified)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         DATABASE SCHEMA                                      │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐\n│  organizations  │       │     users       │       │     teams       │\n├─────────────────┤       ├─────────────────┤       ├─────────────────┤\n│ id (PK)         │──┐    │ id (PK)         │       │ id (PK)         │\n│ name            │  │    │ organization_id │───┐   │ organization_id │\n│ plan            │  │    │ email           │   │   │ name            │\n│ settings        │  │    │ role            │   │   │ hub_id          │\n└─────────────────┘  │    │ team_ids[]      │   │   └─────────────────┘\n                     │    └─────────────────┘   │\n                     │                          │\n                     │    ┌─────────────────────┘\n                     │    │\n                     ▼    ▼\n┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐\n│    accounts     │       │    contacts     │       │     deals       │\n├─────────────────┤       ├─────────────────┤       ├─────────────────┤\n│ id (PK)         │◀──┐   │ id (PK)         │       │ id (PK)         │\n│ organization_id │   │   │ organization_id │       │ organization_id │\n│ external_id     │   │   │ account_id (FK) │───────│ account_id (FK) │\n│ source          │   │   │ email           │       │ amount          │\n│ name            │   │   │ name            │       │ stage           │\n│ health_score    │   └───│                 │       │                 │\n│ mrr             │       └─────────────────┘       └─────────────────┘\n└─────────────────┘\n\n                     ┌─────────────────┐       ┌─────────────────┐\n                     │  health_scores  │       │   audit_logs    │\n                     ├─────────────────┤       ├─────────────────┤\n                     │ id (PK)         │       │ id (PK)         │\n                     │ account_id (FK) │       │ organization_id │\n                     │ score           │       │ user_id         │\n                     │ components      │       │ action          │\n                     │ trend           │       │ resource_type   │\n                     └─────────────────┘       │ resource_id     │\n                                               │ timestamp       │\n                                               └─────────────────┘\n```\n\n## 4.4 Row-Level Security (Multi-Tenancy)\n\n```sql\n-- Every table has organization_id column\n-- RLS policy ensures tenant isolation\n\nALTER TABLE accounts ENABLE ROW LEVEL SECURITY;\n\nCREATE POLICY accounts_isolation ON accounts\n  USING (organization_id = current_setting('app.organization_id')::UUID);\n\n-- Set organization context on each request\nSET app.organization_id = 'org_abc123';\n\n-- All queries automatically filtered by organization\nSELECT * FROM accounts;  -- Only returns org_abc123's accounts\n```\n\n---\n\n# 5. Cloud vs User Systems\n\n## 5.1 What Runs Where\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                    INTEGRATEWISE CLOUD                                       │\n│                    (Managed by IntegrateWise)                                │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                              │\n│  ✓ Web Application (React frontend)                                         │\n│  ✓ API Layer (Cloudflare Workers)                                           │\n│  ✓ Database (Supabase PostgreSQL)                                           │\n│  ✓ File Storage (Cloudflare R2)                                             │\n│  ✓ Automation Engine (n8n Cloud)                                            │\n│  ✓ Document Generation                                                      │\n│  ✓ AI Processing (via OpenAI/Anthropic APIs)                                │\n│                                                                              │\n│  Data Location: Cloudflare Global + AWS us-east-1 (Supabase)                │\n│                                                                              │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                    CUSTOMER SYSTEMS                                          │\n│                    (Customer's Environment)                                  │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                              │\n│  ✓ Existing SaaS tools (HubSpot, Slack, etc.)                               │\n│  ✓ Browser (for web access)                                                 │\n│  ✓ Mobile device (for mobile app)                                           │\n│  ✓ Browser extension (optional, for AI memory capture)                      │\n│                                                                              │\n│  Nothing installed on customer servers                                      │\n│  No agents or daemons required                                              │\n│  No VPN or network changes required                                         │\n│                                                                              │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                    THIRD-PARTY SERVICES                                      │\n│                    (External Dependencies)                                   │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                              │\n│  ✓ Cloudflare (CDN, Workers, KV, R2, Queues)                                │\n│  ✓ Supabase (PostgreSQL, Auth, Realtime)                                    │\n│  ✓ OpenAI (GPT-4 for AI features)                                           │\n│  ✓ Anthropic (Claude for AI features)                                       │\n│  ✓ n8n Cloud (Workflow automation)                                          │\n│                                                                              │\n│  All vendors are SOC 2 Type II certified                                    │\n│                                                                              │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 5.2 Data Never Leaves Cloud Boundary\n\n| Data Type         | Where Processed       | Where Stored | Customer Access  |\n| ----------------- | --------------------- | ------------ | ---------------- |\n| Business data     | IntegrateWise API     | Supabase DB  | Via app/API      |\n| Generated docs    | IntegrateWise Workers | R2 (temp)    | Download link    |\n| AI conversations  | OpenAI/Anthropic      | Supabase DB  | Via Brain search |\n| Audit logs        | IntegrateWise API     | Supabase DB  | Via app/API      |\n| Files/attachments | IntegrateWise API     | R2           | Download link    |\n\n## 5.3 No On-Premise Deployment (Currently)\n\nIntegrateWise is **cloud-only**. We do not currently offer:\n\n- On-premise installation\n- Private cloud deployment\n- Air-gapped deployments\n- Self-hosted options\n\n**Roadmap:** Enterprise self-hosted option planned for 2027.\n\n---\n\n# 6. Integration Architecture\n\n## 6.1 How Integrations Connect\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                      INTEGRATION CONNECTION FLOW                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n┌─────────┐                    ┌─────────────┐                    ┌─────────┐\n│  User   │                    │IntegrateWise│                    │ HubSpot │\n│         │                    │             │                    │  (etc)  │\n└────┬────┘                    └──────┬──────┘                    └────┬────┘\n     │                                │                                │\n     │  1. Click \"Connect HubSpot\"    │                                │\n     │───────────────────────────────▶│                                │\n     │                                │                                │\n     │  2. Redirect to HubSpot OAuth  │                                │\n     │◀───────────────────────────────│                                │\n     │                                │                                │\n     │  3. User authorizes            │                                │\n     │────────────────────────────────┼───────────────────────────────▶│\n     │                                │                                │\n     │                                │  4. Redirect with auth code    │\n     │                                │◀───────────────────────────────│\n     │                                │                                │\n     │                                │  5. Exchange code for tokens   │\n     │                                │───────────────────────────────▶│\n     │                                │                                │\n     │                                │  6. Access + Refresh tokens    │\n     │                                │◀───────────────────────────────│\n     │                                │                                │\n     │                                │  7. Store encrypted tokens     │\n     │                                │  (in Supabase)                 │\n     │                                │                                │\n     │  8. Connection successful      │                                │\n     │◀───────────────────────────────│                                │\n     │                                │                                │\n```\n\n## 6.2 Sync Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         SYNC ARCHITECTURE                                    │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n                              SCHEDULED SYNC\n                              ─────────────\n\n     ┌─────────────┐\n     │   Cron      │  Every 15 min (configurable)\n     │  Scheduler  │\n     └──────┬──────┘\n            │\n            ▼\n     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n     │  Get Active │     │  Check Last │     │  Calculate  │\n     │ Connections │────▶│  Sync Time  │────▶│    Delta    │\n     └─────────────┘     └─────────────┘     └──────┬──────┘\n                                                    │\n                                                    ▼\n     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n     │   Fetch     │     │   Handle    │     │   Call      │\n     │  All Pages  │◀────│  Pagination │◀────│  External   │\n     └─────────────┘     └─────────────┘     │    API      │\n                                             └─────────────┘\n\n\n                              REAL-TIME SYNC (Slack)\n                              ─────────────────────\n\n     ┌─────────────┐\n     │   Slack     │  Webhook POST\n     │   Event     │\n     └──────┬──────┘\n            │\n            ▼\n     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n     │  Webhook    │     │   Verify    │     │   Process   │\n     │  Endpoint   │────▶│  Signature  │────▶│   Event     │\n     │  (Worker)   │     │             │     │             │\n     └─────────────┘     └─────────────┘     └──────┬──────┘\n                                                    │\n                                                    ▼\n                                             ┌─────────────┐\n                                             │   Update    │\n                                             │   Database  │\n                                             └─────────────┘\n```\n\n## 6.3 Integration Permissions Matrix\n\n| Integration | Read | Write | Delete | Webhook | OAuth Scopes                                              |\n| ----------- | ---- | ----- | ------ | ------- | --------------------------------------------------------- |\n| **Slack**   | ✅   | ✅    | ❌     | ✅      | `channels:read`, `users:read`, `chat:write`               |\n| **HubSpot** | ✅   | ✅    | ❌     | ❌      | `crm.objects.contacts.read`, `crm.objects.companies.read` |\n| **Gmail**   | ✅   | ❌    | ❌     | ❌      | `gmail.readonly`                                          |\n| **Notion**  | ✅   | ✅    | ❌     | ❌      | `read_content`, `update_content`                          |\n| **Sheets**  | ✅   | ✅    | ❌     | ❌      | `spreadsheets`                                            |\n\n**Note:** Write and delete permissions are optional. Users can connect in read-only mode.\n\n---\n\n# 7. Failure & Retry Behavior\n\n## 7.1 Retry Strategy Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         RETRY STRATEGY                                       │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n                    EXPONENTIAL BACKOFF WITH JITTER\n                    ──────────────────────────────\n\n     Attempt 1          Attempt 2          Attempt 3          Attempt 4\n         │                  │                  │                  │\n         ▼                  ▼                  ▼                  ▼\n     ┌───────┐          ┌───────┐          ┌───────┐          ┌───────┐\n     │ Try   │          │ Wait  │          │ Wait  │          │ Wait  │\n     │       │──FAIL───▶│ 1-2s  │──FAIL───▶│ 4-8s  │──FAIL───▶│16-32s │\n     └───────┘          └───────┘          └───────┘          └───────┘\n                                                                   │\n                                                              FAIL │\n                                                                   ▼\n                                                          ┌───────────────┐\n                                                          │ Dead Letter   │\n                                                          │ Queue         │\n                                                          │ (Alert Admin) │\n                                                          └───────────────┘\n```\n\n## 7.2 Retry Configuration by Operation\n\n| Operation               | Max Retries | Initial Delay | Max Delay | Timeout |\n| ----------------------- | ----------- | ------------- | --------- | ------- |\n| **API Sync**            | 5           | 1s            | 32s       | 30s     |\n| **Webhook Delivery**    | 10          | 1s            | 5 min     | 10s     |\n| **Document Generation** | 3           | 5s            | 30s       | 60s     |\n| **AI Completion**       | 3           | 2s            | 10s       | 30s     |\n| **Email Send**          | 5           | 5s            | 5 min     | 15s     |\n| **Database Write**      | 3           | 100ms         | 2s        | 5s      |\n\n## 7.3 Error Handling by Type\n\n| Error Type       | HTTP Code | Retry? | Action                        |\n| ---------------- | --------- | ------ | ----------------------------- |\n| **Rate Limited** | 429       | Yes    | Wait for `Retry-After` header |\n| **Server Error** | 500-599   | Yes    | Exponential backoff           |\n| **Bad Request**  | 400       | No     | Log error, alert user         |\n| **Unauthorized** | 401       | Once   | Refresh token, retry          |\n| **Forbidden**    | 403       | No     | Alert user, check permissions |\n| **Not Found**    | 404       | No     | Log, continue sync            |\n| **Timeout**      | -         | Yes    | Exponential backoff           |\n| **Connection**   | -         | Yes    | Exponential backoff           |\n\n## 7.4 Circuit Breaker Pattern\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                       CIRCUIT BREAKER STATES                                 │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     ┌───────────┐                    ┌───────────┐                    ┌───────────┐\n     │  CLOSED   │                    │   OPEN    │                    │HALF-OPEN  │\n     │           │                    │           │                    │           │\n     │  Normal   │   5 failures in    │ All calls │   After 60s       │ Test call │\n     │ operation │──  60 seconds  ───▶│  blocked  │── cooldown ──────▶│  allowed  │\n     │           │                    │           │                    │           │\n     └───────────┘                    └─────┬─────┘                    └─────┬─────┘\n          ▲                                 │                               │\n          │                                 │                               │\n          │                                 │ Still failing                 │ Success\n          │                                 └───────────────────────────────┤\n          │                                                                 │\n          └─────────────────────────────────────────────────────────────────┘\n```\n\n| State         | Behavior                                          |\n| ------------- | ------------------------------------------------- |\n| **CLOSED**    | Normal operation, all requests pass through       |\n| **OPEN**      | All requests fail immediately (no external calls) |\n| **HALF-OPEN** | Limited requests allowed to test recovery         |\n\n## 7.5 Failure Notification\n\n| Failure Type                      | Alert Channel | Recipient        |\n| --------------------------------- | ------------- | ---------------- |\n| **Sync failure (3x)**             | Email + App   | Connection owner |\n| **Webhook delivery failed (10x)** | Email         | Admin            |\n| **Circuit breaker open**          | Slack + Email | Engineering      |\n| **Database connection lost**      | PagerDuty     | On-call          |\n\n---\n\n# 8. Latency Expectations\n\n## 8.1 Response Time Targets (P95)\n\n| Operation                 | Target   | Location   | Notes                  |\n| ------------------------- | -------- | ---------- | ---------------------- |\n| **API Request (simple)**  | < 100ms  | Edge       | Cached or simple query |\n| **API Request (complex)** | < 500ms  | Edge → DB  | Multi-table joins      |\n| **Dashboard Load**        | < 2s     | Edge → DB  | With prefetch          |\n| **Search (text)**         | < 200ms  | DB         | PostgreSQL FTS         |\n| **Search (vector)**       | < 300ms  | DB         | pgvector cosine        |\n| **Document Generation**   | < 5s     | Worker     | Depends on size        |\n| **Initial Sync**          | 1-10 min | Background | Depends on data volume |\n| **Incremental Sync**      | < 1 min  | Background | Delta only             |\n\n## 8.2 Latency by Region\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                    LATENCY BY USER REGION                                    │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     User Location        Edge Response        DB Response        Total\n     ─────────────        ─────────────        ───────────        ─────\n\n     US East              < 20ms               < 30ms             < 100ms\n     US West              < 20ms               < 50ms             < 120ms\n     Europe (West)        < 20ms               < 80ms             < 150ms\n     Europe (East)        < 30ms               < 100ms            < 180ms\n     Asia Pacific         < 30ms               < 150ms            < 230ms\n     India                < 30ms               < 180ms            < 260ms\n     South America        < 40ms               < 120ms            < 210ms\n\n     Note: Database is in AWS us-east-1 (Supabase)\n     Edge caching reduces DB latency impact for read-heavy operations\n```\n\n## 8.3 Performance Optimization\n\n| Optimization           | Implementation    | Impact                        |\n| ---------------------- | ----------------- | ----------------------------- |\n| **Edge Caching**       | Cloudflare KV     | 80% of reads served from edge |\n| **Connection Pooling** | Supabase built-in | Reduced connection overhead   |\n| **Query Optimization** | Indexed columns   | < 50ms for common queries     |\n| **Lazy Loading**       | Frontend chunking | Faster initial render         |\n| **Prefetching**        | Predictive loads  | Perceived instant navigation  |\n| **Compression**        | Brotli/gzip       | 70% smaller payloads          |\n\n---\n\n# 9. Scalability Model\n\n## 9.1 Current Capacity\n\n| Resource                 | Current Limit | Scaling Path                    |\n| ------------------------ | ------------- | ------------------------------- |\n| **Concurrent Users**     | 10,000        | Horizontal (Workers auto-scale) |\n| **Requests/Second**      | 100,000       | Horizontal (Cloudflare)         |\n| **Database Storage**     | 8 GB          | Vertical (Supabase Pro: 8GB)    |\n| **Database Connections** | 60            | Connection pooling              |\n| **File Storage**         | Unlimited     | Pay-as-you-go (R2)              |\n| **Records per Org**      | 1,000,000     | Partitioning at scale           |\n\n## 9.2 Scaling Strategy\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                       SCALING STRATEGY                                       │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     CURRENT (0-1000 orgs)              GROWTH (1000-10000 orgs)\n     ────────────────────               ─────────────────────────\n\n     ┌─────────────────┐                ┌─────────────────┐\n     │  Single DB      │       →        │  Read Replicas  │\n     │  (Supabase Pro) │                │  + Connection   │\n     │                 │                │    Pooling      │\n     └─────────────────┘                └─────────────────┘\n\n     ┌─────────────────┐                ┌─────────────────┐\n     │  Workers        │       →        │  Workers        │\n     │  (Auto-scale)   │                │  (Auto-scale)   │\n     │                 │                │  + More regions │\n     └─────────────────┘                └─────────────────┘\n\n     ┌─────────────────┐                ┌─────────────────┐\n     │  n8n Cloud      │       →        │  Dedicated n8n  │\n     │  (Shared)       │                │  Instance       │\n     └─────────────────┘                └─────────────────┘\n\n\n     ENTERPRISE (10000+ orgs)\n     ─────────────────────────\n\n     ┌─────────────────┐\n     │  Sharded DB     │\n     │  (By org_id)    │\n     │                 │\n     └─────────────────┘\n\n     ┌─────────────────┐\n     │  Dedicated      │\n     │  Compute per    │\n     │  Large Customer │\n     └─────────────────┘\n```\n\n---\n\n# 10. Network Architecture\n\n## 10.1 Network Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         NETWORK ARCHITECTURE                                 │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n                              INTERNET\n                                 │\n                                 │ HTTPS (TLS 1.3)\n                                 ▼\n     ┌───────────────────────────────────────────────────────────────────────┐\n     │                    CLOUDFLARE WAF                                      │\n     │  • DDoS protection                                                     │\n     │  • Rate limiting                                                       │\n     │  • Bot detection                                                       │\n     │  • IP reputation                                                       │\n     └────────────────────────────┬──────────────────────────────────────────┘\n                                  │\n                                  │ Internal\n                                  ▼\n     ┌───────────────────────────────────────────────────────────────────────┐\n     │                    CLOUDFLARE WORKERS                                  │\n     │  • Request validation                                                  │\n     │  • Authentication                                                      │\n     │  • Business logic                                                      │\n     └────────────────────────────┬──────────────────────────────────────────┘\n                                  │\n                                  │ Private (Mutual TLS)\n                                  ▼\n     ┌───────────────────────────────────────────────────────────────────────┐\n     │                    SUPABASE                                            │\n     │  • PostgreSQL                                                          │\n     │  • Connection pooling (PgBouncer)                                      │\n     │  • Row-level security                                                  │\n     └───────────────────────────────────────────────────────────────────────┘\n```\n\n## 10.2 Required Firewall Rules\n\n**For customers with egress filtering:**\n\n| Direction | Source | Destination          | Port | Protocol | Purpose       |\n| --------- | ------ | -------------------- | ---- | -------- | ------------- |\n| Outbound  | User   | \\*.integratewise.com | 443  | HTTPS    | Application   |\n| Outbound  | User   | \\*.cloudflare.com    | 443  | HTTPS    | CDN           |\n| Outbound  | User   | \\*.supabase.co       | 443  | HTTPS    | Auth/Realtime |\n\n**No inbound rules required** - IntegrateWise does not need to connect to customer networks.\n\n## 10.3 IP Addresses\n\nIntegrateWise uses Cloudflare's IP ranges. For allowlisting:\n\n```\n# Cloudflare IPv4 ranges\nhttps://www.cloudflare.com/ips-v4\n\n# Cloudflare IPv6 ranges\nhttps://www.cloudflare.com/ips-v6\n```\n\n**Note:** We recommend allowlisting by domain (`*.integratewise.com`) rather than IP, as Cloudflare IPs may change.\n\n---\n\n# Appendix A: Technology Decision Log\n\n| Decision       | Choice              | Alternatives Considered  | Rationale                     |\n| -------------- | ------------------- | ------------------------ | ----------------------------- |\n| **Frontend**   | React               | Vue, Svelte              | Ecosystem, hiring pool        |\n| **API**        | Cloudflare Workers  | AWS Lambda, Vercel       | Edge performance, cost        |\n| **Database**   | Supabase PostgreSQL | PlanetScale, Neon        | Auth integration, realtime    |\n| **Queue**      | Cloudflare Queues   | SQS, RabbitMQ            | Same vendor, simplicity       |\n| **Storage**    | Cloudflare R2       | S3, GCS                  | No egress fees                |\n| **Automation** | n8n                 | Temporal, Step Functions | Visual builder, self-hostable |\n| **AI**         | OpenAI + Anthropic  | Single vendor            | Best models, redundancy       |\n\n---\n\n# Appendix B: Glossary\n\n| Term         | Definition                                                |\n| ------------ | --------------------------------------------------------- |\n| **Edge**     | Cloudflare's global network (300+ data centers)           |\n| **Worker**   | Serverless function running on Cloudflare's edge          |\n| **RLS**      | Row-Level Security - PostgreSQL feature for multi-tenancy |\n| **pgvector** | PostgreSQL extension for vector similarity search         |\n| **KV**       | Key-Value store for edge caching                          |\n| **R2**       | S3-compatible object storage by Cloudflare                |\n| **Spine**    | IntegrateWise's core data layer                           |\n| **Hub**      | Team/function-based routing layer                         |\n| **Brain**    | AI memory and vector search system                        |\n\n---\n\n**Document Version:** 1.0  \n**Last Updated:** January 2026  \n**Owner:** Engineering Team  \n**Review Cycle:** Quarterly\n\nFor questions: architecture@integratewise.com\n"}