{"slug":"architecture/INTEGRATEWISE_CANONICAL_REFERENCE","title":"IntegrateWise — Canonical Reference & System Doctrine","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/INTEGRATEWISE_CANONICAL_REFERENCE.mdx","bytes":10319,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Authoritative Synthesis & System Contract  \n**Source Baseline:** `integratewise-docs/canonical-reference.html`  \n**Core Invariant:** _One logical Spine, one product (Spine Workspace / User Workbench), and every department, role, and platform function is a projection over that Spine. No surface owns its own database._\n\n---\n\n## I. The Model in One Breath\n\n### 1. Category Definition\n\n> **The Self-Organizing Workspace is a collaborative environment where humans and AI continuously structure work, context, and capabilities around evolving goals.**\n\n- Outcome-first architecture.\n- Names the human + AI partnership as co-equal.\n- Puts **evolving goals** at the center of workspace organization.\n\n### 2. The Precise Statement\n\n> **IntegrateWise is a Continuity Platform delivered through a self-organizing User Workbench (Spine Workspace).**\n> _Platform underneath. Product in front. Promise first._\n\n- **Marketing & Positioning Sequence:**\n  1. **Promise:** Your workspace organizes itself around your work.\n  2. **Product:** Tables (structured truth), Views (role lenses), and Docs (narrative) unified by Twin.\n  3. **Outcome:** Nothing is forgotten. Context follows the work.\n  4. **Platform Proof:** OneAuth, Adaptive Spine, Connectors, Memory, Orchestration, and Governance.\n\n### 3. The Product Promise (Frozen)\n\n> **Nothing is forgotten. Context follows the work. The workspace organizes itself. The user remains in control.**\n\n---\n\n## II. The Five Architectural Layers\n\n```text\n┌──────────────────────────────────────────────────────────────────────────────────┐\n│  LAYER 4: PRODUCT — THE USER WORKBENCH (Spine Workspace)                        │\n│  • Tables (Structured Truth) • Views (Role-Routed Projections) • Docs (Narrative)│\n│  • Contextual Twin Copilot (Invoked on Specific Objects, Not an Idle Rail)       │\n└────────────────────────────────────────▲─────────────────────────────────────────┘\n                                         │ Governed Projections\n┌────────────────────────────────────────┴─────────────────────────────────────────┐\n│  LAYER 2: PRODUCT PACKAGE (Capability Kernel)                                    │\n│  • Discovery • Capability Resolver • Spine Cache • ADK • Loader • Normalizer     │\n│  • packages/*: Reusable contracts defining what is possible                      │\n└────────────────────────────────────────▲─────────────────────────────────────────┘\n                                         │ Synchronizes & Normalizes\n┌────────────────────────────────────────┴─────────────────────────────────────────┐\n│  LAYER 3: THE ADAPTIVE SPINE (Logical Business Backbone)                         │\n│  • Canonical Spine (Neon / Postgres): Durable SSOT, provenance, audit, policies  │\n│  • Operational Spine (D1 / KV): Working set, active KPIs, signals, fast context  │\n│  • Substrates: Neon (Truth), D1 (Ops), KV (Cache), R2 (Evidence), Vectorize (RRF)│\n└────────────────────────────────────────▲─────────────────────────────────────────┘\n                                         │ Powered & Governed By\n┌────────────────────────────────────────┴─────────────────────────────────────────┐\n│  LAYER 5: PLATFORM BACKEND (Execution Runtime)                                   │\n│  • Package Runtime • AI Gateway • Agent Orchestration • Memory • Pipeline Engine │\n│  • services/*: Runs capabilities at enterprise scale with HITL governance        │\n└────────────────────────────────────────▲─────────────────────────────────────────┘\n                                         │ Access Controlled Via\n┌────────────────────────────────────────┴─────────────────────────────────────────┐\n│  LAYER 1: ONEAUTH (Entry & Session Ingress)                                      │\n│  • Host-controlled authentication • Zero client credential copies                │\n│  • Resolves identity, tenant, workspace, roles, entitlements, and policies       │\n└──────────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## III. The Universal Tenant Spine\n\n### 1. Eight Spine Domains\n\nOne unified schema where every role, department, and vertical is an additive projection over the core.\n\n| Domain            | Core Entities & Tables                                                  | Primary Ownership        |\n| :---------------- | :---------------------------------------------------------------------- | :----------------------- |\n| **Identity**      | `tenants`, `users`, `teams`, `roles`, `permissions`, `policies`         | Platform Admin / OneAuth |\n| **Entity**        | `customers`, `contacts`, `accounts`, `projects`, `products`, `vendors`  | All Roles (Scoped)       |\n| **Work**          | `tasks`, `work_items`, `queues`, `approvals`, `assignments`, `SLAs`     | All Roles (Scoped)       |\n| **Communication** | `email_threads`, `calendar_events`, `meetings`, `chat_threads`, `calls` | All Roles (Scoped)       |\n| **Knowledge**     | `documents`, `notes`, `knowledge_base`, `learning_artifacts`            | All Roles (Scoped)       |\n| **Memory**        | `user_memory`, `work_memory`, `org_memory`, `agent_memory`              | Platform (HITL-Gated)    |\n| **Capability**    | `connectors`, `mcp_tools`, `apis`, `ai_models`, `pipelines`             | Integration Manager      |\n| **Governance**    | `approval_records`, `audit_log`, `security_events`, `policies`          | Security / Admin         |\n\n### 2. Six Storage Substrates\n\n| Layer                      | Technology Substrate                        | Role in the Logical Spine                                                    |\n| :------------------------- | :------------------------------------------ | :--------------------------------------------------------------------------- |\n| **1. Structured Truth**    | **Neon** (Canonical) / **D1** (Operational) | Neon = durable historical SSOT; D1 = active runtime working set.             |\n| **2. Spine Cache**         | **Redis / Cloudflare KV**                   | Sub-100ms ephemeral state and hot working context.                           |\n| **3. Evidence Substrate**  | **Cloudflare R2 / Object Store**            | Raw payloads, attachments, invoices, and cryptographic audit receipts.       |\n| **4. Conversational**      | **Event Stream & Pipeline Log**             | Raw multi-channel communication events prior to entity promotion.            |\n| **5. Retrieval Substrate** | **Vectorize / Hybrid Search**               | Cosine similarity + BM25 keyword matching with Reciprocal Rank Fusion (RRF). |\n| **6. Agent Memory**        | **Durable Objects / SQLite**                | Session state, working hypotheses, and long-term HITL-gated memory.          |\n\n### 3. The Universal Governed Write Path\n\n> **Invariant: No surface writes directly to the database. No client reads un-projected records.**\n\n```mermaid\nflowchart LR\n    Source[\"External Event / User Intent / Twin Proposal\"] --> Loader[\"Loader\"]\n    Loader --> Normalizer[\"Normalizer\"]\n    Normalizer --> Pipeline[\"Governed Pipeline\"]\n    Pipeline --> Ops[\"Operational Update (D1)\"]\n    Pipeline --> Canon[\"Canonical Promotion & Audit (Neon)\"]\n    Pipeline --> Invalidate[\"Spine Cache Invalidation (KV)\"]\n    Pipeline --> Reconcile[\"Provider Reconciliation & Re-index\"]\n```\n\n---\n\n## IV. The User Workbench Architecture\n\n### 1. Five-Zone Layout Grammar\n\n_Normalize once, render anywhere._ Every projection across Sales, CS, Finance, RevOps, and Engineering shares this 5-zone structure:\n\n1. **Zone 1 — Header:** Identity, Continuity Score, Last Sync Status, Global Time/Owner Filters.\n2. **Zone 2 — Continuity Strip:** 4 live KPIs computed over the Spine (e.g. Health Score, Open Escalations, Pipeline Value, ARR at Risk).\n3. **Zone 3 — Object Stage (Views):** Multi-view projection (Table view for structured truth, Board view for workflow, Canvas for visual mapping).\n4. **Zone 4 — Context Path (Inspector):** Active entity details, relationship graph, linked communication threads, and source provenance.\n5. **Zone 5 — Governed Action Tray (Twin):** Object-scoped intelligence with 1-click verifiable proposals (_Explain, Draft, Propose, Reconcile_).\n\n### 2. The Twin Invocation Model\n\nThe Twin is **invoked on a specific object** (an account, a ticket, a document, or an escalation). It is not an idle chat sidebar.\n\n```text\nObject Selected (e.g. Acme Corp)\n   ↓\nContext Path Fetch (Spine Graph & Timeline)\n   ↓\nUnderstand → Propose → Govern → Execute → Reconcile → Learn\n```\n"}