{"slug":"internal/architecture/CANONICAL_REFERENCE","title":"IntegrateWise Canonical Reference","section":"internal","sectionLabel":"Internal","status":"current","type":"document","path":"internal/architecture/CANONICAL_REFERENCE.mdx","bytes":10296,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** FROZEN — August 11, 2026\n**Source:** Merged from Auth Ecosystem, UI/Workbench Design, Universal Tenant Spine Schema, and repo excavation\n\n---\n\n## I. The Model in One Breath\n\n### 1. Category definition\n\nThe Self-Organizing Workspace is a collaborative environment where humans and AI continuously structure work, context, and capabilities around evolving goals.\n\n### 2. The precise statement\n\nIntegrateWise is a Continuity Platform delivered through a self-organizing User Workbench.\n\n**Platform underneath. Product in front. Promise first.**\n\nMarketing order: Promise → Product → Outcome → Platform proof. Never lead with the platform, MCP fabric, or a catalogue of agents.\n\n### 3. The product promise\n\n**Frozen.**\nNothing is forgotten. Context follows the work. The workspace organizes itself. The user remains in control.\n\n---\n\n## II. The Five Layers\n\n### 1. OneAuth — entry to the ecosystem\n\nHost-controlled auth, not an IntegrateWise login. The host owns identity and the real provider connections; IntegrateWise never copies credentials.\n\nResolves: identity, tenant, workspace, roles, entitlements, host session, policies.\nConnectors arrive as governed projections of connections the host already owns.\n\n**Frozen rule:** OneAuth establishes trusted entry; connector projections expose permitted capabilities of host-owned connections.\n\n### 2. Product Package — the capability kernel\n\nTurns authorized connections into usable workspace capability.\n\n```\nDiscovery + Capability Resolver + Spine Cache + ADK + Orchestrator\n+ Business Context + Loader + Normalizer + MCP Connector + Tool Capability\n```\n\nFlow: discover → load → normalize → cache → resolve → execute.\nCustomers never buy this directly — they experience its output through the Workbench.\nIn the repo this is `packages/*` (reusable contracts).\n\n### 3. Spine — connected business backbone\n\n**Key correction:** The Spine is logical, not physical. Spine ≠ D1.\n\n```\nSpine = entities + relationships + identity resolution + provenance\n      + freshness + business context + continuity\n```\n\n- **Canonical Spine (Neon):** what is durably known — entities, versions, provenance, policies, historical state, reconciled outcomes.\n- **Operational Spine (D1):** what's needed to work now — active records, current KPIs, signals, runtime context.\n- **Spine Cache (KV):** fast context for workbench consumption.\n- **Evidence (R2):** blobs, attachments, source artifacts.\n- **Retrieval (Vectorize/AI Search):** semantic search over Spine-connected material.\n- **Context (Durable Objects):** interaction/session/runtime context.\n\nMemory ≠ Spine. Business Context ≠ Spine. Both connect through the Spine but are distinct.\n\n### 4. Product — the User Workbench\n\nThe one product customers use. A self-organizing workspace of:\n\n- **Tables** (structured truth)\n- **Views** (role-routed lenses)\n- **Docs** (narrative)\n\nUnified by the **Twin** — invoked on a specific item, not idling in a sidebar.\n\nOperating loop: Understand → Propose → Govern → Execute → Reconcile → Learn.\n\nIn the repo this is `apps/web`; all department subdomains are projections into web, not separate apps.\n\n### 5. Platform Backend — the runtime\n\nOperates the Package capabilities at scale.\n\n```\nPackage Runtime + Services + AI Gateway + Agents + Memory\n+ Pipelines + Governance + Execution + Observability\n```\n\nAgents live here, underneath the Twin and Workbench — internal participants, not the headline product.\n\n**Split rule:** Product Package defines reusable capability (`packages/`); Platform Backend runs it (`services/`).\n\n---\n\n## III. The Universal Tenant Spine\n\n### 1. Eight Spine domains\n\n| Domain        | Core tables                                                    | Owned by        |\n| ------------- | -------------------------------------------------------------- | --------------- |\n| Identity      | tenants, users, teams, roles, permissions, policies            | Platform Admin  |\n| Entity        | customers, contacts, accounts, projects, products, vendors     | All (scoped)    |\n| Work          | tasks, work_items, queues, approvals, assignments, SLAs        | All (scoped)    |\n| Communication | email_threads, calendar_events, meetings, chat_threads, calls  | All (scoped)    |\n| Knowledge     | documents, notes, knowledge_base, learning_artifacts           | All (scoped)    |\n| Memory        | user/work/org/conversation/agent memory                        | Platform (HITL) |\n| Capability    | connectors, mcp_tools, apis, ai_models, automations, pipelines | Integration Mgr |\n| Governance    | approval_records, audit_log, security_events, policies         | Platform Admin  |\n\n### 2. Six storage layers\n\n| Layer | Tech                 | Purpose                                            |\n| ----- | -------------------- | -------------------------------------------------- |\n| 1     | Postgres / D1        | Structured operational truth. SSOT anchor.         |\n| 2     | Redis / KV           | Hot state, sub-100ms. Working memory, not truth.   |\n| 3     | R2 / Object          | Blobs linked by reference. Never queried directly. |\n| 4     | Conversational       | Raw channel events. Classify → Extract → Promote.  |\n| 5     | Vectorize / pgvector | Semantic intelligence. Cosine + BM25 + RRF.        |\n| 6     | Agent Memory         | Durable per-scope state. HITL-gated writes.        |\n\n### 3. The universal write path\n\n**No exceptions.** No role writes directly to the database. No workbench component reads directly from one.\n\n- Channel event: Conversational Store → 8-stage pipeline → D1 canonical write → KV invalidation → re-embed → Twin memory proposal.\n- Twin proposal: Governance creates pending approval → user approves → D1 write tagged `origin: twin, confidence: 0.xx, approved_by`. Provenance is immutable.\n\n---\n\n## IV. The Workbench & Platform UI\n\n### 1. The doctrine\n\nNot a dashboard — an operational workbench. A dashboard is passive; you act on data directly without leaving the surface.\n\nOne layout grammar, many surfaces: \"Normalize once, render anywhere.\"\n\n### 2. The five-zone shell\n\n| Zone                     | Purpose                                                                   |\n| ------------------------ | ------------------------------------------------------------------------- |\n| Zone 1 — Header          | Name, Continuity Score, last sync, two cascading filters (time + owner)   |\n| Zone 2 — Pulse Bar       | Four live KPI cards from Gateway projection; click to filter              |\n| Zone 3 — Work Surface    | Table / Board / Calendar; inline capability buttons on every row          |\n| Zone 4 — OODA Action Bar | Fixed bottom — Observe, Orient, Decide (n pending), Act                   |\n| Zone 5 — Twin Panel      | 300px right rail; signals feed, pending proposals, prompt chips, Ask Twin |\n\n### 3. Sidebar — three questions\n\n1. **What do I work on?** → My Work (Home, Inbox, Tasks, My Queue, Approvals, Notifications)\n2. **Where am I working?** → Workspaces (12 department views, role-routed)\n3. **How is the platform configured?** → Platform + Administration\n\n### 4. Design system — Forest Paper\n\n| Token          | Value            | Use                      |\n| -------------- | ---------------- | ------------------------ |\n| Background     | `#F4F0E8`        | Warm white paper         |\n| Sidebar        | `#0C0C0C`        | Canvas black             |\n| Active accent  | `#2D5A3D`        | Forest green             |\n| Signals / gold | `#B8943F`        | Opportunity, warning     |\n| Risk / urgent  | `#E8693A`        | Ember                    |\n| Headings       | DM Serif Display | Titles                   |\n| Body           | Instrument Sans  | UI, labels               |\n| Numbers        | IBM Plex Mono    | All numbers & timestamps |\n\n---\n\n## V. The Frozen Rules\n\n1. **Subdomains never carry tenant identity.** Hostname = requested projection; OneAuth session = tenant authority.\n2. **Two subdomain classes only:** internal-only (platform, founder, ops, book-of-records, brandstore) and shared internal+external departmental.\n3. **Spine is logical.** Neon/D1/KV/R2/Vectorize are substrates, not the Spine itself.\n4. **No surface owns a database.** Every read goes through the Projection Platform API; every write is governed.\n5. **No AI write lands without HITL approval.** Provenance is immutable.\n6. **OneAuth never copies provider credentials.** The host owns the connection; IntegrateWise receives governed projections.\n7. **Agents sit under the Twin, not as the headline product.** Market the promise, not the platform.\n\n---\n\n## VI. App Surfaces\n\n| App               | Canonical function                         | Exposure            |\n| ----------------- | ------------------------------------------ | ------------------- |\n| `apps/web`        | User Workbench (all department subdomains) | Internal + external |\n| `apps/one-access` | OneAuth (ecosystem entry)                  | Internal + external |\n| `apps/platform`   | Platform Control Board                     | Internal only       |\n| `apps/marketing`  | Public website                             | Public              |\n| `apps/docs`       | Documentation                              | Public              |\n| `apps/mobile`     | Mobile Workbench client                    | Internal + external |\n| `apps/desktop`    | Desktop Workbench client                   | Internal + external |\n\nEverything else is a module, capability, service, projection, or route.\n\n---\n\n## VII. Repo Boundary\n\n| Tree              | Canonical meaning                                                       |\n| ----------------- | ----------------------------------------------------------------------- |\n| `apps/`           | Experience + control surfaces (target: 7)                               |\n| `packages/`       | Product Package — reusable contracts/capabilities                       |\n| `services/`       | Platform Backend — Workers, pipelines, agents, execution                |\n| `storage/runtime` | Physical Spine substrates: Neon + D1 + KV + R2 + Vectorize + DO         |\n| Spine             | Logical connected backbone — spans substrates, not a folder, not one DB |\n"}