{"slug":"architecture/PRODUCT_ARCHITECTURE","title":"IntegrateWise Product Architecture Document","section":"architecture","sectionLabel":"Architecture","status":"superseded","type":"document","path":"architecture/PRODUCT_ARCHITECTURE.mdx","bytes":29505,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## v3.7 — External Customer Surface Lock\n\n**Date:** June 18, 2026  \n**Status:** SUPERSEDED — historical product architecture\n**Classification:** Internal + Customer-Facing Specification\n\n**Current authority:** [INTEGRATEWISE_ARCHITECTURE.md](INTEGRATEWISE_ARCHITECTURE.md) v2.2\n\n> This document is retained for lineage. Current authority is\n> `INTEGRATEWISE_ARCHITECTURE.md` v2.2 and `SPEC_AMENDMENTS_v1.md`,\n> `CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md` and\n> `TWIN_BEHAVIOR.md`. Its D1-truth, layered-surface and older Product claims\n> must not be implemented.\n\n---\n\n## 1. Product Positioning\n\nIntegrateWise is the system that understands, remembers, reasons, and prepares execution — while execution happens in the customer's own environment.\n\nWe do not compete with workflow engines, agent runtimes, or automation platforms. We compete with the chaos of fragmented tools, disconnected context, and blind operational decisions.\n\n### 1.1 Workbench Doctrine Alignment\n\nThe Workbench is the primary operating surface of IntegrateWise. Every customer-facing, internal, AI, governance, knowledge, and domain experience is a governed projection over the same Adaptive Spine. No Workbench owns data or canonical truth; each Workbench consumes governed context and presents the right perspective for its purpose.\n\nThis document's L1-L7 surfaces should therefore be read as specialized Workbench projections, not as independent applications or systems of record. The Human Workbench is one projection alongside the Twin Workbench, Governance Workbench, Knowledge/Memory Workbench, Operations Workbench, Execution Workbench, and role-specific Domain Workbenches.\n\nCanonical doctrine: [Workbench Doctrine](./WORKBENCH_DOCTRINE.md).\n\n### The Wedge\n\nEvery enterprise has 15+ tools. None of them talk to each other. The human operator becomes the integration layer — cross-referencing, reconciling, deciding, then manually updating each system. IntegrateWise replaces that human integration burden with a unified intelligence layer that:\n\n- **Connects** — ingests and normalizes data from all tools (S1–S3)\n- **Unifies** — resolves entities and builds a single source of truth (S4–S5)\n- **Understands** — surfaces signals, insights, and context (L2, S6)\n- **Remembers** — maintains organizational and personal memory (L4, S7)\n- **Reasons** — proposes actions, mutations, and workflows via Twin (L3, S10)\n- **Governs** — ensures every action is approved before it leaves the system (Approval Center, S8)\n- **Prepares** — packages execution into a vendor-neutral canonical contract (Handoff Layer)\n- **Hands Off** — dispatches to the customer's own execution infrastructure (Async, Adapters)\n\n---\n\n## 2. The Two Modes\n\n### 2.1 Customer Zero Mode (IntegrateWise Internal)\n\n**Full Stack — All 7 Layers + 12 Backend Stages**  \nUsed for:\n\n- Internal IntegrateWise operations\n- Sales demos showcasing end-to-end capability\n- Customer Zero verification and dogfooding\n\n| Layer | Name                      | Visibility    |\n| :---- | :------------------------ | :------------ |\n| L0    | Onboarding                | Customer      |\n| L0.5  | Always-On Operating Layer | Background    |\n| L1    | Domain Workbench          | Customer      |\n| L2    | Cognitive Overlay         | Customer      |\n| L3    | Twin Workbench            | Customer      |\n| L4    | Memory Workbench          | Customer      |\n| L5    | Operations Workbench      | Internal Only |\n| L6    | Execution Workbench       | Internal Only |\n| L7    | Governance Workbench      | Internal Only |\n\nIn Customer Zero mode, L5 and L6 are visible. S11 (Execution) and S12 (Writeback) run natively. The full loop is closed inside IntegrateWise.\n\n### 2.2 External Customer Mode\n\n**Trimmed Surface — 5 Layers + Handoff Layer**\n\n| Layer | Customer Name     | Internal Name        | Purpose                    |\n| :---- | :---------------- | :------------------- | :------------------------- |\n| L1    | Workbench         | Domain Workbench     | Main operational surface   |\n| L2    | Cognitive Overlay | Intelligence Overlay | Signals, insights, context |\n| L3    | Twin Workbench    | Twin Workbench       | Chat, reasoning, planning  |\n| L4    | Memory Workbench  | Memory Workbench     | Search, memory, documents  |\n| —     | Approval Center   | L7 Governance        | Approvals, audit, dispatch |\n\n**Removed from customer view:**\n\n- L5 Operations Workbench (Situations board, signals stream, proposal pipeline)\n- L6 Execution Workbench (Ready queue, running executions, writeback audit)\n- Native S11 Execution and S12 Writeback\n\n**Replaced with:**\n\n- Handoff Layer — Canonical JSON contract + adapter exports\n- Async State Machine — Tracked execution states with signal-based feedback\n\n---\n\n## 3. The Five Customer Surfaces\n\n### 3.1 L1 — Workbench\n\n**Intent:** Primary operational surface for the user's domain.\n\n**What the user sees:**\n\n- Domain-specific dashboards (Account Success, Sales, BizOps, RevOps, Product Engineering, Marketing, Personal)\n- Entity 360 views (accounts, contacts, opportunities, tickets)\n- Cross-tool data unified from the Spine\n- Contextual actions and quick insights\n\n**Domain rules:**\n\n- One work domain per user (chosen at onboarding, locked)\n- Personal domain always available (PERSONAL)\n- Data comes from `${domain}_data` Spine partition only\n- No raw tool data ever shown\n\n_Key invariant:_ L1 is strictly differentiated by domain. The UI, modules, and data partitions change based on the active domain.\n\n### 3.2 L2 — Cognitive Overlay\n\n**Intent:** Always-available intelligence surface that sits on top of L1.  \n**Trigger:** `⌘J` (or equivalent keyboard shortcut) sliding drawer/panel.\n\n**What the user sees:**\n\n- Signals — anomalous patterns, risk indicators, opportunity alerts\n- Insights — synthesized observations with evidence and context\n- Think — reasoning traces and hypothesis generation\n- Govern — governance status indicators\n- Context — assembled entity context from the Spine\n- Evidence — source references and confidence scores\n\n**Domain handling:** Shared surface. Filters by active domain context. Can scope to current work view.\n\n**Interaction model:**\n\n- Read-heavy by design\n- Users can promote an insight to a proposal (triggers Twin)\n- Users can query context directly\n- No direct mutations from L2\n\n### 3.3 L3 — Twin Workbench\n\n**Intent:** Conversational reasoning and planning interface.\n\n**What the user sees:**\n\n- Chat interface with streaming responses\n- Reasoning surface (chain-of-thought, plan generation)\n- Workflow design and proposal creation\n- Context-aware suggestions\n\n**How Twin gets context:**\n\n- Seeded from active domain entities (L1 context)\n- Injected with L2 signals and insights\n- Enriched with L4 memory (relevant documents, past sessions)\n- Governed by S9 Continuity Bridge (assembled context package)\n\n**Twin's role in the handoff flow:**\n\n- User asks Twin to plan a workflow or propose a mutation\n- Twin generates a structured proposal (actions + mutations + context + success criteria)\n- Proposal is pushed to Approval Center (status: `PENDING_REVIEW`)\n- Twin does NOT auto-dispatch. Human-in-the-loop is mandatory.\n\n_Backend:_ S10 Twin Runtime (`iw-agent-runtime`, Cloudflare DOs, SQLite state). No OpenWebUI. No CouchDB.\n\n### 3.4 L4 — Memory Workbench\n\n**Intent:** Knowledge substrate — search, organize, and retrieve organizational and personal memory.\n\n**What the user sees:**\n\n- Semantic search across org memory, personal memory, documents, AI sessions\n- Memory organization (tags, categories, promoted knowledge)\n- Document management (upload, reference, ground truth)\n- Session history and continuity\n- Governance status on memory items (staging / approved / published)\n\n**Domain handling:** Differentiated. Memory layer is scoped to the active domain. Search and retrieval filter by domain partition.\n\n**Write path:**\n\n- `memory.propose` is live at the tool/protocol level (MCP handler → proposals table → governance queue)\n- Direct writes to `org_memory` are blocked — all writes go through `propose` → governance\n- L4 UI is currently read-heavy; the dedicated \"Propose to Memory\" form is partial (🟡)\n\n_Key invariant:_ Memory is never written directly. It is always proposed, governed, and then committed.\n\n### 3.5 Approval Center\n\n**Intent:** The single place where users see, review, approve, reject, and dispatch proposed actions.\n\n**What the user sees:**\n\n- **Pending** — proposals awaiting review (from Twin, from L2 insights, from system signals)\n- **Approved** — actions that passed governance, ready for dispatch\n- **Rejected** — actions that were denied, with reasoning\n- **Handed Off** — actions dispatched to customer's execution environment\n- **Audit Trail** — complete history of every proposal, approval, and outcome\n\n**The flow:**\n\n```text\n[Twin Proposes] → [Approval Center: Pending] → [User Reviews] → [User Approves] → [User Dispatches] → [Handoff Package Generated] → [Async Tracking]\n```\n\n**No auto-dispatch.** The user must explicitly choose:\n\n- Export to Hermes\n- Export to OpenClaw\n- Export as JSON\n- Export as MCP\n\n**Governance stamp:** Every approved proposal carries:\n\n```json\n{\n  \"governance\": {\n    \"approval_token\": \"iw-gov-{uuid}\",\n    \"approved_at\": \"ISO8601\",\n    \"approved_by\": \"user_id\",\n    \"proposal_id\": \"prop-{uuid}\",\n    \"audit_hash\": \"sha256:{hash}\",\n    \"expiry\": \"ISO8601 (+1 hour default)\"\n  }\n}\n```\n\n_HARD GATE invariant:_ No handoff package can be generated without an L7 approval token. The Approval Center is the only surface that can mint this token.\n\n---\n\n## 4. The Handoff Layer\n\n### 4.1 Philosophy\n\nIntegrateWise does not execute for external customers. It prepares, governs, and hands off.  \nThe handoff layer is the bridge between IntegrateWise's intelligence and the customer's execution infrastructure.\n\n### 4.2 Canonical Handoff Contract\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"proposal_id\": \"prop-uuid\",\n  \"handoff_id\": \"handoff-uuid\",\n  \"generated_at\": \"2026-06-18T14:58:00Z\",\n  \"type\": \"workflow\",\n\n  \"actions\": [\n    {\n      \"id\": \"act-1\",\n      \"type\": \"workflow\",\n      \"name\": \"Executive Review Scheduling\",\n      \"description\": \"Schedule executive review for high-risk renewal account\",\n      \"tool_refs\": [\"hubspot\", \"calendar\"],\n      \"parameters\": {\n        \"account_id\": \"acc_123\",\n        \"review_type\": \"executive\",\n        \"priority\": \"high\"\n      },\n      \"dependencies\": []\n    }\n  ],\n\n  \"mutations\": [\n    {\n      \"id\": \"mut-1\",\n      \"type\": \"mutation\",\n      \"target\": \"hubspot.account\",\n      \"entity_id\": \"acc_123\",\n      \"operation\": \"update\",\n      \"changes\": {\n        \"renewal_risk\": \"medium\",\n        \"next_action\": \"Executive Review Scheduled\"\n      },\n      \"previous_state\": {\n        \"renewal_risk\": \"high\",\n        \"next_action\": null\n      },\n      \"conflict_resolution\": \"merge_with_audit\"\n    }\n  ],\n\n  \"context\": {\n    \"domain\": \"CUSTOMER_SUCCESS\",\n    \"entity_context\": {\n      \"account\": {\n        \"id\": \"acc_123\",\n        \"name\": \"Acme Corp\",\n        \"arr\": 850000,\n        \"health_score\": 72\n      }\n    },\n    \"assembled_history\": [\n      {\n        \"event\": \"risk_escalation\",\n        \"timestamp\": \"2026-06-15T10:00:00Z\",\n        \"source\": \"support_ticket\"\n      }\n    ],\n    \"goal_refs\": [\"goal_reduce_churn_q3\", \"goal_expand_acme_2026\"],\n    \"relevant_memory\": [\"mem-uuid-1\", \"mem-uuid-2\"]\n  },\n\n  \"governance\": {\n    \"approval_token\": \"iw-gov-uuid\",\n    \"approved_at\": \"2026-06-18T14:58:00Z\",\n    \"approved_by\": \"user_id\",\n    \"proposal_id\": \"prop-uuid\",\n    \"audit_hash\": \"sha256:...\",\n    \"expiry\": \"2026-06-18T15:58:00Z\",\n    \"approval_scope\": \"single_execution\",\n    \"risk_classification\": \"medium\"\n  },\n\n  \"success_criteria\": [\n    {\n      \"id\": \"sc-1\",\n      \"metric\": \"hubspot.account.renewal_risk\",\n      \"expected\": \"medium\",\n      \"verification\": \"direct_read\"\n    },\n    {\n      \"id\": \"sc-2\",\n      \"metric\": \"calendar.event.created\",\n      \"expected\": true,\n      \"verification\": \"existence_check\"\n    }\n  ],\n\n  \"metadata\": {\n    \"twin_session_id\": \"twin-uuid\",\n    \"source_insight_id\": \"insight-uuid\",\n    \"estimated_execution_time\": \"120s\",\n    \"retry_policy\": {\n      \"max_retries\": 2,\n      \"backoff\": \"exponential\"\n    }\n  }\n}\n```\n\n### 4.3 Field Definitions\n\n| Field            | Type   | Required | Description                                        |\n| :--------------- | :----- | :------- | :------------------------------------------------- |\n| version          | string | Yes      | Contract version (semver)                          |\n| proposal_id      | string | Yes      | Original proposal ID from Twin                     |\n| handoff_id       | string | Yes      | Unique ID for this handoff instance                |\n| type             | enum   | Yes      | workflow, mutation, composite                      |\n| actions          | array  | No       | Workflow triggers (read operations, orchestration) |\n| mutations        | array  | No       | State changes (writes, updates, deletes)           |\n| context          | object | Yes      | Assembled Spine context for the customer's agent   |\n| governance       | object | Yes      | Approval token and audit metadata                  |\n| success_criteria | array  | Yes      | How the customer agent verifies success            |\n| metadata         | object | No       | Execution hints, retry policy, session refs        |\n\n_Rule:_ Either `actions` or `mutations` (or both) must be non-empty. A handoff with neither is invalid.\n\n### 4.4 Adapter Layer\n\nThe canonical contract is vendor-neutral. Adapters translate it to target formats:\n\n```text\nCanonical Handoff\n       ↓\n┌──────────────────┐\n│ Adapter Layer    │\n├──────────────────┤\n│ JSON (raw)       │ — Direct export, human-readable\n│ MCP              │ — Model Context Protocol tool calls\n│ LangGraph        │ — LangChain/LangGraph state graph\n│ Hermes           │ — IntegrateWise internal runtime (Customer Zero)\n│ OpenClaw         │ — Customer's agent runtime\n│ n8n              │ — n8n workflow JSON\n│ Zapier           │ — Zapier action payload\n└──────────────────┘\n```\n\nEach adapter:\n\n- Validates the canonical contract against schema\n- Maps actions/mutations to target-specific format\n- Preserves the governance stamp (token + audit hash)\n- Preserves success criteria in target-verifiable form\n- Returns the adapted payload + metadata\n\n---\n\n## 5. Async State Machine\n\n### 5.1 States\n\n```text\n[PENDING_REVIEW]        — Proposal created by Twin, awaiting review\n       ↓\n[APPROVED]              — User approved in Approval Center\n       ↓\n[HANDED_OFF]            — User dispatched, package generated, sent to customer\n       ↓\n[AWAITING_OUTCOME]      — Customer agent acknowledged, executing\n       ↓\n[COMPLETED]             — Success criteria met, outcome recorded\n       ↓\n[FAILED]                — Execution failed, error recorded\n       ↓\n[PARTIAL]               — Some success criteria met, partial outcome\n       ↓\n[EXPIRED]               — Governance token expired before execution\n       ↓\n[REJECTED]              — User denied in Approval Center\n```\n\n### 5.2 State Transitions\n\n| From             | To               | Trigger                                  | Actor          |\n| :--------------- | :--------------- | :--------------------------------------- | :------------- |\n| PENDING_REVIEW   | APPROVED         | User clicks \"Approve\"                    | Human          |\n| PENDING_REVIEW   | REJECTED         | User clicks \"Reject\"                     | Human          |\n| APPROVED         | HANDED_OFF       | User selects adapter + clicks \"Dispatch\" | Human          |\n| HANDED_OFF       | AWAITING_OUTCOME | Customer agent acknowledges receipt      | System         |\n| AWAITING_OUTCOME | COMPLETED        | Outcome webhook reports success          | System         |\n| AWAITING_OUTCOME | FAILED           | Outcome webhook reports failure          | System         |\n| AWAITING_OUTCOME | PARTIAL          | Outcome webhook reports partial          | System         |\n| AWAITING_OUTCOME | EXPIRED          | Governance token expires                 | System (alarm) |\n\n### 5.3 L2 Signal Mapping\n\nEach state change surfaces in L2 as a signal:\n\n| State            | L2 Signal                                | Urgency |\n| :--------------- | :--------------------------------------- | :------ |\n| HANDED_OFF       | \"Sent to {adapter_name}\"                 | Info    |\n| AWAITING_OUTCOME | \"Awaiting outcome from {adapter_name}\"   | Info    |\n| COMPLETED        | \"Execution completed: {summary}\"         | Success |\n| FAILED           | \"Execution failed: {error_summary}\"      | Warning |\n| PARTIAL          | \"Partially completed: {details}\"         | Warning |\n| EXPIRED          | \"Handoff expired — re-approval required\" | Error   |\n\n### 5.4 L4 Memory Mapping\n\nEvery handoff outcome is recorded in L4 as an `execution_memory` entry:\n\n```json\n{\n  \"type\": \"execution_memory\",\n  \"handoff_id\": \"handoff-uuid\",\n  \"proposal_id\": \"prop-uuid\",\n  \"outcome\": \"completed | failed | partial | expired\",\n  \"timestamp\": \"ISO8601\",\n  \"adapter\": \"hermes | openclaw | json | mcp | ...\",\n  \"success_criteria_results\": [...],\n  \"error_details\": \"...\",\n  \"governance_token\": \"iw-gov-uuid\",\n  \"linked_entities\": [\"acc_123\"],\n  \"linked_goals\": [\"goal_reduce_churn_q3\"]\n}\n```\n\n---\n\n## 6. API Contracts\n\n### 6.1 Handoff Generation\n\n```http\nPOST /api/v1/handoff/generate\nAuthorization: Bearer {jwt}\nContent-Type: application/json\n\n{\n  \"proposal_id\": \"prop-uuid\",\n  \"adapter\": \"json | mcp | hermes | openclaw | n8n | langgraph\"\n}\n```\n\n**Response: 200 OK**\n\n```json\n{\n  \"handoff_id\": \"handoff-uuid\",\n  \"status\": \"generated\",\n  \"payload\": { ... canonical contract ... },\n  \"adapted_payload\": { ... adapter-specific format ... },\n  \"governance_token\": \"iw-gov-uuid\",\n  \"expires_at\": \"2026-06-18T15:58:00Z\",\n  \"download_url\": \"https://api.integratewise.ai/v1/handoff/download/handoff-uuid\"\n}\n```\n\n### 6.2 Outcome Ingestion\n\n```http\nPOST /api/v1/handoff/outcome\nAuthorization: Bearer {api_key}  // Customer's system API key\nContent-Type: application/json\n\n{\n  \"handoff_id\": \"handoff-uuid\",\n  \"governance_token\": \"iw-gov-uuid\",\n  \"status\": \"completed | failed | partial\",\n  \"timestamp\": \"ISO8601\",\n  \"results\": {\n    \"success_criteria\": [\n      {\n        \"id\": \"sc-1\",\n        \"met\": true,\n        \"actual_value\": \"medium\",\n        \"verification_method\": \"direct_read\"\n      }\n    ],\n    \"error\": null,\n    \"logs\": [\"...\"]\n  }\n}\n```\n\n**Response: 200 OK**\n\n```json\n{\n  \"received\": true,\n  \"memory_id\": \"mem-uuid\",\n  \"signal_id\": \"sig-uuid\"\n}\n```\n\n### 6.3 Status Polling\n\n```http\nGET /api/v1/handoff/status/:handoff_id\nAuthorization: Bearer {jwt}\n```\n\n**Response: 200 OK**\n\n```json\n{\n  \"handoff_id\": \"handoff-uuid\",\n  \"status\": \"handed_off | awaiting_outcome | completed | failed | partial | expired\",\n  \"proposal\": { ... },\n  \"governance\": { ... },\n  \"outcome\": { ... },\n  \"timeline\": [\n    {\"state\": \"approved\", \"at\": \"...\"},\n    {\"state\": \"handed_off\", \"at\": \"...\"},\n    {\"state\": \"awaiting_outcome\", \"at\": \"...\"}\n  ]\n}\n```\n\n---\n\n## 7. Backend Architecture (S1–S12)\n\n### 7.1 Stages\n\n| Stage | Name              | Purpose                         | Customer Zero | External Customer                |\n| :---- | :---------------- | :------------------------------ | :------------ | :------------------------------- |\n| S1    | Connectivity      | Connectors / Nango / MCP        | ✅ Active     | ✅ Active                        |\n| S2    | Loader            | Ingest raw data                 | ✅ Active     | ✅ Active                        |\n| S3    | Normalizer        | 8-stage pipeline                | ✅ Active     | ✅ Active                        |\n| S4    | Entity Resolution | Spine deduping                  | ✅ Active     | ✅ Active                        |\n| S5    | Spine Write       | D1 partitions (source of truth) | ✅ Active     | ✅ Active                        |\n| S6    | Intelligence      | Signals, think, proposals       | ✅ Active     | ✅ Active                        |\n| S7    | Memory            | Org + personal + conversational | ✅ Active     | ✅ Active                        |\n| S8    | Governance        | Approvals, policies, audit      | ✅ Active     | ✅ Active                        |\n| S9    | Continuity Bridge | Assembled context               | ✅ Active     | ✅ Active                        |\n| S10   | Twin Runtime      | iw-agent-runtime (DOs)          | ✅ Active     | ✅ Active                        |\n| S11   | Execution         | Handoff / playbook dispatch     | ✅ Active     | ❌ Bypassed → Handoff            |\n| S12   | Writeback         | Record outcomes                 | ✅ Active     | ❌ Delegated → Outcome Ingestion |\n\n### 7.2 L0.5 Always-On Operating Layer\n\nNon-UI background layer. Runs continuously.\n\n**Components:**\n\n- **TwinAgent** — Background reasoning, proposal generation, alarm handling\n- **TenantBrainDO** — Per-tenant state, pending approvals, active signals, execution tracking\n- **Watcher DO** — Monitors data freshness, connector health, anomaly detection\n- **Cron Jobs** — Scheduled context assembly, memory compaction, signal generation\n\n_Critical note for external customers:_  \nL0.5's escalation bypass path (where `TenantBrainDO` can mint an `escalation-bypass-token` on alarm timeout) is Customer Zero only. For external customers, L0.5 is strictly read/propose-only. Any proposal from L0.5 goes to Approval Center. No execution bypass exists.\n\n---\n\n## 8. Data Flow: End-to-End\n\n### 8.1 External Customer Flow\n\n```text\n[User edits Renewal Risk in L1]\n         ↓\n[Change captured as proposed mutation]\n         ↓\n[Twin (L3) generates structured proposal]\n         ↓\n[Proposal pushed to Approval Center — PENDING_REVIEW]\n         ↓\n[User reviews in Approval Center]\n         ↓\n[User APPROVES]\n         ↓\n[User selects adapter: \"Export to OpenClaw\"]\n         ↓\n[Canonical Handoff Contract generated]\n         ↓\n[Adapted to OpenClaw format]\n         ↓\n[Package dispatched to customer's OpenClaw endpoint]\n         ↓\n[Status: HANDED_OFF → AWAITING_OUTCOME]\n         ↓\n[Customer's OpenClaw executes: updates HubSpot, schedules calendar]\n         ↓\n[OpenClaw POSTs outcome to /api/v1/handoff/outcome]\n         ↓\n[IntegrateWise validates governance token]\n         ↓\n[Status: COMPLETED]\n         ↓\n[L2 Signal: \"Execution completed: Account renewal risk updated\"]\n         ↓\n[L4 Memory: execution_memory entry recorded]\n         ↓\n[L1 Workbench: Account card refreshed from Spine]\n```\n\n### 8.2 Customer Zero Flow (Full Loop)\n\n```text\n[Same path through Approval Center]\n         ↓\n[User selects adapter: \"Execute via Hermes\"]\n         ↓\n[Canonical contract adapted to Hermes format]\n         ↓\n[Hermes (S11) executes directly on IntegrateWise infrastructure]\n         ↓\n[S12 Writeback records outcomes to Spine]\n         ↓\n[L2 Signal + L4 Memory + L1 Refresh]\n```\n\n---\n\n## 9. Key Invariants\n\n1. **Spine-Only Reads:** The UI (all layers) only ever reads projections assembled from the Spine. Raw data is never shown.\n2. **HARD GATE:** Approval Center is the only surface that can mint an approval token. No handoff package can be generated without it.\n3. **No Auto-Dispatch:** The user must explicitly dispatch an approved proposal. Twin does not auto-execute.\n4. **Async Execution:** All handoffs are async. The UI never blocks waiting for execution.\n5. **Vendor-Neutral Contract:** The canonical handoff format is adapter-agnostic. IntegrateWise does not lock customers into a specific execution runtime.\n6. **Mutations Included:** Handoffs support state changes (writes, updates, deletes), not just workflow triggers.\n7. **Outcome Feedback:** Customer execution agents must POST outcomes back to IntegrateWise. Without this, the loop is broken.\n8. **Domain Differentiation:** L1 and L4 are differentiated by domain. L2, L3, Approval Center, and handoff layer are shared.\n9. **No Direct Execution for External Customers:** S11 and S12 are bypassed for external customers. Execution happens in the customer's environment.\n10. **L0.5 Escalation Bypass — Customer Zero Only:** The alarm timeout escalation path is restricted to internal IntegrateWise operations.\n\n---\n\n## 10. Design System\n\n### 10.1 Colors\n\n```css\n:root {\n  --iw-ink: #0c0c0c;\n  --iw-paper: #f4f0eb;\n  --iw-forest: #232d42;\n  --iw-gold: #c9a96e;\n  --iw-primary: #4356a9;\n  --iw-primary-pink: #eb4f72;\n  --iw-bg: #edeef0;\n}\n```\n\n### 10.2 Typography\n\n- **Primary:** Inter, Poppins\n- **Monospace:** IBM Plex Mono\n\n### 10.3 Aesthetic\n\n- Minimal, calm, systems-oriented\n- Whitespace, rounded rectangles, simple lines/nodes\n- Grid-aligned diagrams, flat vectors\n- No gradients, no 3D, no heavy shadows\n\n---\n\n## 11. Implementation Maturity (June 2026)\n\n| Component                  | Status      | Notes                                                         |\n| :------------------------- | :---------- | :------------------------------------------------------------ |\n| L0 Onboarding              | ✅ Solid    | 4-step wizard, domain resolution, JWT metadata                |\n| L1 Workbench               | ✅ Solid    | `DOMAIN_CONTENT_MAP`, per-domain modules, design tokens clean |\n| L2 Cognitive Overlay       | ✅ Solid    | Functional, cognitive signals, insight panel                  |\n| L3 Twin Workbench          | ✅ Solid    | Native Cloudflare DOs, streaming, context seeding             |\n| L4 Memory Workbench        | 🟡 Partial  | Read surface solid; write surface (propose form) partial      |\n| L5 Operations              | ✅ Internal | Functional for Customer Zero                                  |\n| L6 Execution               | ✅ Internal | Functional for Customer Zero                                  |\n| L7 Governance              | ✅ Internal | Functional for Customer Zero                                  |\n| Approval Center (External) | 🎯 Target   | Needs UI build, dispatch flow, adapter selection              |\n| Handoff Layer              | 🎯 Target   | Canonical contract defined; adapters need implementation      |\n| Async State Machine        | 🎯 Target   | States defined; webhook endpoints need build                  |\n| Outcome Ingestion          | 🎯 Target   | API spec defined; implementation pending                      |\n| S11 Bypass for External    | 🎯 Target   | Logic flag needed in S8/S11 boundary                          |\n| Adapter Layer              | 🎯 Target   | JSON adapter first; MCP, Hermes, OpenClaw, n8n follow         |\n\n---\n\n## 12. Glossary\n\n| Term                   | Definition                                                                                                |\n| :--------------------- | :-------------------------------------------------------------------------------------------------------- |\n| **Spine**              | Single Source of Truth — unified intelligence layer connecting tools, context, and decisions              |\n| **Twin**               | Conversational AI workbench that reasons, plans, and proposes                                             |\n| **Approval Center**    | Customer-facing governance surface for reviewing, approving, and dispatching proposals                    |\n| **Handoff**            | The act of packaging an approved proposal into a vendor-neutral contract for external execution           |\n| **Canonical Contract** | The vendor-neutral JSON format that defines actions, mutations, context, governance, and success criteria |\n| **Adapter**            | A translator that converts the canonical contract into a target execution format (MCP, Hermes, etc.)      |\n| **HITL**               | Human-in-the-Loop — mandatory human approval before any action leaves the system                          |\n| **HARD GATE**          | The invariant that no execution token can exist without L7/Approval Center approval                       |\n| **Customer Zero**      | IntegrateWise's own internal operations — the dogfood tenant that uses the full stack                     |\n| **Domain**             | The user's chosen work context (CUSTOMER_SUCCESS, SALES, BIZOPS, etc.)                                    |\n| **L0.5**               | The always-on background operating layer (DOs, crons, agents)                                             |\n\n---\n\n## 13. Document Control\n\n| Version | Date       | Author                 | Changes                                                                                                                          |\n| :------ | :--------- | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------- |\n| 3.7     | 2026-06-18 | Product + Architecture | External customer surface lock, handoff layer specification, Approval Center definition, async state machine, canonical contract |\n\n**Next Review:** Upon completion of Approval Center UI and Handoff Layer implementation.\n\n_This document is the canonical source of truth for IntegrateWise product architecture as of June 2026. All engineering, design, and go-to-market decisions must align with this specification._\n"}