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