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