Unclassified

IntegrateWise — Canonical Reference & System Doctrine

Status: Authoritative Synthesis & System Contract
Source Baseline: integratewise-docs/canonical-reference.html
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.

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 (Spine Workspace).
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

┌──────────────────────────────────────────────────────────────────────────────────┐
│  LAYER 4: PRODUCT — THE USER WORKBENCH (Spine Workspace)                        │
│  • 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.

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:

Zone 1 — Header: Identity, Continuity Score, Last Sync Status, Global Time/Owner Filters.
Zone 2 — Continuity Strip: 4 live KPIs computed over the Spine (e.g. Health Score, Open Escalations, Pipeline Value, ARR at Risk).
Zone 3 — Object Stage (Views): Multi-view projection (Table view for structured truth, Board view for workflow, Canvas for visual mapping).
Zone 4 — Context Path (Inspector): Active entity details, relationship graph, linked communication threads, and source provenance.
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.

Object Selected (e.g. Acme Corp)
   ↓
Context Path Fetch (Spine Graph & Timeline)
   ↓
Understand → Propose → Govern → Execute → Reconcile → Learn