{"slug":"internal/architecture/INTEGRATEWISE_CANONICAL_ARCHITECTURE","title":"IntegrateWise — Canonical Architecture","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/INTEGRATEWISE_CANONICAL_ARCHITECTURE.mdx","bytes":24520,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Version:** 2.0\n**Date:** 2026-06-09\n**Status:** Approved\n**Authority:** Founder + Architecture Team\n\n---\n\n## The System Statement\n\n```\nOne Twin\nOne Spine\nOne Memory\nOne Governance Layer\nOne Bridge\n\nMany Interfaces\nMany Execution Providers\n\nInfinite Capabilities\n```\n\n---\n\n## Architecture Diagram\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ ONE TWIN │\n│ (Persistent Cognitive Orchestrator) │\n│ │\n│ Observe → Reason → Propose → Coordinate → Monitor → Learn │\n│ │\n│ Runtime: CF Worker (services/twin-orchestrator/) │\n│ Frequency: Every 5 minutes (cron) │\n│ Reasoning: OpenRouter Agents (multi-model deliberation) │\n│ Memory: Book of Records (via Triage Bot) │\n└───────────────────────────┬─────────────────────────────────────┘\n │\n ┌───────────────────┼───────────────────┐\n │ │ │\n ▼ ▼ ▼\n┌───────────────┐ ┌───────────────┐ ┌───────────────┐\n│ ONE SPINE │ │ ONE MEMORY │ │ ONE GOVERNANCE│\n│ │ │ │ │ LAYER │\n│ Entities │ │ Org Memory │ │ │\n│ Relationships │ │ Conversational│ │ Proposals │\n│ Signals │ │ Personal │ │ HITL │\n│ Entity 360 │ │ Sessions │ │ Policy │\n│ │ │ │ │ Audit │\n└───────┬───────┘ └───────┬───────┘ └───────┬───────┘\n │ │ │\n └───────────────────┼───────────────────┘\n │\n ▼\n ┌───────────────┐\n │ ONE BRIDGE │\n │ │\n │ MCP Protocol │\n │ 20 Tools │\n │ OAuth 2.0 │\n │ ADK/SDK │\n │ │\n └───────┬───────┘\n │\n ┌───────────────────┼───────────────────┐\n │ │ │\n ▼ ▼ ▼\n┌───────────────────────────────────────────────────────┐\n│ MANY INTERFACES │\n├───────────────┬───────────────┬───────────────────────┤\n│ OWUI (chat) │ Voice (speak) │ API (programmatic) │\n│ CLI (term) │ Email (async) │ Mobile (app) │\n└───────────────┴───────────────┴───────────────────────┘\n │\n ▼\n ┌───────────────┐\n │ GOVERNANCE │\n │ (HITL Gate) │\n └───────┬───────┘\n │\n ▼\n┌───────────────────────────────────────────────────────┐\n│ MANY EXECUTION PROVIDERS │\n├───────────────┬───────────────┬───────────────────────┤\n│ APIs │ Browser Agent │ MCP Tools │\n│ (HubSpot, │ (Playwright) │ (18 canonical) │\n│ Jira, etc.) │ │ │\n├───────────────┼───────────────┼───────────────────────┤\n│ Workflows │ Human Tasks │ Webhooks │\n│ (Durable) │ (Manual) │ (Events) │\n└───────────────┴───────────────┴───────────────────────┘\n │\n ▼\n ┌───────────────┐\n │ OUTCOMES │\n │ (Results) │\n └───────┬───────┘\n │\n ▼\n ┌───────────────────┐\n │ TRIAGE BOT │\n │ (Book of Records) │\n └───────┬───────────┘\n │\n ▼\n ┌───────────────────┐\n │ CONVERSATIONAL │\n │ MEMORY │\n │ (Staging Book) │\n └───────┬───────────┘\n │\n ┌───────────────────┼───────────────────┐\n │ │ │\n ▼ ▼ ▼\n┌──────────────┐ ┌──────────────┐ ┌──────────────┐\n│ Search Index │ │ Promotion │ │ Org Memory │\n│ (Auto) │ │ Queue (HITL) │ │ (Approved) │\n└──────────────┘ └──────────────┘ └──────┬───────┘\n │\n ▼\n ┌──────────────┐\n │ Surface │\n │ Projection │\n │ │\n │ - OWUI KB │\n │ - Book Proj │\n │ - Evolution │\n └──────────────┘\n```\n\n---\n\n## ONE TWIN\n\n**What:** The persistent cognitive orchestrator\n\n**Role:** Observe, reason, propose, coordinate, monitor, learn\n\n**Implementation:**\n\n```\nLocation: services/twin-orchestrator/\nRuntime: Cloudflare Worker\nTrigger: Cron (every 5 minutes)\nReasoning: OpenRouter Agents (ecosystem agent)\nMemory: Book of Records (via Triage Bot)\n```\n\n**Core Loop:**\n\n```typescript\nasync function scheduled(event: ScheduledEvent, env: Env) {\n // 1. Observe\n const context = await buildTwinContext(env, tenantId);\n\n // 2. Reason\n const reasoning = await reasonAboutContext(env, context);\n\n // 3. Propose\n if (reasoning.suggested_actions.length > 0) {\n await generateProposals(env, reasoning, tenantId);\n }\n\n // 4. Coordinate\n await coordinateApprovedActions(env, tenantId);\n\n // 5. Monitor\n await monitorOutcomes(env, tenantId);\n\n // 6. Learn (via Triage Bot)\n // Outcomes written to conversational_memory\n}\n```\n\n**Characteristics:**\n\n- Always-on (24/7, every 5 minutes)\n- Proactive (observes without being asked)\n- Deliberative (multi-model reasoning)\n- Cautious (proposes, never executes directly)\n- Persistent (all outcomes recorded)\n- Learning (improves over time)\n\n---\n\n## ONE SPINE\n\n**What:** The operational truth substrate\n\n**Role:** Canonical entity graph across all tools\n\n**Implementation:**\n\n```\nStorage: D1 (edge cache) + Supabase (fortress)\nWriter: Pipeline service (SOLE writer)\nReaders: MCP tools, Twin, ADK\nSchema: Entities, Relationships, Signals, Entity 360\n```\n\n**Entities:**\n\n- Person, Account, Deal, Task, Ticket, Invoice, Project, Email, Event, Document\n\n**Relationships:**\n\n- works_at, owns, assigned_to, related_to, reports_to, manages, created_by\n\n**Signals:**\n\n- Entity changes (health drop, activity stall, status change)\n- Weak signals (anomalies, patterns, predictions)\n- Severity: low, medium, high, critical\n\n**Entity Resolution:**\n\n- One Person across HubSpot + Jira + Gmail + Slack\n- Trait detection (18 core traits)\n- Resource type mapping (7 canonical types)\n- Identity by nature, not label\n\n**The Moat:**\n\n- 30+ connectors normalized into one graph\n- Relationship tracking across disconnected tools\n- Signal detection at entity level\n- Time-series history (all changes tracked)\n- Entity 360 views (all context in one place)\n\n---\n\n## ONE MEMORY\n\n**What:** The institutional knowledge substrate\n\n**Role:** What the organization knows and remembers\n\n**Implementation:**\n\n```\nStorage: Supabase (org, conversational, personal memory)\nWriter: Triage Bot (SOLE writer for conversational)\nFormat: Book of Records\nPromotion: Human-governed only\n```\n\n**Memory Types:**\n\n### Conversational Memory (Staging Book)\n\n- Written by: Triage Bot only\n- Format: Book of Records (episode, decision, learning, commitment, fact, action_item)\n- Scope: user | work | org\n- TTL: 90 days (decisions: 30 days)\n- Auto-indexed for search\n\n### Org Memory (Institutional Knowledge)\n\n- Written by: Promotion from conversational (human-approved only)\n- Format: Book of Records (approved entries)\n- Scope: org only\n- TTL: Never (permanent)\n- Projects to surfaces (OWUI Knowledge, Book of Projects, Evolution)\n\n### Personal Memory\n\n- Written by: Triage Bot (user-scoped)\n- Format: Preferences, patterns, context\n- Scope: user only\n- TTL: 90 days (unless referenced)\n\n**Book of Records Primitives:**\n\n1. **Episode** — Time-bounded chapter (decisions, learnings, commitments)\n2. **Decision** — Explicit choice + rationale + alternatives\n3. **Learning** — Takeaway for future work\n4. **Commitment** — What we agreed to do (owner, action, deadline)\n5. **Fact** — Verifiable institutional fact (source, confidence)\n6. **Action Item** — What needs addressing (urgency, assigned_to)\n\n**The Doctrine:**\n\n- NO direct writes (all via Triage Bot)\n- Search is parallel (immediate indexing)\n- Promotion is human-only (never auto-promoted)\n- TTL rules (decisions age faster: 30 days)\n\n---\n\n## ONE GOVERNANCE LAYER\n\n**What:** The approval and policy substrate\n\n**Role:** Human-in-the-loop gate for all execution\n\n**Implementation:**\n\n```\nLocation: services/intelligence/src/govern/\nUI: L2 Awareness (Governance queue)\nStorage: D1 (proposals, approvals, audit log)\n```\n\n**Flow:**\n\n```\nTwin → Propose\n ↓\nGovernance Queue (proposal created)\n ↓\nHuman Reviews (L2 UI)\n ↓\nApprove or Reject\n ↓ (if approved)\nAct Service → Execute\n ↓\nTriage Bot → Record outcome\n```\n\n**Proposal Schema:**\n\n```typescript\n{\n tenant_id: string;\n action_type: string;\n target: { entity_id?, url?, tool? };\n reasoning: string;\n impact: 'low' | 'medium' | 'high';\n risk: 'low' | 'medium' | 'high';\n urgency: 'low' | 'medium' | 'high';\n confidence: number;\n status: 'pending' | 'approved' | 'rejected' | 'executed';\n created_by: 'twin-orchestrator';\n reviewed_by?: string;\n executed_at?: string;\n}\n```\n\n**Policy Engine:**\n\n- Read operations: No approval\n- Write operations: Always approval\n- High-risk actions: Require justification\n- Browser automation: Requires step review\n- Entity creation: Requires data validation\n\n**Audit Trail:**\n\n- Every proposal logged\n- Every approval logged\n- Every execution logged\n- Every outcome logged\n- Full lineage (proposal → approval → execution → outcome)\n\n---\n\n## ONE BRIDGE\n\n**What:** The communication and extensibility layer\n\n**Role:** MCP + ADK for tool access and custom development\n\n**Implementation:**\n\n### MCP (Model Context Protocol)\n\n```\nServer: https://mcp.integratewise.ai\nOAuth 2.0: RS256 JWT, 1hr access, 30d refresh\nTools: 20 canonical tools\nScopes: mcp:tools, mcp:resources, tenant:read/write, memory:read/write\n```\n\n**20 Canonical Tools:**\n\n**MEMORY Namespace:**\n\n1. `memory.search` — Semantic search across memory\n2. `memory.propose_candidate` — Propose promotion to org memory\n3. `memory.write_conversational` — Write conversational event (via Triage Bot)\n4. `memory.read_conversational` — Read conversational memory\n\n**SESSION Namespace:** 5. `session.write_summary` — Write session summary (via Triage Bot)\n\n**SPINE Namespace:** 6. `spine.get_entity` — Fetch entity by ID 7. `spine.list_entities` — List entities by type 8. `spine.search_entities` — Search entities\n\n**SIGNAL Namespace:** 9. `signal.list` — List signals 10. `signal.create` — Create signal (via Pipeline)\n\n**PROPOSAL Namespace:** 11. `proposal.create` — Create governed proposal 12. `proposal.list` — List proposals 13. `proposal.approve` — Approve proposal (HITL only) 14. `proposal.reject` — Reject proposal (HITL only)\n\n**KB Namespace:** 15. `kb.search` — Search org memory 16. `kb.get_article` — Fetch article 17. `kb.write_article` — Write article (via Triage Bot promotion)\n\n**SEARCH Namespace:** 18. `search.semantic` — Semantic search across all memory\n\n**TOOL Namespace:** 19. `tool.execute` — Execute tool (browser, API, etc.) via Act service\n\n**OPS Namespace:** 20. `ops.read` — Read operations metrics\n\n### ADK (Application Development Kit)\n\n**REST APIs:**\n\n```\nGateway: https://gateway.integratewise.ai\nAuth: JWT (Firebase Auth or IntegrateWise OAuth)\nEndpoints: /api/v1/spine/*, /api/v1/memory/*, /api/v1/signals/*\nRate Limits: 1000 req/min per tenant\n```\n\n**TypeScript SDK:**\n\n```typescript\n\nconst iw = new IntegrateWise({ apiKey: \"...\" });\n\n// Query Spine\nconst entity = await iw.spine.getEntity(\"person-123\");\n\n// Query Memory\nconst results = await iw.memory.search(\"architecture decisions\");\n\n// Create Proposal\nconst proposal = await iw.proposals.create({\n action_type: \"create_entity\",\n target: { entity_type: \"Person\", name: \"John Doe\" },\n reasoning: \"User requested contact creation\",\n});\n```\n\n**React Hooks:**\n\n```typescript\n\nfunction AccountView({ accountId }) {\n const { entity, loading } = useEntity(accountId);\n const { proposals } = useProposals({ entity_id: accountId });\n\n return (\n
\n

{entity.name}

\n \n
\n );\n}\n```\n\n---\n\n## MANY INTERFACES\n\n**What:** Multiple ways to interact with the Twin\n\n**Principle:** All interfaces reach the same Twin Runtime\n\n### 1. OWUI (Chat)\n\n```\nURL: https://twin.integratewise.ai\nStack: Open WebUI + Agent Zero\nVoice: x.ai (Kokoro TTS + Whisper STT)\nModels: Grok-4.3 (primary), Hermes-internal (fallback)\nConnection: Twin Runtime API (/v1/chat/completions)\n```\n\n### 2. Voice (Speak)\n\n```\nSTT: x.ai Whisper (speech → text)\nProcessing: Twin Runtime API\nTTS: x.ai Kokoro \"eve\" (text → speech)\nMode: Hands-free, brief responses\n```\n\n### 3. API (Programmatic)\n\n```\nEndpoint: https://twin.dev.integratewise.ai/v1/chat/completions\nAuth: Bearer token (IntegrateWise OAuth)\nFormat: OpenAI-compatible\nUse Case: Custom integrations, automation\n```\n\n### 4. CLI (Terminal)\n\n```\nCommand: iw twin ask \"what's at risk?\"\nAuth: ~/.iw/credentials.json\nOutput: Structured (JSON) or pretty (table)\nUse Case: Scripts, automation, power users\n```\n\n### 5. Email (Async)\n\n```\nAddress: twin@integratewise.ai\nProcessing: Email → Twin Runtime → Response email\nMode: Async, threaded conversations\nUse Case: Daily briefs, status updates\n```\n\n### 6. Mobile (App)\n\n```\nPlatform: iOS + Android\nStack: React Native\nConnection: Twin Runtime API\nMode: On-the-go, push notifications\n```\n\n**All interfaces:**\n\n- Reach same Twin Runtime\n- Store in same Memory\n- Create same Proposals\n- Trigger same Governance\n- Record in same Audit Log\n\n---\n\n## MANY EXECUTION PROVIDERS\n\n**What:** Multiple ways to execute approved actions\n\n**Principle:** Twin proposes, Governance approves, Act dispatches, Providers execute\n\n### 1. APIs\n\n```\nProviders: HubSpot, Jira, Salesforce, Gmail, Slack, GitHub, etc.\nProtocol: REST API\nAuth: OAuth 2.0 (per connector)\nUse Case: Structured CRUD operations\n```\n\n### 2. Browser Agent (Playwright)\n\n```\nLocation: VPS (integratewise-ops/vps-operations-stack/browser-agent/)\nStack: Playwright + Express\nUse Case: Web forms, screenshots, data extraction (no API)\nGovernance: Always requires approval (high-risk)\n```\n\n### 3. MCP Tools\n\n```\nCount: 20 canonical tools\nProtocol: MCP (Model Context Protocol)\nAuth: OAuth 2.0 + service bindings\nUse Case: IntegrateWise-native operations\n```\n\n### 4. Workflows (Durable Execution)\n\n```\nPlatform: Cloudflare Workflows\nUse Case: Multi-step processes, retries, state management\nExamples: Morning brief, signal analysis, triage workflow\n```\n\n### 5. Human Tasks\n\n```\nPlatform: L2 Governance UI (manual task list)\nUse Case: Actions that require human judgment\nExamples: Complex approvals, relationship calls, strategic decisions\n```\n\n### 6. Webhooks\n\n```\nDirection: Outbound (notify external systems)\nUse Case: Trigger external workflows, send notifications\nExamples: Slack alerts, PagerDuty incidents, custom integrations\n```\n\n**All providers:**\n\n- Receive from Act service\n- Return outcomes\n- Outcomes flow to Triage Bot\n- Triage Bot writes to Memory\n- Twin monitors results\n\n---\n\n## INFINITE CAPABILITIES\n\n**What:** Unlimited business outcomes from composing the system\n\n**Examples:**\n\n### Proactive Account Management\n\n```\nSpine detects: Health score drop\nTwin reasons: Renewal risk\nTwin proposes: Create follow-up task\nHuman approves\nAPI executes: HubSpot task creation\nTriage Bot records: Task created + learning\n```\n\n### Voice-Initiated Entity Creation\n\n```\nUser speaks: \"Create contact for Jane Smith\"\nVoice STT → Twin Runtime\nTwin checks: Entity doesn't exist\nTwin proposes: Create Person entity\nHuman approves (L2)\nAPI executes: Pipeline → Spine write\nTriage Bot records: Entity created\nVoice TTS: \"Jane Smith created\"\n```\n\n### Browser Automation for Legacy Tools\n\n```\nTwin detects: Action needed in legacy tool (no API)\nTwin proposes: Browser automation (7 steps)\nHuman reviews steps\nBrowser Agent executes: Navigate, fill form, submit, screenshot\nTriage Bot records: Form submitted + screenshot\nTwin monitors: Success\n```\n\n### Daily Morning Brief\n\n```\nCron triggers: 7 AM every day\nTwin observes: Signals, proposals, at-risk items\nTwin compiles: Structured brief\nTwin delivers: Voice/Email/Chat\nTriage Bot records: Daily episode\n```\n\n### Knowledge Search & Promotion\n\n```\nUser asks: \"What did we decide about X?\"\nTwin searches: Org memory + conversational memory\nTwin responds: \"We decided Y because Z\"\nTwin detects: Reusable decision\nTwin proposes: Promote to org memory\nHuman approves\nTriage Bot promotes: Conversational → Org memory\n```\n\n### Multi-Step Workflow Orchestration\n\n```\nSignal detected: Deal stalled\nTwin reasons: Needs executive review\nTwin proposes: Workflow (notify → schedule → brief → track)\nHuman approves\nWorkflow executes: 4-step durable workflow\nTriage Bot records: Each step outcome\nTwin monitors: Workflow completion\n```\n\n**The Pattern:**\n\n```\nObserve (Spine/Memory/Operations)\n ↓\nReason (Twin + OpenRouter Agents)\n ↓\nPropose (Governed action)\n ↓\nApprove (HITL)\n ↓\nExecute (Providers)\n ↓\nRecord (Triage Bot → Memory)\n ↓\nLearn (Next observation improves)\n```\n\n---\n\n## THE VALUE PROPOSITION\n\n### For Businesses\n\n- Proactive operations (Twin observes 24/7)\n- Cross-tool intelligence (Spine unifies all tools)\n- Governed AI execution (HITL gate prevents mistakes)\n- Institutional memory (learns and improves)\n\n### For Developers\n\n- Build custom surfaces (ADK + React hooks)\n- Extend Twin capabilities (MCP tools)\n- Query normalized data (Spine API)\n- Rapid development (hours, not months)\n\n### For AI Agents\n\n- Access cross-tool context (MCP OAuth)\n- Execute governed actions (Propose → Approve → Execute)\n- Learn from outcomes (Triage Bot records)\n- Persistent memory (sessions + institutional knowledge)\n\n---\n\n## THE MOAT\n\n| Component | Replaceability | Strength |\n| -------------- | -------------- | --------------- |\n| **Spine** | Impossible | ██████████ 100% |\n| **Twin** | Hard | ████████░░ 80% |\n| **Memory** | Hard | █████████░ 90% |\n| **Governance** | Medium | ███████░░░ 70% |\n| **Bridge** | Medium | ██████░░░░ 60% |\n| **Interfaces** | Easy | ████░░░░░░ 40% |\n| **Execution** | Easy | ███░░░░░░░ 30% |\n\n**The Spine is the moat.**\n\n- 30+ connectors normalized\n- Entity resolution across all tools\n- Relationship graph (exists nowhere else)\n- Signal detection at entity level\n- 5 years of connector development\n- 18 traits × 7 resource types\n\n**The Twin makes it intelligent.**\n\n- Persistent orchestration\n- Multi-model reasoning\n- Governed execution\n- Continuous learning\n\n**Together = Unbeatable.**\n\n---\n\n## THE SYSTEM STATEMENT\n\n```\nOne Twin = Cognitive orchestrator (reasoning)\nOne Spine = Operational truth (data)\nOne Memory = Institutional knowledge (learning)\nOne Governance = Approval layer (HITL)\nOne Bridge = Communication protocol (MCP + ADK)\n\nMany Interfaces = Chat, Voice, API, CLI, Email, Mobile\nMany Execution Providers = APIs, Browser, MCP, Workflows, Human Tasks\n\nInfinite Capabilities = Observe + Reason + Execute + Learn = Business Value\n```\n\n---\n\n## IMPLEMENTATION STATUS\n\n### ✅ Complete\n\n- Spine (entity resolution, relationships, signals)\n- Pipeline (sole Spine writer)\n- MCP OAuth 2.0 (20 tools, mcp.integratewise.ai)\n- Governance (proposals, HITL, audit)\n- Act (execution coordination)\n- Memory tables (org, conversational, personal)\n- OWUI (chat + voice via x.ai)\n\n### 🚧 In Progress\n\n- Twin Runtime (designed, needs deployment)\n- Triage Bot (schema defined, needs implementation)\n- Browser Agent (VPS, designed, needs deployment)\n- Skills (OWUI, manifest created, needs loading)\n\n### 📋 Planned\n\n- CLI interface\n- Email interface\n- Mobile app\n- TTL job (memory aging)\n- Publication worker (org memory → surfaces)\n\n---\n\n## FILES\n\n- **This document:** `docs/tech/INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`\n- **Twin Runtime:** `services/twin-orchestrator/`\n- **Memory Doctrine:** `docs/tech/MEMORY_GOVERNANCE_DOCTRINE.md`\n- **Triage Schema:** `.iw-memory/specs/twin-owui/triage-output-schema.ts`\n- **Skills Manifest:** `.iw-memory/specs/twin-owui/owui-skill-manifest.md`\n- **Episode:** `.iw-memory/specs/twin-owui/memory-pipeline-episode.json`\n\n---\n\n**Approved: 2026-06-09**\n**Authority: Founder + Architecture Team**\n**Status: Canonical — all implementations must align**\n\n---\n\n**This is IntegrateWise.**\n\nOne Twin. One Spine. One Memory. One Governance. One Bridge.\nMany Interfaces. Many Execution Providers.\nInfinite Capabilities.\n"}