{"slug":"architecture/ARCHITECTURE_DIAGRAMS","title":"IntegrateWise System Architecture - Visual Diagrams","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/ARCHITECTURE_DIAGRAMS.mdx","bytes":36187,"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## 1. Three-Spine Lifecycle Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ UNIFIED LIFECYCLE (All Three Spines) │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n HUMAN SPINE (L1)\n Ground Truth Layer\n ┌──────────────────────────────┐\n │ User creates quarterly goal │\n └──────────────┬───────────────┘\n │\n ┌──────────────┴───────────────┐\n │ INTAKE PHASE │\n │ Signal enters the system │\n └──────────────┬───────────────┘\n │\n ┌──────────────┴───────────────┐\n │ PROMOTION PHASE │\n │ Validates, ready to act │\n └──────────────┬───────────────┘\n │\n ┌──────────────┴───────────────┐\n │ MEMORY PHASE │\n │ Stored as ground truth │\n └──────────────┬───────────────┘\n │\n ┌─────────────────────────────┼─────────────────────────────┐\n │ │ │\n │ ┌──────────┴───────────┐ │\n │ │ DECAY PHASE │ │\n │ │ Aged signals archived│ │\n │ └──────────┬────────────┘ │\n │ │ │\n │ ┌───────────────────┴──────────────────┐ │\n │ │ CONTINUITY PHASE │ │\n │ │ Outcome stored in continuity graph │ │\n │ │ (For next cycle learning) │ │\n │ └────────────────────────────────────┬─┘ │\n │ │ │\n │ ┌─────────┴─────┐ │\n │ │ COMPOUNDS INTO │ │\n │ │ AI SPINE + COL │ │\n │ │ LABORATION │ │\n │ └────────────────┘ │\n │ │\n │ AI SPINE (L3) COLLABORATION │ (L2)\n │ Intelligence Layer Joint Decision │\n │ ┌──────────────────────────────┐ ┌────────────────┐ │\n │ │Twin analyzes churn pattern │ │ Human approves │ │\n │ │→ reasoning trace generated │→ │ AI proposal │──┘\n │ │→ proposal with confidence │ │ → joint outcome│\n │ │→ all three flow through same │ │ → memory │\n │ │ 5-phase lifecycle │ │ compounds │\n │ └──────────────────────────────┘ └────────────────┘\n │\n └──────────────────────────────────────────────────────────┘\n │\n ↓\n ⚙️ SYSTEM LEARNING LOOP ⚙️\n (Outcomes feed back in)\n```\n\n---\n\n## 2. Monorepo Structure\n\n```\n┌────────────────────────────────────────────────────────────────┐\n│ INTEGRATEWISE MONOREPO │\n└────────────────────────────────────────────────────────────────┘\n\n┌─ APPS (User-Facing) ──────────────────────────────────────────┐\n│ ├─ web/ Next.js 16 SPA (Next.js 16 App Router) │\n│ │ ├─ Layer Switcher (Human/AI/Collaborate/Approve) │\n│ │ ├─ Domain Workbenches (CS, Sales, Marketing, RevOps, etc) │\n│ │ ├─ Twin Chat Interface │\n│ │ ├─ Cognitive Overlay (L2) │\n│ │ ├─ Memory Search │\n│ │ └─ Approval Center │\n│ │ │\n│ ├─ desktop/ Electron desktop app │\n│ ├─ mobile/ React Native iOS/Android │\n│ └─ local-monitor/ Node.js folder watcher │\n└───────────────────────────────────────────────────────────────┘\n\n┌─ SERVICES (28 Cloudflare Workers) ────────────────────────────┐\n│ │\n│ ┌─ DATA INGESTION (S1-S4) ──────────────────────────────────┐ │\n│ │ LOADER Universal intake (MCP-native, no transform) │ │\n│ │ CONNECTOR Tool OAuth + API integration │ │\n│ │ NORMALIZER 8-stage LLM-in-loop pipeline │ │\n│ │ PIPELINE Entity resolution + Spine writes │ │\n│ └──────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ ┌─ INTELLIGENCE (S5-S8) ──────────────────────────────────┐ │\n│ │ INTELLIGENCE Signal analysis + anomalies │ │\n│ │ THINK Synchronous reasoning │ │\n│ │ IW-AGENT-RUNTIME Twin orchestration + LLM dispatch │ │\n│ │ CONTINUITY 5-phase lifecycle + memory consolidation │ │\n│ └──────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ ┌─ GOVERNANCE (S9-S10) ───────────────────────────────────┐ │\n│ │ GOVERN Approval gate (no execution authority) │ │\n│ │ WORKFLOW Async execution orchestration │ │\n│ └──────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ ┌─ MEMORY & KNOWLEDGE (S11-S12) ──────────────────────────┐ │\n│ │ KNOWLEDGE Semantic search + vector embeddings │ │\n│ │ HERMES Memory operations + lifecycle │ │\n│ └──────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─ ACCESS & ROUTING ───────────────────────────────────────┐ │\n│ │ GATEWAY Public ingress, auth, routing │ │\n│ │ TENANTS Tenant provisioning + isolation │ │\n│ │ ADMIN Internal operations │ │\n│ └──────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─ INTEGRATIONS & SUPPORT ─────────────────────────────────┐ │\n│ │ MCP-CONNECTOR External AI access to Spine │ │\n│ │ WEBHOOK-INGRESS Secure webhook receivers │ │\n│ │ BILLING Usage tracking + SaaS │ │\n│ │ TELEMETRY Observability + monitoring │ │\n│ │ FOLDER-WATCHER Local file monitoring │ │\n│ │ [11+ other workers] ACT, Hermes, Govern, etc │ │\n│ └──────────────────────────────────────────────────────────┘ │\n└───────────────────────────────────────────────────────────────┘\n\n┌─ PACKAGES (Shared Libraries) ─────────────────────────────────┐\n│ ├─ types/ Canonical schemas + type definitions │\n│ ├─ db/ Database client abstractions │\n│ ├─ api/ HTTP client utilities │\n│ ├─ connector-contracts Integration contracts │\n│ ├─ rbac/ Role-based access control │\n│ ├─ tenancy/ Multi-tenant utilities │\n│ ├─ hermes-spine-memory Memory operations library │\n│ └─ [3+ other packages] │\n└───────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 3. Data Flow Architecture\n\n```\n┌───────────────────────────────────────────────────────────────┐\n│ DATA FLOW: INGEST → NORMALIZE → SPINE │\n└───────────────────────────────────────────────────────────────┘\n\nEXTERNAL TOOLS (HubSpot, Salesforce, Slack, Jira, etc.)\n │\n ├─ Push: Webhooks → WEBHOOK-INGRESS → LOADER\n └─ Pull: Scheduled → CONNECTOR-SYNC → LOADER\n │\n ↓\n ┌─────────────────────────────────────────────┐\n │ LOADER (S1) │\n │ • Receives raw events │\n │ • No transformation │\n │ • Tracks provenance (source, timestamp) │\n │ • Enqueues to NORMALIZER │\n └─────────────────────────────────────────────┘\n │\n ↓\n ┌─────────────────────────────────────────────┐\n │ NORMALIZER (S2-S4) 8-Stage Pipeline │\n │ 1. Intake: Deserialize │\n │ 2. Classification: Identify entity type │\n │ 3. Entity Resolution: LLM → canonical ID │\n │ 4. Field Mapping: LLM → canonical schema │\n │ 5. Validation: Schema compliance │\n │ 6. Enrichment: LLM → missing fields │\n │ 7. Deduplication: Check if exists │\n │ 8. Emission: Output as MCP call │\n │ │\n │ Cost Model: LLM paid ONCE per entity │\n └─────────────────────────────────────────────┘\n │\n ↓\n ┌─────────────────────────────────────────────┐\n │ PIPELINE (S4) │\n │ • Consumes normalized MCP calls │\n │ • Resolves entity to canonical ID │\n │ • Writes to D1 domain partitions │\n │ • Builds relationship graph │\n │ • Triggers INTELLIGENCE (signal analysis) │\n │ • Enqueues to CONTINUITY │\n └─────────────────────────────────────────────┘\n │\n ┌────────────┴────────────────────────────────┐\n │ │\n ↓ ↓\n┌──────────────────────┐ ┌─────────────────────────────┐\n│ D1 (Hot, Edge) │ │ Supabase Fortress (SSOT) │\n│ • person_data │◄──────►│ • Canonical entities │\n│ • account_data │ │ • Audit logs │\n│ • opportunity_data │ │ • Memory tables │\n│ • signal_cache │ │ • RLS policies │\n│ • continuity_graph │ │ • Billing logs │\n│ • execution_queue │ └─────────────────────────────┘\n│ • [9 domain parts] │\n└──────────────────────┘\n │\n ↓\n ┌─────────────────────────────────────────────┐\n │ INTELLIGENCE (S5) │\n │ • Analyzes entity changes │\n │ • Detects anomalies │\n │ • Generates signals + confidence │\n │ • Emits to L2 Cognitive Overlay │\n └─────────────────────────────────────────────┘\n │\n ↓\n ┌─────────────────────────────────────────────┐\n │ CONTINUITY (S7) │\n │ • Implements 5-phase lifecycle │\n │ • Triages signals (via TriageBot MCP) │\n │ • Promotes to active memory │\n │ • Ages out stale signals │\n │ • Compounds outcomes (human+AI) │\n └─────────────────────────────────────────────┘\n │\n ↓\n Frontend (L1-L4 Workbenches) ← Spine queries\n```\n\n---\n\n## 4. Request Flow Through Gateway\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ REQUEST FLOW: PUBLIC → GATEWAY → WORKER │\n└──────────────────────────────────────────────────────────────┘\n\nINTERNET (Public Users, External AIs, MCP Clients)\n │\n ↓\n┌────────────────────────────────────────────────────────────┐\n│ GATEWAY (S0) │\n│ • SSL/TLS termination │\n│ • Request authentication (Supabase auth) │\n│ • Route authorization (RBAC check) │\n│ • Request routing to downstream workers │\n│ • Rate limiting + DDoS protection │\n│ • Logging + telemetry │\n│ │\n│ KEY INVARIANT: This is the ONLY public entry point │\n└────────────────────────────────────────────────────────────┘\n │\n ├─ Authenticated ← Gateway verifies JWT token\n │ │\n │ ├─ Route: /api/spine/... → PIPELINE (read Spine)\n │ ├─ Route: /api/twin/... → IW-AGENT-RUNTIME\n │ ├─ Route: /api/signals/..→ INTELLIGENCE\n │ ├─ Route: /api/memory/... → KNOWLEDGE\n │ ├─ Route: /api/govern/... → GOVERN\n │ ├─ Route: /mcp/tools/... → MCP-CONNECTOR\n │ └─ Route: /webhooks/... → WEBHOOK-INGRESS\n │\n └─ Unauthenticated ← No token or invalid\n │\n ├─ Route: /auth/signup → Supabase Auth (new user)\n ├─ Route: /auth/login → Supabase Auth (sign in)\n └─ Route: /public-demo → Demo page (no auth)\n\n┌────────────────────────────────────────────────────────────┐\n│ Zero-Trust Internal Routing │\n│ │\n│ All downstream workers communicate via Cloudflare │\n│ Service Bindings (internal, not exposed to internet) │\n│ │\n│ NORMALIZER → PIPELINE → INTELLIGENCE ↔ CONTINUITY │\n│ ↔ IW-AGENT-RUNTIME → GOVERN → WORKFLOW │\n│ ↔ KNOWLEDGE │\n│ │\n│ No worker is directly accessible from the public internet.│\n└────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 5. Frontend Layer Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ FRONTEND: Next.js 16 Layered UI │\n└──────────────────────────────────────────────────────────────┘\n\nUSER INTERACTS WITH SINGLE APP\n │\n ├─ LAYER SWITCHER (Sidebar)\n │ ├─ 🔵 Human (L1) - Your decisions & outcomes\n │ ├─ 🟣 AI (L3) - Twin reasoning & proposals\n │ ├─ 🟨 Collaborate (L2) - Joint approvals & memory\n │ └─ 🟢 Approve (L4) - Governance & audit\n │\n ├─ DATA PROJECTION CHANGES (No page reload)\n │\n └─ USER SEES DIFFERENT DATA LENS\n │\n ┌────────────┼────────────┬────────────┬────────────┐\n │ │ │ │ │\n ↓ ↓ ↓ ↓ ↓\n HUMAN L1 AI L3 COLLAB L2 GOVERN L4 MEMORY L4\n ┌───────┐ ┌──────┐ ┌────────┐ ┌─────────┐ ┌──────────┐\n │Workbench │Twin Chat │Approval │ │Governance│ │Memory │\n │(domain) │(reasoning)│Center │ │Dashboard │ │Search │\n │Goals │Proposals │Decisions│ │Audit Log │ │Documents │\n │Entities │Context │Outcomes │ │RLS Check │ │Sessions │\n │Timeline │Evidence │Feedback │ │Settings │ │Entities │\n │Signals │Traces │Credits │ │Compliance│ │History │\n └───────┘ └──────┘ └────────┘ └─────────┘ └──────────┘\n │ │ │ │ │\n └───────────┴───────────┴───────────┴───────────┘\n │\n ↓\n All query same SPINE backend\n But see different projections\n Based on layer context\n```\n\n---\n\n## 6. Approval & Execution Flow\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ GOVERNANCE & EXECUTION: HITL → Approval → Action │\n└─────────────────────────────────────────────────────────────┘\n\nUSER (L1) AI (L3) SYSTEM\n │ │ │\n ├─ Creates goal │ │\n │ (or task) │ │\n │ │ │\n └──────────────────────┬───────────────────────────┬─│\n │ │ │\n ├─ THINK analyzes goal │ │\n │ │ │\n ├─ IW-AGENT-RUNTIME │ │\n │ generates proposal │ │\n │ (actions, mutations, │ │\n │ success criteria) │ │\n │ │ │\n └─ Enqueues to GOVERN │ │\n ↓ │\n ┌─────────────────────────────────────────┐\n │ GOVERN (S9) - Approval Gate │\n │ Status: PENDING_REVIEW │\n │ Waits for human approval │\n │ (No execution authority) │\n └─────────────────────────────────────────┘\n │\n Human reviews │\n proposal in │\n L4 Approval │\n Center │\n │\n ┌────────────┴───────────┐\n │ │\n ✅ APPROVE ❌ REJECT\n │ │\n ↓ ↓\n ┌──────────────┐ ┌────────────┐\n │ Status: │ │ Status: │\n │ APPROVED │ │ REJECTED │\n │ │ │ │\n │ Logged in │ │ Reason │\n │ governance_ │ │ recorded │\n │ audit_log │ │ │\n └──────────────┘ │ Proposal │\n │ │ archived │\n ↓ └────────────┘\n ┌──────────────────┐\n │ WORKFLOW (S10) │\n │ Async execution │\n │ orchestration │\n │ │\n │ • Resolves target │\n │ • Prepares │\n │ handoff (JSON) │\n │ • Stages in queue │\n │ • Tracks state │\n └──────────────────┘\n │\n ├─ Local execution (user runs playbook)\n ├─ Slack action (send message)\n ├─ HubSpot update (create contact)\n ├─ Email (send notification)\n └─ Custom adapter (user's tool)\n │\n ↓\n ┌──────────────────┐\n │ Execution │\n │ feedback sent │\n │ back to system │\n │ as signals │\n └──────────────────┘\n │\n ↓\n Signals → INTELLIGENCE\n → CONTINUITY → MEMORY\n → Next cycle learning\n```\n\n---\n\n## 7. Deployment Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ DEPLOYMENT: Multi-Environment │\n└──────────────────────────────────────────────────────────────┘\n\nDEV (Localhost) TEST (Staging) PROD (Live)\n────────────── ────────────── ──────────\npnpm dev staging. app.\nlocalhost:3333 integratewise.ai integratewise.ai\n│ │ │\n├─ Local D1 mock ├─ Cloudflare D1 ├─ Cloudflare D1\n├─ Local Supabase ├─ Supabase ├─ Supabase\n├─ localhost:5432 │ (staging DB) │ Fortress (SSOT)\n│ PostgreSQL │ │\n└─ Hot reload ├─ All 28 workers ├─ All 28 workers\n enabled │ deployed │ deployed\n │ │\n ├─ Vercel preview ├─ Vercel prod\n │ (frontend) │ (frontend)\n │ │\n └─ Smoke tests run └─ Monitoring:\n - Sentry\n - Grafana\n - CF Analytics\n\n ┌─────────────────────────────────────────────┐\n │ Deployment Pipeline │\n │ │\n │ 1. Git push to branch │\n │ 2. GitHub Actions runs tests │\n │ 3. pnpm preflight (install, lint, build) │\n │ 4. Deploy to staging (CF Workers) │\n │ 5. Smoke tests run │\n │ 6. PR ready for review │\n │ 7. Merge to main │\n │ 8. Auto-deploy to production │\n │ 9. Monitor error rates (Sentry) │\n │ 10. Monitor latency (Grafana) │\n └─────────────────────────────────────────────┘\n```\n\n---\n\n## 8. Multi-Tenancy & Isolation\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ MULTI-TENANCY: Per-Tenant Isolation │\n└──────────────────────────────────────────────────────────────┘\n\nINTEGRATEWISE SYSTEM\n │\n ├─ Tenant A (Acme Corp)\n │ │\n │ ├─ D1 partitions\n │ │ ├─ person_data (ACL: acme corp only)\n │ │ ├─ account_data\n │ │ ├─ opportunity_data\n │ │ └─ [domain partitions]\n │ │\n │ ├─ Supabase RLS policies\n │ │ ├─ tenant_id = 'acme-corp'\n │ │ ├─ All queries filtered\n │ │ └─ No cross-tenant access\n │ │\n │ ├─ Memory\n │ │ ├─ org_memory (Acme Corp level)\n │ │ ├─ personal_memory (User Alice)\n │ │ └─ conversational_memory (Twin sessions)\n │ │\n │ ├─ RBAC rules\n │ │ ├─ Alice: admin\n │ │ ├─ Bob: analyst\n │ │ └─ Charlie: viewer\n │ │\n │ └─ All 28 services scope to tenant_id\n │\n ├─ Tenant B (BigTech Inc)\n │ │\n │ ├─ D1 partitions\n │ │ ├─ person_data (BTI: bigtechinc.com only)\n │ │ ├─ account_data\n │ │ ├─ opportunity_data\n │ │ └─ [domain partitions]\n │ │\n │ ├─ Supabase RLS policies\n │ │ ├─ tenant_id = 'bigtechinc'\n │ │ ├─ All queries filtered\n │ │ └─ No cross-tenant access\n │ │\n │ ├─ Memory\n │ │ ├─ org_memory (BigTech Inc level)\n │ │ ├─ personal_memory (User Diana)\n │ │ └─ conversational_memory (Twin sessions)\n │ │\n │ ├─ RBAC rules\n │ │ ├─ Diana: admin\n │ │ └─ Eve: analyst\n │ │\n │ └─ All 28 services scope to tenant_id\n │\n └─ [100+ more tenants] ← Independent, never mixed\n\nKEY INVARIANT: Every query includes tenant_id scoping\n At database layer (RLS)\n At worker layer (scoped queries)\n At API layer (user auth → tenant)\n No data leakage between tenants\n```\n\n---\n\n## 9. Observability & Monitoring\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ OBSERVABILITY: Cloud-First Audit Trail │\n└──────────────────────────────────────────────────────────────┘\n\nALL 28 WORKERS emit to\n │\n ├─ D1 Tables\n │ ├─ audit_logs (all actions)\n │ ├─ governance_audit_log (approvals)\n │ ├─ spine_audit_log (entity writes)\n │ └─ webhook_deliveries (webhook status)\n │\n ├─ Supabase\n │ ├─ usage_logs (API usage)\n │ ├─ billing_events (charges)\n │ └─ support_tickets (customer issues)\n │\n ├─ Sentry (Errors)\n │ ├─ 5xx errors\n │ ├─ 4xx errors\n │ ├─ LLM failures\n │ └─ Database timeouts\n │\n ├─ Grafana (Metrics)\n │ ├─ P95 latency per worker\n │ ├─ Error rates\n │ ├─ Memory usage\n │ ├─ Database query time\n │ └─ Worker CPU/memory\n │\n ├─ Cloudflare Analytics\n │ ├─ Requests/sec\n │ ├─ Cache hit ratio\n │ ├─ Worker performance\n │ └─ DDoS events\n │\n └─ Custom Telemetry\n ├─ LLM cost tracking\n ├─ Vector search latency\n ├─ Continuity lifecycle duration\n └─ Approval SLA (target: <1min)\n\nNO LOCAL LOGGING\nEvery action logged to cloud (100% audit trail)\n```\n\n---\n\nThis document provides visual representation of the complete IntegrateWise system architecture across all dimensions (data flow, services, frontend, multi-tenancy, monitoring).\n"}