{"slug":"strategy/product-strategy/ARCHITECTURE_UPDATE_2026-06-09","title":"Architecture Update — 2026-06-09","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/ARCHITECTURE_UPDATE_2026-06-09.mdx","bytes":12052,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Canonical Architecture Finalized  \n**Authority:** Founder + Architecture Team  \n**Version:** 2.0\n\n---\n\n## What Changed Today\n\n### **New Canonical Statement**\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---\n\n## Major Architecture Documents Created\n\n### **1. Master Architecture**\n\n**File:** `docs/tech/INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`  \n**Purpose:** THE definitive architecture document  \n**Status:** Approved, canonical\n\n**Key Sections:**\n\n- One Twin (cognitive orchestrator)\n- One Spine (operational truth)\n- One Memory (Book of Records format)\n- One Governance Layer (HITL gate)\n- One Bridge (MCP + ADK)\n- Many Interfaces (OWUI, Voice, API, CLI, Email, Mobile)\n- Many Execution Providers (APIs, Browser, MCP, Workflows, Human)\n- Infinite Capabilities (business outcomes)\n\n---\n\n### **2. Memory Governance Doctrine**\n\n**File:** `docs/tech/MEMORY_GOVERNANCE_DOCTRINE.md`  \n**Purpose:** How memory is written (Triage Bot only)  \n**Status:** Approved, canonical\n\n**Key Rules:**\n\n1. NO direct memory writes (all via Triage Bot)\n2. Conversational memory is staging book (Book of Records format)\n3. Search is parallel (immediate indexing)\n4. Promotion is human-only (never auto-promoted)\n5. Org memory projects to surfaces (OWUI Knowledge, Book of Projects)\n6. Decision TTL: 30 days (vs 90 days for general conversational)\n7. Twin wiring is read-heavy (reads memory, proposes writes)\n\n---\n\n### **3. Twin as Cognitive Orchestrator**\n\n**File:** `docs/tech/TWIN_AS_COGNITIVE_ORCHESTRATOR.md` (updated)  \n**Purpose:** Twin Runtime details  \n**Status:** Approved, canonical\n\n**Key Points:**\n\n- Twin = Persistent cognitive orchestrator (NOT a chatbot)\n- Runtime: CF Worker or VPS (services/twin-orchestrator/)\n- Core Loop: Observe → Reason → Propose → Coordinate → Monitor → Learn\n- Reasoning: OpenRouter Agents (multi-model deliberation)\n- Memory: Book of Records (via Triage Bot)\n- Governance: Propose → HITL → Approve → Execute\n\n---\n\n### **4. Twin Voice Interface**\n\n**File:** `docs/tech/TWIN_VOICE_INTERFACE.md`  \n**Purpose:** Voice as interface to Twin Runtime  \n**Status:** Approved, canonical\n\n**Key Points:**\n\n- Voice = ONE interface to Twin (not the Twin itself)\n- Stack: x.ai STT (Whisper) + x.ai TTS (Kokoro \"eve\")\n- Connection: Voice → OWUI → Twin Runtime → OpenRouter → Response\n- Capabilities: Morning briefs, action proposals, voice commands\n- Voice-optimized responses (brief, clear, conversational)\n\n---\n\n### **5. Twin Browser Execution**\n\n**File:** `docs/tech/TWIN_BROWSER_EXECUTION.md`  \n**Purpose:** Browser Agent as execution provider  \n**Status:** Approved, canonical\n\n**Key Points:**\n\n- Browser Agent = Execution provider (NOT Twin itself)\n- Stack: Playwright (VPS) + Puppeteer (CF Worker)\n- Use Case: Web forms, screenshots, data extraction (no API)\n- Governance: Always requires approval (high-risk)\n- Flow: Twin proposes → Human approves → Act dispatches → Browser executes\n\n---\n\n### **6. Book of Records Episode**\n\n**File:** `.iw-memory/specs/twin-owui/memory-pipeline-episode.json`  \n**Purpose:** Memory pipeline architecture (Book of Records format)  \n**Status:** Approved, canonical\n\n**Key Content:**\n\n- Pipeline stages (AI Worker → Triage Bot → Memory)\n- Book of Records primitives (episode, decision, learning, commitment, fact, action_item)\n- Decisions, learnings, commitments\n- Gaps vs today (write-session-log.ts must be rerouted)\n\n---\n\n### **7. Triage Output Schema**\n\n**File:** `.iw-memory/specs/twin-owui/triage-output-schema.ts`  \n**Purpose:** TypeScript schema for Triage Bot outputs  \n**Status:** Approved, canonical\n\n**Key Types:**\n\n- `TriageOutput` (base interface)\n- `EpisodeOutput`, `DecisionOutput`, `LearningOutput`, `CommitmentOutput`, `FactOutput`, `ActionItemOutput`\n- `PromotionQueueItem` (for human review)\n- TTL rules (decisions: 30 days, general: 90 days)\n\n---\n\n### **8. OWUI Skill Manifest**\n\n**File:** `.iw-memory/specs/twin-owui/owui-skill-manifest.md`  \n**Purpose:** How Twin uses tools without writing memory  \n**Status:** Approved, canonical\n\n**Key Skills:**\n\n- Read-only: `continuity.search`, `book.get_episodes`, `twin.morning_brief`\n- Write (approval): `memory.propose_candidate`, `spine.create_entity`, `browser.execute`\n- Skill format: YAML (when to use, inputs, outputs, governance)\n\n---\n\n## Architecture Convergence\n\n### **What Was Fragmented Before:**\n\n```\n- Twin (concept unclear: chatbot? orchestrator?)\n- OWUI (thought to be \"the Twin\")\n- Voice (thought to be separate from Twin)\n- Browser Agent (unclear if part of Twin)\n- Memory (unclear who writes, what format)\n- Models vs Profiles (confusion about Hermes/Think/Fast)\n```\n\n### **What Is Clear Now:**\n\n```\nTWIN\n├─ Runtime: CF Worker or VPS (persistent orchestrator)\n├─ Interfaces: OWUI, Voice, API, CLI (many ways to reach Twin)\n├─ Memory: Book of Records via Triage Bot (sole writer)\n├─ Reasoning: OpenRouter Agents (multi-model deliberation)\n├─ Governance: Propose → HITL → Approve\n└─ Execution: APIs, Browser, MCP, Workflows (many providers)\n\nOWUI\n├─ ONE interface to Twin (not the Twin itself)\n├─ Models: Foundation models (grok-4.3, hermes-internal)\n└─ Profiles: System prompts (Hermes, Think, Fast) wrapping foundation models\n\nVOICE\n├─ ONE interface to Twin (not separate system)\n├─ STT: x.ai Whisper (speech → text)\n└─ TTS: x.ai Kokoro \"eve\" (text → speech)\n\nBROWSER AGENT\n├─ ONE execution provider (not part of Twin)\n├─ Stack: Playwright (VPS) + Puppeteer (CF)\n└─ Flow: Twin proposes → Human approves → Act dispatches → Browser executes\n\nMEMORY\n├─ Writer: Triage Bot ONLY (no direct writes)\n├─ Format: Book of Records (6 primitives)\n├─ Storage: Conversational (staging) → Org (promoted)\n└─ Governance: Human-only promotion\n```\n\n---\n\n## Implementation Status\n\n### ✅ **Complete (Already Deployed)**\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- Intelligence worker (AI router, RAG, signal analysis)\n\n### 🚧 **In Progress (Designed, Needs Deployment)**\n\n- Twin Runtime (VPS: twin-runtime.operations.integratewise.ai)\n- Triage Bot (schema complete, needs implementation)\n- Browser Agent (VPS: browser-agent.operations.integratewise.ai)\n- Skills (YAML manifests created, needs OWUI loading)\n\n### 📋 **Planned (Next Phase)**\n\n- Twin Runtime → CF Worker (after VPS validation)\n- CLI interface (iw twin ask \"...\")\n- Email interface (twin@integratewise.ai)\n- Mobile app (iOS + Android)\n- TTL job (conversational memory aging)\n- Publication worker (org memory → OWUI surfaces)\n\n---\n\n## Key Decisions Today\n\n### **Decision 1: Twin ≠ OWUI**\n\n**Before:** OWUI is the Twin  \n**After:** OWUI is ONE interface to the Twin Runtime\n\n**Impact:** Twin can operate when OWUI is offline (always-on orchestrator)\n\n---\n\n### **Decision 2: Memory Pipeline is Governed**\n\n**Before:** Agents/tools write memory directly  \n**After:** All memory flows through AI Worker → Triage Bot → Memory\n\n**Impact:** All memory is structured (Book of Records), searchable, promotable\n\n---\n\n### **Decision 3: Models vs Profiles**\n\n**Before:** Hermes/Think/Fast are separate models  \n**After:** Hermes/Think/Fast are profiles (system prompts) wrapping foundation models (grok-4.3, hermes-internal)\n\n**Impact:** Clarity on what's a model vs what's a behavior\n\n---\n\n### **Decision 4: Voice = Interface (Not Separate System)**\n\n**Before:** Voice is a separate capability  \n**After:** Voice is ONE interface to the same Twin Runtime\n\n**Impact:** Voice conversations persist in Memory, can trigger proposals\n\n---\n\n### **Decision 5: Browser Agent = Execution Provider**\n\n**Before:** Browser Agent is part of Twin  \n**After:** Browser Agent is ONE execution provider (like APIs, MCP)\n\n**Impact:** Twin proposes, Human approves, Act dispatches, Browser executes\n\n---\n\n## Migration Path\n\n### **Phase 1: Twin Runtime on VPS (Customer Zero)**\n\n**Location:** integratewise-ops/vps-operations-stack/twin-runtime/  \n**URL:** https://twin-runtime.operations.integratewise.ai  \n**Tenant:** iw-customer-zero\n\n**Steps:**\n\n1. Build Twin Runtime (Bun + Hono)\n2. Deploy to VPS (Docker)\n3. Wire OWUI to Twin Runtime (update OPENAI_API_BASE_URL)\n4. Load Customer Zero (entities, signals, proposals, memory)\n5. Test end-to-end (voice, chat, proposals, execution)\n\n---\n\n### **Phase 2: Triage Bot Implementation**\n\n**Location:** services/triage-bot/ (CF Worker or VPS)  \n**Purpose:** Sole memory writer (Book of Records format)\n\n**Steps:**\n\n1. Implement Triage Bot worker\n2. Wire to outcome events (from Act service)\n3. Write to conversational_memory (Book of Records format)\n4. Index for search (auto)\n5. Queue for promotion (human review)\n\n---\n\n### **Phase 3: Browser Agent Deployment**\n\n**Location:** integratewise-ops/vps-operations-stack/browser-agent/  \n**URL:** https://browser-agent.operations.integratewise.ai\n\n**Steps:**\n\n1. Deploy Playwright service (VPS)\n2. Wire to Act service\n3. Test browser automation (screenshot, form fill, data extraction)\n4. Integrate with governance (approval flow)\n\n---\n\n### **Phase 4: Twin Runtime → CF Worker (Production)**\n\n**Location:** services/twin-orchestrator/  \n**URL:** https://twin.dev.integratewise.ai\n\n**Steps:**\n\n1. Migrate VPS Twin Runtime to CF Worker\n2. Update OWUI to call CF endpoint\n3. Deploy cron trigger (every 5 minutes)\n4. Verify observe → reason → propose loop\n5. Monitor logs + outcomes\n\n---\n\n## Document Hierarchy (Updated)\n\n```\ndocs/tech/INTEGRATEWISE_CANONICAL_ARCHITECTURE.md ← MASTER (start here)\n    │\n    ├─→ docs/tech/MEMORY_GOVERNANCE_DOCTRINE.md (memory rules)\n    ├─→ docs/tech/TWIN_AS_COGNITIVE_ORCHESTRATOR.md (Twin details)\n    ├─→ docs/tech/TWIN_VOICE_INTERFACE.md (Voice interface)\n    ├─→ docs/tech/TWIN_BROWSER_EXECUTION.md (Browser Agent)\n    ├─→ docs/tech/ENTITY_BINDING_AND_RELATIONSHIPS.md (Spine)\n    ├─→ docs/tech/MCP_ADK_ROUTING_SPINE_MEMORY_ARCHITECTURE.md (MCP + ADK)\n    ├─→ docs/tech/LAYER_OWNERSHIP_AND_TWIN_RUNTIME.md (S/U/V/CZ layers)\n    └─→ docs/tech/INTEGRATEWISE_PRODUCT_ARCHITECTURE.md (legacy, still valid)\n\n.iw-memory/specs/twin-owui/\n    ├─→ memory-pipeline-episode.json (Book of Records episode)\n    ├─→ triage-output-schema.ts (TypeScript schema)\n    └─→ owui-skill-manifest.md (Skills documentation)\n```\n\n---\n\n## For Next Session\n\n**Read this file first:** `docs/tech/INTEGRATEWISE_CANONICAL_ARCHITECTURE.md`\n\n**Then proceed with implementation:**\n\n1. Build Twin Runtime (VPS)\n2. Wire OWUI to Twin Runtime\n3. Load Customer Zero\n4. Test end-to-end\n\n**Key constraint:** integratewise-live is restricted (no edits without explicit permission). Work in integratewise-ops for VPS deployment.\n\n---\n\n## Summary\n\n**Today we achieved:**\n\n- ✅ Defined canonical architecture (One Twin, One Spine, One Memory, One Governance, One Bridge)\n- ✅ Clarified Twin vs OWUI vs Voice vs Browser Agent\n- ✅ Established memory governance (Triage Bot only)\n- ✅ Documented Book of Records format (6 primitives)\n- ✅ Created skill manifests (how Twin uses tools)\n- ✅ Designed deployment path (VPS → CF)\n\n**Everything now has its place.**\n**Every write path is governed.**\n**Every interface reaches the same Twin.**\n\n**This is IntegrateWise 2.0.**\n\n---\n\n**Date:** 2026-06-09  \n**Version:** 2.0  \n**Status:** Canonical  \n**Authority:** Founder + Architecture Team\n"}