{"slug":"strategy/business-strategy/UNIVERSAL_TENANT_SPINE_AND_CUSTOMER_ZERO_SCHEMA_V1","title":"IntegrateWise Universal Tenant Spine + Customer Zero Schema v1","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/business-strategy/UNIVERSAL_TENANT_SPINE_AND_CUSTOMER_ZERO_SCHEMA_V1.mdx","bytes":23038,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Canonical design baseline  \n**Tenant:** `tnt_integratewise_customer_zero`  \n**Primary workspace:** `wsp_integratewise_ops`\n\n> One tenant owns one Spine. Departments do not own separate databases. Each department is a governed projection over shared tenant truth, memory, knowledge, communications, capabilities, and execution state.\n\n## 1. Governing Rules\n\n1. **One Spine per tenant.** Role, department, and industry alter projection scope—not storage ownership.\n2. **No direct UI database reads.** Work-Bench reads projected shapes through the Projection Platform API.\n3. **All writes preserve provenance.** Every mutation records actor, origin, evidence, confidence, timestamps, and source connection.\n4. **AI proposes; humans decide.** Cognitive output enters a proposal/approval path before operational promotion.\n5. **Connect once, available everywhere.** Connector ownership is tenant-scoped, not frontend-scoped.\n6. **Provider-neutral persistence.** The logical contract is portable across PostgreSQL/Neon/Supabase or D1-compatible adapters.\n\n## 2. Universal Record Envelope\n\nEvery operational table carries this minimum contract:\n\n```sql\nid                   text primary key,\ntenant_id            text not null,\nworkspace_id         text,\nstatus               text not null,\nversion              integer not null default 1,\norigin               text not null,\nconfidence           numeric(5,4),\nsource_connection_id text,\nprovenance           jsonb not null default '[]',\nmetadata             jsonb not null default '{}',\ncreated_by           text,\nupdated_by           text,\ncreated_at           timestamptz not null,\nupdated_at           timestamptz not null,\narchived_at          timestamptz\n```\n\nAll tenant queries require `tenant_id`. Sensitive projections additionally require workspace, role, permission, and policy checks.\n\n## 3. Shared Tenant Spine\n\n### 3.1 Identity and Tenancy\n\n- `tenants`: `id`, `slug`, `name`, `plan`, `industry`, `region`, `continuity_score`, `schema_version`.\n- `workspaces`: `id`, `tenant_id`, `name`, `type`, `department`, `industry`, `projection_manifest_id`, `status`.\n- `users`: `id`, `tenant_id`, `email`, `display_name`, `title`, `department`, `manager_id`, `timezone`, `locale`.\n- `teams`: `id`, `tenant_id`, `name`, `department`, `owner_user_id`.\n- `roles`: `id`, `tenant_id`, `name`, `department`, `scope`, `governance_posture`.\n- `permissions`: `id`, `key`, `resource`, `action`, `risk_level`.\n- `role_permissions`: `role_id`, `permission_id`, `conditions`.\n- `memberships`: `user_id`, `workspace_id`, `role_id`, `status`.\n\n### 3.2 Entity and Relationship Truth\n\n- `entities`: canonical entity anchor with `entity_type`, `name`, `external_keys`, `attributes`, `lifecycle`, `owner_user_id`.\n- `relationships`: `from_entity_id`, `to_entity_id`, `relationship_type`, `strength`, `valid_from`, `valid_to`.\n- `entity_versions`: append-only snapshots by entity version.\n- `timeline_events`: append-only operational history with `event_type`, `subject_entity_id`, `payload`, `evidence_refs`.\n- `evidence`: source citations, hashes, document spans, connector references, and observed timestamps.\n- `attachments`: object references only; binary data remains in object storage.\n\n### 3.3 Work, Governance, and Signals\n\n- `tasks`: `title`, `description`, `assignee_id`, `priority`, `due_at`, `entity_id`, `source`, `completion_state`.\n- `work_items`: generalized operational item with `work_type`, `queue_id`, `sla_due_at`, `payload`.\n- `queues`: `name`, `department`, `routing_policy`, `owner_team_id`.\n- `assignments`: `work_item_id`, `assignee_id`, `assigned_by`, `assigned_at`, `released_at`.\n- `approvals`: `proposal_id`, `capability_id`, `risk_level`, `approver_chain`, `decision`, `decided_by`, `decided_at`.\n- `proposals`: `proposal_type`, `subject_entity_id`, `recommended_action`, `reasoning_summary`, `confidence`, `evidence_refs`.\n- `signals`: `kind`, `priority`, `subject_entity_id`, `score`, `title`, `summary`, `detected_at`, `expires_at`, `resolution_state`.\n- `policies`: approval, retention, write-back, data visibility, and capability policies.\n\n### 3.4 Communications and Knowledge\n\n- `communication_threads`: `channel`, `subject`, `participants`, `linked_entity_ids`, `last_message_at`.\n- `messages`: `thread_id`, `sender`, `recipients`, `body_ref`, `sent_at`, `classification`.\n- `calendar_events`: `title`, `starts_at`, `ends_at`, `attendees`, `linked_entity_ids`, `meeting_state`.\n- `meetings`: `calendar_event_id`, `summary`, `transcript_ref`, `decisions`, `actions`.\n- `calls`: `direction`, `participants`, `duration_seconds`, `recording_ref`, `outcome`.\n- `documents`: `title`, `document_type`, `storage_ref`, `mime_type`, `owner_id`, `linked_entity_ids`.\n- `document_chunks`: `document_id`, `chunk_index`, `content_hash`, `embedding_ref`, `classification`.\n- `notes`: `author_id`, `note_type`, `body`, `linked_entity_ids`, `visibility`.\n- `knowledge_articles`: `title`, `category`, `content_ref`, `status`, `reviewed_at`.\n\n### 3.5 Memory and Continuity\n\n- `memory_items`: `scope` (`user|work|org|agent|development|conversation`), `memory_type`, `content`, `subject_refs`, `importance`, `retention_policy`.\n- `memory_proposals`: proposed promotion with classification, confidence, dedupe cluster, and approval state.\n- `conversation_sessions`: session/channel continuity metadata.\n- `agent_sessions`: Twin/Triage runtime state references.\n- `continuity_contexts`: effective role, workspace, active entities, active goals, connected capabilities, and recent evidence.\n\n### 3.6 Capability and Integration Spine\n\n- `connectors`: catalogue record with `provider`, `category`, `auth_type`, `is_mcp`, `release_state`, `supported_objects`.\n- `connections`: tenant-owned installation with `connector_id`, `connected_by`, `provider_account`, `health`, `last_sync_at`.\n- `credential_refs`: vault references only; raw secrets are never projected.\n- `sync_jobs`: `connection_id`, `sync_type`, `cursor`, `started_at`, `completed_at`, `records_processed`, `error_class`.\n- `field_mappings`: source-to-canonical field mappings and transformation rules.\n- `webhooks`: endpoint registration, signature policy, event subscriptions, health.\n- `capabilities`: `key`, `plane`, `inputs`, `outputs`, `required_scopes`, `governance_policy`, `surface_compatibility`.\n- `capability_invocations`: request, authorization, execution, result, rollback, and audit state.\n- `mcp_servers` and `mcp_tools`: MCP registry, tool manifests, resource URIs, scopes, and health.\n- `ai_models`: provider, model, capability class, tenant policy, cost and latency metadata.\n\n### 3.7 Platform Operations\n\n- `deployments`, `environments`, `service_health`, `incidents`, `audit_events`, `billing_accounts`, `subscriptions`, `usage_events`, `api_clients`, `api_keys`, `security_events`.\n\n## 4. Department Projection Schemas\n\n### 4.1 Account Success\n\n**Tables:** `accounts`, `account_contacts`, `account_health_logs`, `account_tasks`, `account_playbooks`, `account_signals`, `renewals`, `adoption_milestones`.  \n**KPIs:** managed ARR, average health, renewals due, accounts at risk.  \n**Signals:** churn risk, adoption decline, executive silence, renewal opportunity.  \n**Capabilities:** prepare QBR, create success plan, draft outreach, update CRM, schedule meeting.  \n**Approval boundary:** customer-facing sends and contractual changes require approval.  \n**Views:** Dashboard, Accounts, Contacts, Renewals, Risk Matrix, Meetings, Projects, Tasks, Documents, Calendar.\n\n### 4.2 Sales\n\n**Tables:** `leads`, `opportunities`, `deals`, `sales_activities`, `quotes`, `sales_sequences`, `sales_signals`, `forecast_snapshots`.  \n**KPIs:** pipeline value, weighted forecast, win rate, stalled deals.  \n**Signals:** buying intent, stage stall, close-date slip, competitor mention, forecast risk.  \n**Capabilities:** qualify lead, update stage, draft follow-up, create quote, schedule call.  \n**Approval boundary:** discounts, pricing changes, legal commitments, and external sends follow policy.  \n**Views:** Dashboard, Pipeline, Deals, Leads, Activities, Sequences, Forecast, Quota, Accounts, Contacts.\n\n### 4.3 Marketing\n\n**Tables:** `campaigns`, `campaign_members`, `content_assets`, `attribution_events`, `audience_segments`, `marketing_spend`, `marketing_signals`, `forms`.  \n**KPIs:** sourced pipeline, influenced pipeline, campaign ROI, qualified leads.  \n**Signals:** channel anomaly, content gap, audience saturation, attribution conflict.  \n**Capabilities:** create campaign, publish content, adjust budget, generate brief, route lead.  \n**Approval boundary:** public publishing, spend changes, and regulated claims require approval.  \n**Views:** Dashboard, Campaigns, Leads, Email Studio, Social, Blog, Website, Forms, Attribution, Analytics.\n\n### 4.4 Revenue Operations\n\n**Tables:** `pipelines`, `pipeline_stages`, `routing_rules`, `territories`, `quota_plans`, `forecast_models`, `revenue_metrics`, `revops_signals`.  \n**KPIs:** coverage ratio, conversion by stage, forecast accuracy, routing SLA.  \n**Signals:** funnel leakage, routing failure, duplicate ownership, forecast variance, capacity risk.  \n**Capabilities:** modify routing rule, reconcile pipeline, assign territory, publish forecast, repair ownership.  \n**Approval boundary:** production routing, quota, compensation, and ownership model changes require elevated approval.  \n**Views:** Command Center, Pipeline Health, Routing, Territories, Forecast, Quotas, Data Quality, Analytics.\n\n### 4.5 Finance\n\n**Tables:** `invoices`, `payments`, `budgets`, `expenses`, `subscriptions`, `vendors`, `cashflow_snapshots`, `finance_signals`.  \n**KPIs:** cash balance, overdue receivables, burn, runway, budget variance.  \n**Signals:** late payment, cashflow risk, anomaly, duplicate invoice, renewal exposure.  \n**Capabilities:** approve expense, mark paid, generate invoice, reconcile payment, update forecast.  \n**Approval boundary:** payment release, voids, bank changes, budget overrides, and high-value expenses.  \n**Views:** Dashboard, Revenue, Expenses, Invoices, Invoice Approvals, Reports, Forecasting, Budget.\n\n### 4.6 Operations / Business Ops\n\n**Tables:** `operating_plans`, `projects`, `milestones`, `dependencies`, `processes`, `workflows`, `operational_metrics`, `ops_signals`.  \n**KPIs:** active initiatives, milestone health, blocked work, SLA attainment.  \n**Signals:** dependency risk, milestone slip, process failure, capacity bottleneck.  \n**Capabilities:** create project, assign owner, update milestone, trigger workflow, escalate blocker.  \n**Approval boundary:** cross-department priority changes and irreversible workflow actions.  \n**Views:** Dashboard, Command Center, Strategic Hub, Projects, Tasks, Calendar, Workflows, Metrics, Analytics.\n\n### 4.7 Product & Engineering\n\n**Tables:** `products`, `roadmap_items`, `features`, `requirements`, `sprints`, `engineering_tasks`, `bugs`, `releases`, `repositories`, `deployments`, `engineering_signals`.  \n**KPIs:** roadmap progress, sprint completion, escaped defects, deployment health.  \n**Signals:** release risk, regression, blocked dependency, incident recurrence, scope drift.  \n**Capabilities:** create issue, update roadmap, start release, request review, rollback deployment.  \n**Approval boundary:** production deployment, destructive repository actions, security-sensitive changes.  \n**Views:** Dashboard, Roadmap, Features, Bugs, Sprints, Releases, Feedback, Repositories, Deployments.\n\n### 4.8 Support & Service\n\n**Tables:** `tickets`, `cases`, `sla_policies`, `sla_events`, `escalations`, `support_interactions`, `csat_responses`, `support_signals`.  \n**KPIs:** open tickets, SLA risk, first-response time, CSAT, escalation count.  \n**Signals:** breach risk, customer frustration, repeated issue, deflection opportunity.  \n**Capabilities:** respond, resolve, escalate, create knowledge article, update priority.  \n**Approval boundary:** refunds, contractual concessions, sensitive disclosures, and bulk responses.  \n**Views:** Dashboard, Tickets, Customers, SLA, Escalations, CSAT, Knowledge, Queue.\n\n### 4.9 IT & Security\n\n**Tables:** `systems`, `assets`, `licenses`, `certificates`, `vulnerabilities`, `incidents`, `access_requests`, `security_controls`, `it_signals`.  \n**KPIs:** service availability, open incidents, critical vulnerabilities, expiring certificates.  \n**Signals:** outage, credential anomaly, certificate expiry, vulnerability exposure, license overage.  \n**Capabilities:** create incident, revoke session, rotate credential, patch asset, renew certificate.  \n**Approval boundary:** privileged access, key rotation, destructive remediation, production configuration.  \n**Views:** Dashboard, Systems, Incidents, Vulnerabilities, Certificates, Licenses, Access, Security.\n\n### 4.10 HR & People Ops\n\n**Tables:** `employees`, `positions`, `teams`, `onboarding_plans`, `performance_cycles`, `leave_records`, `compensation_records`, `people_signals`.  \n**KPIs:** headcount, open roles, onboarding completion, retention risk, leave load.  \n**Signals:** flight risk, onboarding blocker, review overdue, hiring milestone, policy exception.  \n**Capabilities:** start onboarding, approve leave, create review cycle, update position, initiate offboarding.  \n**Approval boundary:** compensation, termination, medical data, and sensitive employee actions.  \n**Views:** Dashboard, People, Org Chart, Hiring, Onboarding, Performance, Leave, Policies.\n\n### 4.11 Legal & Compliance\n\n**Tables:** `contracts`, `contract_parties`, `obligations`, `legal_requests`, `policies`, `compliance_controls`, `evidence_requests`, `legal_signals`.  \n**KPIs:** contracts awaiting review, obligations due, policy exceptions, control coverage.  \n**Signals:** renewal deadline, missing clause, compliance gap, data-processing risk, obligation breach.  \n**Capabilities:** request review, generate clause proposal, assign obligation, publish policy, open legal matter.  \n**Approval boundary:** signature, clause acceptance, regulatory representation, data-retention exceptions.  \n**Views:** Dashboard, Contracts, Matters, Obligations, Policies, Compliance, Evidence, Approvals.\n\n### 4.12 Founder / Executive Ops\n\n**Tables:** `strategic_goals`, `company_metrics`, `executive_decisions`, `board_items`, `investor_updates`, `fundraising_pipeline`, `founder_projects`, `executive_signals`.  \n**KPIs:** runway, revenue, pipeline, product delivery, customer risk, hiring plan.  \n**Signals:** cross-department blocker, strategic drift, runway risk, major account risk, release risk.  \n**Capabilities:** create decision, assign cross-functional action, approve exception, publish update, initiate review.  \n**Approval boundary:** Founder Ops can view across departments but writes remain subject to owning-domain policy.  \n**Views:** Founder Today, Company Pulse, Projects, Decisions, Customers, Revenue, Product, People, Risks, Knowledge.\n\n## 5. Platform Projections\n\n- **Integration Manager:** connectors, connections, credentials, sync jobs, mappings, webhooks, integration signals.\n- **Connector Marketplace:** catalogue, listings, release state, installation, authorization, capabilities, documentation.\n- **Activation Hub:** onboarding sessions, role/department/industry selection, initial connectors, hydration progress, readiness.\n- **Capability Manager:** capability registry, policies, invocation history, compatibility, rollback.\n- **MCP Pool:** servers, tools, resources, operational/cognitive plane, health, scopes.\n- **Knowledge:** documents, chunks, articles, evidence, embeddings, publication workflow.\n- **Memory & Continuity:** intake, triage, promotion queue, user/work/org memory, continuity contexts.\n- **Automation & Pipelines:** workflows, triggers, runs, pipeline stages, retries, dead letters.\n- **Governance:** proposals, approvals, policies, exceptions, immutable provenance.\n- **Observability:** service health, traces, alerts, incidents, cost and latency.\n- **Administration:** organizations, users, roles, permissions, audit, billing, deployments, API keys, security.\n\n## 6. Customer Zero Tenant Manifest\n\nCustomer Zero is not a separate schema. It is the first fully populated tenant using every shared domain and selected departmental extensions.\n\n```yaml\ntenant:\n  id: tnt_integratewise_customer_zero\n  name: IntegrateWise LLP\n  industry: b2b_saas_continuity_platform\n  schema_version: tenant-spine-v1\n  governance_posture: approval_first\n  retention_days: 90\n\nworkspaces:\n  - wsp_founder_ops\n  - wsp_account_success\n  - wsp_sales\n  - wsp_marketing\n  - wsp_revops\n  - wsp_finance\n  - wsp_operations\n  - wsp_product_engineering\n  - wsp_support\n  - wsp_it_security\n  - wsp_people_ops\n  - wsp_legal\n  - wsp_platform_ops\n```\n\n### 6.1 Seed Users and Roles\n\n- Nirmal Prince — Founder & CEO — Founder Ops, Platform Admin, Executive approvals.\n- Account Success Manager — accounts, renewals, QBRs, risk response.\n- Sales Lead — pipeline, opportunities, forecasts, outreach.\n- Marketing Lead — campaigns, content, attribution, leads.\n- Finance Manager — invoices, subscriptions, expenses, cashflow.\n- Product/Engineering Lead — roadmap, releases, defects, deployments.\n- Support Lead — queues, SLAs, escalations, knowledge.\n- Integration Manager — connector catalogue, sync health, mappings, MCP pool.\n- People Ops Manager — hiring, onboarding, performance, leave.\n- Legal/Compliance Owner — contracts, obligations, policies, evidence.\n\n### 6.2 Seed Connections\n\n- GitHub organization and repositories.\n- Gmail or Microsoft 365 mail/calendar.\n- Slack or Microsoft Teams communications.\n- Coda and/or Notion knowledge sources.\n- Attio or current CRM source.\n- Cloudflare operational infrastructure.\n- Vercel/release frontend deployment source where applicable.\n- AI providers registered in the cognitive plane, not as operational truth connectors.\n\nEach connection seeds connector capabilities, sync policy, health, cursors, source identifiers, and tenant ownership. Credentials remain vault-side.\n\n### 6.3 Cross-Department Seed Entities\n\n- **Company:** IntegrateWise LLP.\n- **Products/surfaces:** IntegrateWise Workbench, IW-Spine-Network Plugin,\n  IW-Spine-Network MCP and Connector Marketplace.\n- **Projects:** Public connector go-live, Work-Bench Spine wiring, Customer Zero activation, marketplace submission, infrastructure portability.\n- **Customers/Prospects:** Customer Zero plus realistic SaaS accounts and current founder-led opportunities.\n- **Repositories:** `integratewise-live`, `work-bench`, AI workspace and marketplace packages.\n- **Connectors:** the existing connector catalogue, with production/beta/preview/internal release states.\n- **Documents:** canonical architecture, marketplace package, onboarding specifications, deployment runbooks, security policies.\n- **Decisions:** provider choices, connector ownership doctrine, one-Spine projection rule, Twin/Triage boundaries.\n\n### 6.4 Believable Operational Seed\n\n1. A connector token-expiry signal assigned to Integration Manager and visible in Founder Ops.\n2. A marketplace publication project with engineering tasks, legal review, marketing launch items, and executive milestones.\n3. A customer account with CRM opportunity, email thread, support risk, invoice, renewal, and QBR action linked to one canonical account.\n4. A production deployment with GitHub commit, deployment record, incident signal, approval, and remediation task.\n5. A document ingested into Knowledge, chunked and embedded, with a proposed Org Memory promotion awaiting approval.\n6. A Twin proposal backed by evidence, routed through Governance, approved by the user, executed through a capability, and written back to the timeline.\n\n### 6.5 Minimum Seed Counts\n\n- 1 tenant and 13 workspaces.\n- 10 users, 12 roles, and role-permission mappings.\n- 12–20 connectors with mixed release/health states; existing full catalogue remains available.\n- 25 accounts/organizations, 60 contacts, 20 leads, 12 opportunities/deals.\n- 20 projects, 80 tasks/work items, 12 queues.\n- 40 communication threads, 30 calendar events, 15 meetings.\n- 50 documents/notes/knowledge records.\n- 30 signals, 12 proposals, 8 pending approvals.\n- 30 memory items across user, work, org, agent, development, and conversation scopes.\n- 10 deployments, 5 incidents, and 100 audit/timeline events.\n\n## 7. Projection API Contract\n\n```http\nGET /api/v1/workspaces/{workspaceId}/projection\nGET /api/v1/projections/{department}/home\nGET /api/v1/projections/{department}/entities\nGET /api/v1/projections/{department}/signals\nGET /api/v1/projections/{department}/work\nGET /api/v1/projections/{department}/approvals\nGET /api/v1/entities/{entityId}/360\nPOST /api/v1/work\nPOST /api/v1/proposals\nPOST /api/v1/approvals/{approvalId}/decision\nPOST /api/v1/capabilities/{capabilityKey}/invoke\n```\n\nProjection response envelope:\n\n```json\n{\n  \"tenant\": {},\n  \"workspace\": {},\n  \"role\": {},\n  \"continuity\": { \"score\": 0, \"lastSyncAt\": null },\n  \"pulse\": [],\n  \"records\": [],\n  \"signals\": [],\n  \"approvals\": [],\n  \"capabilities\": [],\n  \"twinContext\": {},\n  \"provenance\": []\n}\n```\n\n## 8. Work-Bench Wiring Rule\n\n`NirmalPrinceJ/work-bench` remains an Experience. It replaces null/mock hydration hooks with a tenant-aware Gateway client. Department components consume projection DTOs; they do not import database or provider SDKs.\n\nRequired replacement seams:\n\n- `useHydrateProjection(domain)` → real Projection API query.\n- `useSpine()` → authenticated tenant/workspace metadata.\n- hard-coded navigation badges → work, communication, approval, and signal counts.\n- mock Twin responses → evidence-backed Twin/Triage endpoints.\n- local entity store → Entity 360 and governed mutation endpoints.\n\n## 9. Implementation Sequence\n\n1. Convert this document into portable SQL migrations and typed contracts in `integratewise-live`.\n2. Add deterministic Customer Zero seed fixtures.\n3. Implement projection queries for Home, My Work, Communications, twelve departments, Platform, and Administration.\n4. Wire Work-Bench to those contracts.\n5. Validate one complete loop: connector event → pipeline → Spine → projection → proposal → approval → capability → source write-back → timeline/memory.\n6. Publish IW-Spine-Network Plugin, IW-Spine-Network MCP and provider connector\n   surfaces only after this tenant loop is demonstrable.\n\n## 10. Acceptance Criteria\n\n- The same canonical entity appears consistently across Sales, Account Success, Finance, Support, and Founder Ops.\n- Connected applications are tenant-owned and visible across all authorized surfaces without repeat OAuth.\n- Every departmental KPI is derived from stored fields or projection queries, never hard-coded UI values.\n- Every signal and AI proposal carries evidence, confidence, origin, and immutable provenance.\n- Every high-risk write passes Governance and appears on the audit/timeline history.\n- Work-Bench can switch departments without changing tenant truth or reconnecting infrastructure.\n"}