Canonical Reference
One document, everything clubbed — final, four corrections applied. This merges the four working sources from the Auth Ecosystem thread — the layered architecture, the UI/Workbench design, the Universal Tenant Spine Schema, and the repo excavation — into a single frozen reference.
Spine of it: one product (the Self-Organizing Workspace / User Workbench), one logical Spine, and every department, role, and platform function is a projection over that Spine. No surface owns its own database.
Four contradictions resolved in this version: D1 is operational (not the system of record), the Pipeline governs all writes, departmental tables are allowed without silos, and the Twin is contextual — not a sidebar agent.
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.
This is the frozen top-line. It is outcome-first, names the human+AI partnership as co-equal, and puts evolving goals at the center — the organizing purpose the earlier "Tables/Views/Docs" framing lacked.
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 (your workspace organizes itself) → Product (Tables, Views, Docs unified by Twin) → Outcome (nothing is forgotten, context follows the work) → Platform proof (OneAuth, Spine, connectors, memory, orchestration, governance). Never lead with the platform, MCP fabric, or a catalogue of agents.
3. The product promise
Nothing is forgotten. Context follows the work. The workspace organizes itself. The user remains in control. — Frozen.
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 — one connection fans out into read / sync / Twin-search / approved-write projections without duplicating the credential.
- 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 what's available → load source data → normalize into the Spine → cache fast context → resolve allowed operations → coordinate governed execution.
- 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
The Spine is logical, not physical. Spine ≠ D1. It is entities + relationships + identity resolution + provenance + freshness + business context + continuity — spanning multiple storage substrates.
- 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. Joined to canonical via sync / hydration / reconciliation.
- Neon, D1, KV (Spine Cache), R2 (evidence), Vectorize/AI Search (retrieval), Durable Objects are substrates — none individually is the Spine.
- 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.
- The Twin is invoked on a specific object — not a sidebar agent, not idling in a rail. Selecting an account / task / risk / signal / doc / KPI creates a context path → context fetch → explain, organize, generate, propose.
- Operating loop: Understand → Propose → Govern → Execute → Reconcile → Learn.
- In the repo this is
apps/web; all department subdomains (sales, finance, support…) 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/). Every capability has a contract in packages and a runtime in services.
The Spine holds the truth. The Projection shapes what each user sees. Core identity and relationships are stable; departmental operational truth may use domain tables; role, industry, and presentation variation lives in the projection layer. — Corrected from Universal Tenant Spine Schema v1
III. The Universal Tenant Spine
1. Eight Spine domains
One schema. Every role, department, and industry is a projection over the same core. The mandatory Base Spine is stable; tenant/domain/industry models are additive.
| 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 | Neon (canonical) / D1 (operational) | Structured truth. Neon = durable canonical substrate; D1 = operational working set. |
| 2 | Redis / KV | Spine Cache. Hot state, sub-100ms. Working memory, not truth. |
| 3 | R2 / Object | Evidence/blob substrate. Linked by reference. Never queried directly. |
| 4 | Conversational | Raw channel events. Classify → Extract → Promote. |
| 5 | Vectorize / AI Search | Retrieval substrate. Cosine + BM25 + RRF. |
| 6 | Durable Objects / Agent Memory | Session/coordination + durable per-scope state. HITL-gated writes. |
D1 is not the universal system of record. D1 is operationally authoritative for the active working set (runtime truth for current Workbench operations); Neon is the canonical/durable substrate. The Spine Schema doc's "Postgres/D1 = SSOT" language should be updated to this two-substrate split, or the two docs will keep drifting.
3. The universal write path
No exceptions: No role writes directly to the database. No workbench component reads directly from one. All reads go through the Projection Platform API. Every write passes through the governed Pipeline.
- Provider / user / Twin event: Loader → Normalizer → Pipeline → operational update (D1) → canonical promotion / reconciliation (Neon) → operational refresh / cache invalidation → re-embed.
- Provider-owned data: external SaaS → Loader → Normalizer → Pipeline → canonical reconciliation → operational projection.
- Twin proposal: Governance creates pending approval → user approves → governed write tagged
origin: twin, confidence: 0.xx, approved_by. It does not become native truth. 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 (add a task, update a pipeline, approve a request, respond to email) without leaving the surface.
One layout grammar, many surfaces: "Normalize once, render anywhere" — the principle that governs the Spine governs the UI.
2. The five-zone shell
Every department uses the same shell; only data, KPIs, entities, and capabilities change.
- Zone 1 — Header: name, Continuity Score, last sync, two cascading filters (time + owner).
- Zone 2 — Pulse Bar: four live KPI cards from the 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 — Contextual Twin: not an always-on 300px rail or a passive sidebar agent. The Twin is invoked on a selected object (account, task, risk, signal, doc, KPI), which creates a context path; it then fetches context and explains / organizes / generates / proposes. It may surface as a drawer, rail, modal, or detail pane after invocation, then closes on navigate-away.
Correction applied: the UI doc's original "Zone 5 — Twin Panel: 300px right rail, always present" contradicted the product definition ("invoked on a specific item, not idling in a sidebar"). The product definition wins.
3. Sidebar — three questions
The sidebar answers three progressively broader questions: What do I work on? → Where am I working? → How is the platform configured?
- My Work (80–90% of time): Home, Inbox, Tasks, My Queue, Approvals, Notifications.
- Communications: Activity Feed, Email, Calendar, Meetings, Chat, Calls.
- Workspaces: 12 department views (Customer Zero → Knowledge), role-routed.
- Platform: Integration Manager, Connector Marketplace, Activation, Capability Manager, MCP Pool, AI Models, Knowledge, Memory, Automation, Pipelines, Governance, Observability.
- Administration: Organizations, Users, Roles, Permissions, Audit, Billing, Deployments, API Keys, Security.
4. Twelve Platform surfaces, one grammar
Every Platform page shares one anatomy: context header → KPI strip → primary management surface → collapsible Twin/inspector rail → activity & audit timeline. Do not build twelve unrelated dashboard styles.
Twin behavior is page-specific: diagnose this degraded connection (Integration Manager), explain why these records failed (Pipelines), identify the probable root cause (Observability). Rule: Twin never executes a destructive or external action from an unreviewed chat response.
5. 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 Model vs. The Real Repo
The gap the code reveals
The aspirational doc assumed 12 apps and a clean collapse to 7. The excavation of /Users/nirmal/Github/integratewise-live shows ~14 apps, ~40 services, and ~50 packages — including folders the model never mentioned and backup folders that signal active drift.
- Apps the model missed:
integrationwise-os,integratewise-core-engine,workspace,platform-console,mcp-servers. - Drift signals in packages:
config-backup-1782830543,lib-backup-1782830543— timestamped backups living in the tree. - The repo root carries 30+ loose
.mdstatus/audit files (SPEC_VS_CODE_GAP_ANALYSIS, CODEBASE_ISSUES_AND_CONFUSIONS, REPO_STRUCTURE_CLARIFICATION) — itself evidence the structure isn't yet frozen.
apps/ — actual vs. target disposition
| Real folder | Canonical role | Target |
|---|---|---|
| web | User Workbench | KEEP (the product) |
| one-access | OneAuth entry | KEEP (canonical entry) |
| platform | Platform Control Surface | KEEP |
| marketing | Public site → www | KEEP |
| docs | Public / dev docs | KEEP |
| mobile | Workbench channel | KEEP |
| desktop | Workbench channel | KEEP |
| workspace | Overlaps web? | RESOLVE vs. web |
| platform-console | Overlaps platform? | RESOLVE vs. platform |
| portfolio | A Workbench view | MERGE into web |
| mcp-servers | Infra / interop | → services + platform UI |
| integrationwise-os | Unclear (legacy?) | INVESTIGATE |
| integratewise-core-engine | Belongs in services? | INVESTIGATE → services |
Target end state: 7 legitimate app surfaces — web, one-access, platform, marketing, docs, mobile, desktop. Everything else is a module, service, projection, or route.
The repo boundary to freeze
| 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 |
Two rules to write down before freezing: (1) every Package capability has a contract in packages/ and a runtime in services/ — no orchestration logic in packages, no contract redefinition in services; (2) activation, connector, and mcp-servers each split across a user surface and a platform/service home — document which routes live where, or they regrow as standalone apps.
VI. The Frozen Rules
The non-negotiables
- Subdomains never carry tenant identity. Hostname = requested projection; OneAuth session = tenant authority. No
sales.acme.integratewise.ai. - Two subdomain classes only: internal-only (platform, founder, ops, book-of-records, brandstore) and shared internal+external departmental. No external-tenant-specific subdomains.
- Spine is logical. Neon = canonical substrate, D1 = operational substrate; KV/R2/Vectorize/DO are supporting substrates. None individually is the Spine.
- 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; Twin-origin data never masquerades as native truth.
- OneAuth never copies provider credentials. The host owns the connection; IntegrateWise receives governed projections.
- The Twin is contextual, not a sidebar agent. Invoked on a selected object, runs on a context path, closes on navigate-away.
- Every write passes through the governed Pipeline — not "straight to D1."
- Departmental tables are allowed, silos are not. Core identity + relationships stay stable; departments may use domain tables; role/industry/presentation variation lives in the projection.
The one sentence to freeze
OneAuth enters the host ecosystem. Product Package converts authorized ecosystem access into usable capabilities. Spine connects business truth across canonical, operational, evidence, retrieval, and continuity substrates. The User Workbench turns that connected truth into collaborative work. Platform Backend runs the capabilities at scale. The Self-Organizing Workspace emerges as humans and AI continuously organize work, context, and capabilities around evolving goals.
Source: _legacy/canonical-reference.html · ported to Nextra MDX 2026-08-20