{"slug":"architecture/UNIVERSAL_TENANT_SPINE_SCHEMA_V1","title":"IntegrateWise Universal Tenant Spine Schema v1","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/UNIVERSAL_TENANT_SPINE_SCHEMA_V1.mdx","bytes":8870,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Authoritative schema source · reconciled with Book of Record v1.1**\n\n**AUTHORITATIVE SCHEMA SOURCE — reconciled 2026-07-28**\n\nThis page remains the authoritative Universal Tenant Spine Schema source. Its interpretation is constrained by the current Book of Record: the Base Spine is mandatory and stable; tenant, domain and provider models are additive; provenance, tenant scope and reconciliation are required.\n\nFor V0 runtime, Cloudflare D1 is the tenant Spine system of record. Frontend and AI clients access Spine data only through versioned Platform query and projection contracts.\n\n---\n\n## Core Principle\n\nOne Spine. One schema. Every role, department, and industry is a **projection** over the same core. The mandatory Base Spine remains stable; additive extensions and schema versions evolve through governance. Only what each user sees changes — based on Role × Industry × Department.\n\n**The governing principle:** The Spine holds the truth. The Projection shapes what each user sees. The schema variation lives entirely in the projection layer — not in the data layer.\n\n---\n\n## Spine as Multi-Store Fabric\n\n| Layer  | Store                          | Purpose                                            |\n| ------ | ------------------------------ | -------------------------------------------------- |\n| **L1** | PostgreSQL / D1                | Structured operational truth. The SSOT anchor.     |\n| **L2** | Redis / KV                     | Hot state. Sub-100ms. Working memory. Not truth.   |\n| **L3** | R2 / Object Storage            | Blobs linked by reference. Never queried directly. |\n| **L4** | Conversational Store           | Raw channel events. Classify → Extract → Promote.  |\n| **L5** | Vectorize / pgvector           | Semantic intelligence. Hybrid cosine + BM25 + RRF. |\n| **L6** | Agent Memory (Durable Objects) | Durable per-scope state. HITL-gated writes.        |\n\n---\n\n## Shared Tenant Spine Domains\n\n| Domain                  | Core Tables                                                                   | Owned By              |\n| ----------------------- | ----------------------------------------------------------------------------- | --------------------- |\n| **Identity Spine**      | tenants, users, teams, roles, permissions, policies                           | Platform Admin        |\n| **Entity Spine**        | customers, contacts, accounts, projects, products, assets, vendors, employees | All roles (scoped)    |\n| **Work Spine**          | tasks, work_items, queues, approvals, assignments, escalations, slas          | All roles (scoped)    |\n| **Communication Spine** | email_threads, calendar_events, meetings, chat_threads, calls                 | All roles (scoped)    |\n| **Knowledge Spine**     | documents, notes, knowledge_base, brainstorm_sessions, learning_artifacts     | All roles (scoped)    |\n| **Memory Spine**        | user_memory, work_memory, org_memory, conversation_memory, agent_memory       | Platform (HITL-gated) |\n| **Capability Spine**    | connectors, mcp_tools, apis, ai_models, automations, pipelines                | Integration Manager   |\n| **Governance Spine**    | approval_records, audit_log, security_events, compliance_records, policies    | Platform Admin        |\n| **Platform Spine**      | billing_records, deployments, api_keys, observability_events, admin_actions   | Platform Admin        |\n\n---\n\n## 12 Department Projections\n\nEach department is a governed projection over the shared Spine. See individual schema files for complete table definitions, 6-layer maps, KV patterns, R2 paths, conversational store documents, vector collections, agent memory scopes, workbench zone maps, and write paths.\n\n| Department                | Spine Domains Used                                 | Schema File                         |\n| ------------------------- | -------------------------------------------------- | ----------------------------------- |\n| Account Success           | Entity + Work + Communication + Knowledge + Memory | `docs/spine/account-success.md`     |\n| Sales                     | Entity + Work + Communication + Knowledge          | `docs/spine/sales.md`               |\n| Marketing                 | Entity + Communication + Knowledge + Work          | `docs/spine/marketing.md`           |\n| Revenue Operations        | Entity + Work + Governance                         | `docs/spine/revops.md`              |\n| Finance                   | Entity + Work + Governance + Platform              | `docs/spine/finance.md`             |\n| Operations / Business Ops | Work + Entity + Governance                         | `docs/spine/operations.md`          |\n| Product & Engineering     | Work + Capability + Knowledge + Governance         | `docs/spine/product-engineering.md` |\n| Support & Service         | Entity + Work + Communication + Knowledge          | `docs/spine/support.md`             |\n| IT & Security             | Identity + Entity + Work + Governance              | `docs/spine/it-security.md`         |\n| HR & People Ops           | Identity + Entity + Work + Knowledge               | `docs/spine/hr-people.md`           |\n| Legal & Compliance        | Entity + Work + Governance + Knowledge             | `docs/spine/legal-compliance.md`    |\n| Founder / Executive Ops   | All domains (read-only aggregate)                  | `docs/spine/founder-executive.md`   |\n\n---\n\n## Industry Extensions\n\nThe mandatory Base Spine remains stable across industries; governed industry extensions are additive.\n\n| Industry                | Entity Extensions                                         | Signal Extensions                                  |\n| ----------------------- | --------------------------------------------------------- | -------------------------------------------------- |\n| SaaS                    | subscription, mrr, churn_risk, expansion_signal           | usage_drop, renewal_risk, expansion_ready          |\n| Aerospace Manufacturing | program, satellite, subsystem, assembly_step, test_result | milestone_slip, quality_hold, supplier_delay       |\n| Healthcare              | patient, provider, appointment, claim, compliance_record  | missed_appointment, billing_error, compliance_flag |\n| Professional Services   | engagement, deliverable, timesheet, invoice, retainer     | scope_creep, budget_overrun, delivery_risk         |\n| Logistics               | shipment, route, carrier, warehouse, manifest             | delay_risk, customs_hold, capacity_alert           |\n\n---\n\n## Write Paths\n\n### Channel Event (any source)\n\n```\n-> Conversational Store (append)\n-> 8-Stage Pipeline: Ingest -> Parse -> Classify -> Extract -> Enrich -> Route -> Govern -> Promote\n-> D1 canonical write (role-scoped tables)\n-> KV/cache invalidation (affected keys)\n-> Vector re-embedding (affected collections)\n-> Twin memory update proposal (if memory-worthy)\n```\n\n### User Action (workbench)\n\n```\n-> Governance check\n-> Projection Platform API write\n-> Webhook / ADK write-back to source system\n-> KV/cache invalidation\n-> Signal Platform: evaluate if action resolves a signal\n```\n\n### Twin Proposal (AI-generated)\n\n```\n-> Governance Platform: create pending approval record\n-> Workbench: render approval card to user\n-> User approves -> D1 canonical write with approved_by + approval_id\n-> User rejects -> audit log write, no Spine write\n-> Provenance preserved forever: origin, confidence, approved_by, approved_at\n```\n\n---\n\n## Governance Rules\n\n1. No workbench component may read directly from a database. All reads go through the Projection Platform API.\n2. No AI-proposed write lands in the Spine without HITL approval.\n3. Provenance is immutable. A Twin-proposed entry that passes approval arrives tagged `origin: twin, confidence: 0.xx`. It does not become native truth.\n4. Every operational table carries the Universal Record Envelope: id, tenant_id, workspace_id, status, version, origin, confidence, source_connection_id, provenance, metadata, created_by, updated_by, created_at, updated_at, archived_at.\n\n---\n\n## Canonical Implementation Companion\n\nSee `docs/SPINE_SCHEMA_V1_ALL_DEPARTMENTS.md` for:\n\n- Shared record envelope\n- Twelve department projections with complete table definitions\n- Platform projections\n- Customer Zero seed manifest\n- Projection API contract\n- Work-Bench wiring rules\n- Acceptance criteria\n\n---\n\n## Customer Zero\n\n**Tenant:** `tnt_integratewise_customer_zero`\n**Primary workspace:** `wsp_integratewise_ops`\n**Industry:** b2b_saas_continuity_platform\n**Governance posture:** approval_first\n\n13 workspaces, 10 users, 12 roles, 12-20 connectors, 25 accounts, 60 contacts, 20 leads, 12 deals, 20 projects, 80 tasks, 40 threads, 50 documents, 30 signals, 12 proposals, 8 pending approvals, 30 memory items, 10 deployments, 5 incidents, 100 audit events.\n"}