{"slug":"strategy/product-strategy/README_ARCHITECTURE_2.0","title":"IntegrateWise Architecture 2.0 — Documentation Guide","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/README_ARCHITECTURE_2.0.mdx","bytes":12859,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Version:** 2.0  \n**Date:** 2026-06-09  \n**Status:** Canonical\n\n---\n\n## 🎯 Start Here\n\n**If you're new or returning after a break, read these in order:**\n\n### 1. **The System Statement** (30 seconds)\n\n```\nOne Twin                    = Persistent cognitive orchestrator\nOne Spine                   = Operational truth substrate\nOne Memory                  = Institutional knowledge\nOne Governance Layer        = HITL approval gate\nOne Bridge                  = MCP + ADK communication layer\n\nMany Interfaces             = OWUI, Voice, API, CLI, Email, Mobile\nMany Execution Providers    = APIs, Browser, MCP, Workflows, Human\n\nInfinite Capabilities       = Business outcomes\n```\n\n### 2. **Master Architecture** (15 minutes)\n\n📄 `docs/tech/INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`\n\nThis is THE definitive architecture document. Read this first.\n\n### 3. **Architecture Update** (5 minutes)\n\n📄 `docs/ARCHITECTURE_UPDATE_2026-06-09.md`\n\nWhat changed today, why it matters, what's next.\n\n---\n\n## 📚 Core Architecture Documents\n\n### **Foundation Layer**\n\n| Document                                  | Purpose             | When to Read           |\n| ----------------------------------------- | ------------------- | ---------------------- |\n| `INTEGRATEWISE_CANONICAL_ARCHITECTURE.md` | Master architecture | Always start here      |\n| `ARCHITECTURE_UPDATE_2026-06-09.md`       | What changed today  | After master doc       |\n| `INTEGRATEWISE_PRODUCT_ARCHITECTURE.md`   | Legacy product doc  | For historical context |\n\n### **Twin Layer**\n\n| Document                            | Purpose              | When to Read         |\n| ----------------------------------- | -------------------- | -------------------- |\n| `TWIN_AS_COGNITIVE_ORCHESTRATOR.md` | Twin Runtime details | Building Twin        |\n| `TWIN_VOICE_INTERFACE.md`           | Voice integration    | Adding voice         |\n| `TWIN_BROWSER_EXECUTION.md`         | Browser automation   | Adding browser agent |\n\n### **Memory Layer**\n\n| Document                        | Purpose                 | When to Read            |\n| ------------------------------- | ----------------------- | ----------------------- |\n| `MEMORY_GOVERNANCE_DOCTRINE.md` | Memory write rules      | Understanding memory    |\n| `memory-pipeline-episode.json`  | Book of Records episode | Example format          |\n| `triage-output-schema.ts`       | TypeScript schema       | Implementing Triage Bot |\n| `owui-skill-manifest.md`        | Skills documentation    | Wiring OWUI to Twin     |\n\n### **Data Layer**\n\n| Document                                       | Purpose            | When to Read           |\n| ---------------------------------------------- | ------------------ | ---------------------- |\n| `ENTITY_BINDING_AND_RELATIONSHIPS.md`          | Spine architecture | Understanding entities |\n| `MCP_ADK_ROUTING_SPINE_MEMORY_ARCHITECTURE.md` | MCP + ADK          | Building integrations  |\n\n### **Product Layer**\n\n| Document                              | Purpose           | When to Read           |\n| ------------------------------------- | ----------------- | ---------------------- |\n| `LAYER_OWNERSHIP_AND_TWIN_RUNTIME.md` | S/U/V/CZ layers   | Understanding surfaces |\n| `FRONTEND_LAYER_MAP.md`               | Frontend surfaces | Building UI            |\n| `CANONICAL_TAXONOMY.md`               | Terminology       | Learning the language  |\n\n---\n\n## 🔑 Key Concepts\n\n### **ONE TWIN**\n\nThe Twin is **NOT:**\n\n- ❌ A chatbot\n- ❌ A UI (OWUI)\n- ❌ A model (Grok-4.3)\n- ❌ A profile (Hermes/Think/Fast)\n\nThe Twin **IS:**\n\n- ✅ Persistent cognitive orchestrator\n- ✅ Always-on (every 5 minutes, 24/7)\n- ✅ Observes system state\n- ✅ Reasons via OpenRouter Agents\n- ✅ Proposes governed actions\n- ✅ Coordinates execution\n- ✅ Monitors outcomes\n- ✅ Learns via Triage Bot\n\n**Location:**\n\n- VPS (dev): `twin-runtime.operations.integratewise.ai`\n- CF Worker (prod): `services/twin-orchestrator/`\n\n---\n\n### **ONE SPINE**\n\n**What:** Canonical entity graph across all tools\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, stall, status change)\n- Weak signals (anomalies, patterns, predictions)\n\n**Writer:** Pipeline service (SOLE writer)\n\n**Readers:** MCP tools, Twin, ADK\n\n**The Moat:** 30+ connectors normalized into one graph\n\n---\n\n### **ONE MEMORY**\n\n**Format:** Book of Records (6 primitives)\n\n1. Episode — Time-bounded chapter\n2. Decision — Explicit choice + rationale\n3. Learning — Takeaway for future work\n4. Commitment — What we agreed to do\n5. Fact — Verifiable institutional fact\n6. Action Item — What needs addressing\n\n**Writer:** Triage Bot ONLY (no direct writes)\n\n**Storage:**\n\n- Conversational Memory (staging book, 90 days TTL)\n- Org Memory (promoted, permanent)\n- Personal Memory (user-scoped, 90 days TTL)\n\n**Flow:**\n\n```\nAI Worker → AI Worker → Triage Bot → Conversational Memory\n                                            ↓\n                        ┌───────────────────┼───────────────────┐\n                        ↓                   ↓                   ↓\n                  Search Index      Governance Queue    Promotion Queue\n                   (auto)              (review)            (review)\n                                                               ↓\n                                                          Org Memory\n                                                          (approved)\n```\n\n---\n\n### **ONE GOVERNANCE LAYER**\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**Rules:**\n\n- Read operations: No approval\n- Write operations: Always approval\n- High-risk actions: Require justification\n- Browser automation: Requires step review\n\n---\n\n### **ONE BRIDGE**\n\n**MCP (Model Context Protocol):**\n\n- 20 canonical tools\n- OAuth 2.0 (RS256 JWT)\n- Server: https://mcp.integratewise.ai\n\n**ADK (Application Development Kit):**\n\n- REST APIs (gateway.integratewise.ai)\n- TypeScript SDK (@integratewise/sdk)\n- React hooks (@integratewise/react)\n- Webhooks (webhook-ingress)\n\n---\n\n### **MANY INTERFACES**\n\nAll interfaces reach the **same Twin Runtime:**\n\n1. **OWUI (Chat)** — twin.integratewise.ai\n2. **Voice (Speak)** — x.ai STT + TTS\n3. **API (Programmatic)** — twin.dev.integratewise.ai/v1/chat/completions\n4. **CLI (Terminal)** — iw twin ask \"...\" (planned)\n5. **Email (Async)** — twin@integratewise.ai (planned)\n6. **Mobile (App)** — iOS + Android (planned)\n\n---\n\n### **MANY EXECUTION PROVIDERS**\n\nTwin proposes, Governance approves, Act dispatches:\n\n1. **APIs** — HubSpot, Jira, Salesforce, Gmail, Slack, etc.\n2. **Browser Agent** — Playwright (VPS) + Puppeteer (CF)\n3. **MCP Tools** — 20 canonical tools\n4. **Workflows** — CF Workflows (durable execution)\n5. **Human Tasks** — Manual workflows (L2 UI)\n6. **Webhooks** — Outbound notifications\n\n---\n\n## 🏗️ Implementation Status\n\n### ✅ **Deployed (Production)**\n\n- Spine (entity resolution, relationships, signals)\n- Pipeline (sole Spine writer)\n- MCP OAuth 2.0 (20 tools)\n- Governance (proposals, HITL, audit)\n- Act (execution coordination)\n- Memory tables (org, conversational, personal)\n- OWUI (chat + voice)\n- Intelligence worker\n\n### 🚧 **Designed (Ready for Implementation)**\n\n- Twin Runtime (VPS deployment planned)\n- Triage Bot (schema complete)\n- Browser Agent (VPS deployment planned)\n- Skills (YAML manifests created)\n\n### 📋 **Planned (Next Phase)**\n\n- Twin Runtime → CF Worker migration\n- CLI interface\n- Email interface\n- Mobile app\n- TTL job (memory aging)\n- Publication worker\n\n---\n\n## 🚀 Quick Start Guides\n\n### **For Developers Building Custom Surfaces**\n\n1. Read: `INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`\n2. Read: `MCP_ADK_ROUTING_SPINE_MEMORY_ARCHITECTURE.md`\n3. Use: ADK REST APIs or TypeScript SDK\n4. Query: Spine entities, Memory, Signals\n5. Build: Custom L1 views\n\n### **For Developers Extending Twin**\n\n1. Read: `TWIN_AS_COGNITIVE_ORCHESTRATOR.md`\n2. Read: `owui-skill-manifest.md`\n3. Create: New MCP tool\n4. Define: Skill YAML (when to use, inputs, outputs)\n5. Test: Via OWUI\n\n### **For Developers Building Execution Providers**\n\n1. Read: `TWIN_BROWSER_EXECUTION.md`\n2. Implement: Execution provider (API, browser, MCP, etc.)\n3. Wire: To Act service\n4. Test: Proposal → Approval → Execution\n5. Verify: Outcome recorded via Triage Bot\n\n### **For AI Agents Connecting via MCP**\n\n1. Read: `MCP_ADK_ROUTING_SPINE_MEMORY_ARCHITECTURE.md`\n2. OAuth: Connect to mcp.integratewise.ai\n3. Discover: 20 canonical tools\n4. Use: SPINE._, MEMORY._, PROPOSAL._, KB._ tools\n5. Respect: Governance (propose, don't execute)\n\n---\n\n## 🎓 Learning Path\n\n### **Week 1: Understand the System**\n\n- Day 1: Read `INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`\n- Day 2: Read `ARCHITECTURE_UPDATE_2026-06-09.md`\n- Day 3: Read `TWIN_AS_COGNITIVE_ORCHESTRATOR.md`\n- Day 4: Read `MEMORY_GOVERNANCE_DOCTRINE.md`\n- Day 5: Read `ENTITY_BINDING_AND_RELATIONSHIPS.md`\n\n### **Week 2: Build Something**\n\n- Day 1-2: Query Spine via MCP tools\n- Day 3-4: Build custom L1 view\n- Day 5: Create proposal workflow\n\n### **Week 3: Extend the Twin**\n\n- Day 1-2: Create new MCP tool\n- Day 3-4: Define skill YAML\n- Day 5: Test via OWUI\n\n---\n\n## 📖 Glossary\n\n| Term                | Definition                                                                |\n| ------------------- | ------------------------------------------------------------------------- |\n| **Twin**            | Persistent cognitive orchestrator (not a chatbot)                         |\n| **Spine**           | Canonical entity graph across all tools                                   |\n| **Memory**          | Institutional knowledge (Book of Records format)                          |\n| **Triage Bot**      | Sole memory writer (Book of Records format)                               |\n| **Book of Records** | 6 primitives (episode, decision, learning, commitment, fact, action_item) |\n| **MCP**             | Model Context Protocol (20 tools, OAuth 2.0)                              |\n| **ADK**             | Application Development Kit (REST APIs, SDK, webhooks)                    |\n| **OWUI**            | Open WebUI (ONE interface to Twin, not the Twin itself)                   |\n| **Voice**           | x.ai STT + TTS (ONE interface to Twin)                                    |\n| **Browser Agent**   | Playwright automation (ONE execution provider)                            |\n| **Governance**      | HITL approval gate (proposal → review → approve/reject)                   |\n| **Act**             | Execution coordinator (dispatches to providers)                           |\n| **Pipeline**        | Sole Spine writer (8-stage normalizer)                                    |\n| **Entity 360**      | Complete context view for an entity                                       |\n| **Signal**          | Entity change event (health drop, stall, anomaly)                         |\n| **Proposal**        | Governed action (Twin proposes, human approves)                           |\n\n---\n\n## 🔗 External Resources\n\n- **Live System:** https://twin.operations.integratewise.ai\n- **MCP Server:** https://mcp.integratewise.ai\n- **API Gateway:** https://gateway.integratewise.ai\n- **Docs:** https://docs.integratewise.ai\n\n---\n\n## 📞 Getting Help\n\n### **For Architecture Questions**\n\nRead: `INTEGRATEWISE_CANONICAL_ARCHITECTURE.md` first\n\n### **For Memory Questions**\n\nRead: `MEMORY_GOVERNANCE_DOCTRINE.md`\n\n### **For Twin Questions**\n\nRead: `TWIN_AS_COGNITIVE_ORCHESTRATOR.md`\n\n### **For Implementation Questions**\n\nRead: `ARCHITECTURE_UPDATE_2026-06-09.md` (what's ready, what's planned)\n\n---\n\n## ✅ Before You Start Building\n\n**Checklist:**\n\n- [ ] Read `INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`\n- [ ] Understand: One Twin, One Spine, One Memory, One Governance, One Bridge\n- [ ] Know: Many Interfaces, Many Execution Providers, Infinite Capabilities\n- [ ] Understand: Twin ≠ OWUI ≠ Voice ≠ Browser Agent\n- [ ] Understand: Memory writes via Triage Bot ONLY\n- [ ] Understand: Proposals require HITL approval\n- [ ] Know where to find: MCP tools, ADK APIs, TypeScript SDK\n- [ ] Know the hierarchy: Canonical Architecture → Domain Docs → Implementation Guides\n\n---\n\n**Last Updated:** 2026-06-09  \n**Version:** 2.0  \n**Status:** Canonical\n\n**This is IntegrateWise 2.0.**\n\nOne Twin. One Spine. One Memory. One Governance. One Bridge.\nMany Interfaces. Many Execution Providers. Infinite Capabilities.\n"}