> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integratewise.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# INTEGRATEWISE CANONICAL REFERENCE

# IntegrateWise — Canonical Reference & System Doctrine

**Status:** Authoritative Synthesis & System Contract\
**Source Baseline:** `integratewise-docs/canonical-reference.html`\
**Core Invariant:** *One logical Spine, one product (SpineWorkspace / User Workbench), and every department, role, and platform function is a projection over that Spine. No surface owns its own database.*

***

## I. The Model in One Breath

### 1. Category Definition

> **The Self-Organizing Workspace is a collaborative environment where humans and AI continuously structure work, context, and capabilities around evolving goals.**

* Outcome-first architecture.
* Names the human + AI partnership as co-equal.
* Puts **evolving goals** at the center of workspace organization.

### 2. The Precise Statement

> **IntegrateWise is a Continuity Platform delivered through a self-organizing User Workbench (SpineWorkspace).**
> *Platform underneath. Product in front. Promise first.*

* **Marketing & Positioning Sequence:**
  1. **Promise:** Your workspace organizes itself around your work.
  2. **Product:** Tables (structured truth), Views (role lenses), and Docs (narrative) unified by Twin.
  3. **Outcome:** Nothing is forgotten. Context follows the work.
  4. **Platform Proof:** OneAuth, Adaptive Spine, Connectors, Memory, Orchestration, and Governance.

### 3. The Product Promise (Frozen)

> **Nothing is forgotten. Context follows the work. The workspace organizes itself. The user remains in control.**

***

## II. The Five Architectural Layers

```text theme={null}
┌──────────────────────────────────────────────────────────────────────────────────┐
│  LAYER 4: PRODUCT — THE USER WORKBENCH (SpineWorkspace)                        │
│  • Tables (Structured Truth) • Views (Role-Routed Projections) • Docs (Narrative)│
│  • Contextual Twin Copilot (Invoked on Specific Objects, Not an Idle Rail)       │
└────────────────────────────────────────▲─────────────────────────────────────────┘
                                         │ Governed Projections
┌────────────────────────────────────────┴─────────────────────────────────────────┐
│  LAYER 2: PRODUCT PACKAGE (Capability Kernel)                                    │
│  • Discovery • Capability Resolver • Spine Cache • ADK • Loader • Normalizer     │
│  • packages/*: Reusable contracts defining what is possible                      │
└────────────────────────────────────────▲─────────────────────────────────────────┘
                                         │ Synchronizes & Normalizes
┌────────────────────────────────────────┴─────────────────────────────────────────┐
│  LAYER 3: THE ADAPTIVE SPINE (Logical Business Backbone)                         │
│  • Canonical Spine (Neon / Postgres): Durable SSOT, provenance, audit, policies  │
│  • Operational Spine (D1 / KV): Working set, active KPIs, signals, fast context  │
│  • Substrates: Neon (Truth), D1 (Ops), KV (Cache), R2 (Evidence), Vectorize (RRF)│
└────────────────────────────────────────▲─────────────────────────────────────────┘
                                         │ Powered & Governed By
┌────────────────────────────────────────┴─────────────────────────────────────────┐
│  LAYER 5: PLATFORM BACKEND (Execution Runtime)                                   │
│  • Package Runtime • AI Gateway • Agent Orchestration • Memory • Pipeline Engine │
│  • services/*: Runs capabilities at enterprise scale with HITL governance        │
└────────────────────────────────────────▲─────────────────────────────────────────┘
                                         │ Access Controlled Via
┌────────────────────────────────────────┴─────────────────────────────────────────┐
│  LAYER 1: ONEAUTH (Entry & Session Ingress)                                      │
│  • Host-controlled authentication • Zero client credential copies                │
│  • Resolves identity, tenant, workspace, roles, entitlements, and policies       │
└──────────────────────────────────────────────────────────────────────────────────┘
```

***

## III. The Universal Tenant Spine

### 1. Eight Spine Domains

One unified schema where every role, department, and vertical is an additive projection over the core.

| Domain            | Core Entities & Tables                                                  | Primary Ownership        |
| :---------------- | :---------------------------------------------------------------------- | :----------------------- |
| **Identity**      | `tenants`, `users`, `teams`, `roles`, `permissions`, `policies`         | Platform Admin / OneAuth |
| **Entity**        | `customers`, `contacts`, `accounts`, `projects`, `products`, `vendors`  | All Roles (Scoped)       |
| **Work**          | `tasks`, `work_items`, `queues`, `approvals`, `assignments`, `SLAs`     | All Roles (Scoped)       |
| **Communication** | `email_threads`, `calendar_events`, `meetings`, `chat_threads`, `calls` | All Roles (Scoped)       |
| **Knowledge**     | `documents`, `notes`, `knowledge_base`, `learning_artifacts`            | All Roles (Scoped)       |
| **Memory**        | `user_memory`, `work_memory`, `org_memory`, `agent_memory`              | Platform (HITL-Gated)    |
| **Capability**    | `connectors`, `mcp_tools`, `apis`, `ai_models`, `pipelines`             | Integration Manager      |
| **Governance**    | `approval_records`, `audit_log`, `security_events`, `policies`          | Security / Admin         |

### 2. Six Storage Substrates

| Layer                      | Technology Substrate                        | Role in the Logical Spine                                                    |
| :------------------------- | :------------------------------------------ | :--------------------------------------------------------------------------- |
| **1. Structured Truth**    | **Neon** (Canonical) / **D1** (Operational) | Neon = durable historical SSOT; D1 = active runtime working set.             |
| **2. Spine Cache**         | **Redis / Cloudflare KV**                   | Sub-100ms ephemeral state and hot working context.                           |
| **3. Evidence Substrate**  | **Cloudflare R2 / Object Store**            | Raw payloads, attachments, invoices, and cryptographic audit receipts.       |
| **4. Conversational**      | **Event Stream & Pipeline Log**             | Raw multi-channel communication events prior to entity promotion.            |
| **5. Retrieval Substrate** | **Vectorize / Hybrid Search**               | Cosine similarity + BM25 keyword matching with Reciprocal Rank Fusion (RRF). |
| **6. Agent Memory**        | **Durable Objects / SQLite**                | Session state, working hypotheses, and long-term HITL-gated memory.          |

### 3. The Universal Governed Write Path

> **Invariant: No surface writes directly to the database. No client reads un-projected records.**

```mermaid theme={null}
flowchart LR
    Source["External Event / User Intent / Twin Proposal"] --> Loader["Loader"]
    Loader --> Normalizer["Normalizer"]
    Normalizer --> Pipeline["Governed Pipeline"]
    Pipeline --> Ops["Operational Update (D1)"]
    Pipeline --> Canon["Canonical Promotion & Audit (Neon)"]
    Pipeline --> Invalidate["Spine Cache Invalidation (KV)"]
    Pipeline --> Reconcile["Provider Reconciliation & Re-index"]
```

***

## IV. The User Workbench Architecture

### 1. Five-Zone Layout Grammar

*Normalize once, render anywhere.* Every projection across Sales, CS, Finance, RevOps, and Engineering shares this 5-zone structure:

1. **Zone 1 — Header:** Identity, Continuity Score, Last Sync Status, Global Time/Owner Filters.
2. **Zone 2 — Continuity Strip:** 4 live KPIs computed over the Spine (e.g. Health Score, Open Escalations, Pipeline Value, ARR at Risk).
3. **Zone 3 — Object Stage (Views):** Multi-view projection (Table view for structured truth, Board view for workflow, Canvas for visual mapping).
4. **Zone 4 — Context Path (Inspector):** Active entity details, relationship graph, linked communication threads, and source provenance.
5. **Zone 5 — Governed Action Tray (Twin):** Object-scoped intelligence with 1-click verifiable proposals (*Explain, Draft, Propose, Reconcile*).

### 2. The Twin Invocation Model

The Twin is **invoked on a specific object** (an account, a ticket, a document, or an escalation). It is not an idle chat sidebar.

```text theme={null}
Object Selected (e.g. Acme Corp)
   ↓
Context Path Fetch (Spine Graph & Timeline)
   ↓
Understand → Propose → Govern → Execute → Reconcile → Learn
```