Unclassified

IntegrateWise Universal Tenant Spine + Customer Zero Schema v1

Status: Canonical design baseline
Tenant: tnt_integratewise_customer_zero
Primary workspace: wsp_integratewise_ops

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.

1. Governing Rules

  1. One Spine per tenant. Role, department, and industry alter projection scope—not storage ownership.
  2. No direct UI database reads. Work-Bench reads projected shapes through the Projection Platform API.
  3. All writes preserve provenance. Every mutation records actor, origin, evidence, confidence, timestamps, and source connection.
  4. AI proposes; humans decide. Cognitive output enters a proposal/approval path before operational promotion.
  5. Connect once, available everywhere. Connector ownership is tenant-scoped, not frontend-scoped.
  6. Provider-neutral persistence. The logical contract is portable across PostgreSQL/Neon/Supabase or D1-compatible adapters.

2. Universal Record Envelope

Every operational table carries this minimum contract:

id                   text primary key,
tenant_id            text not null,
workspace_id         text,
status               text not null,
version              integer not null default 1,
origin               text not null,
confidence           numeric(5,4),
source_connection_id text,
provenance           jsonb not null default '[]',
metadata             jsonb not null default '{}',
created_by           text,
updated_by           text,
created_at           timestamptz not null,
updated_at           timestamptz not null,
archived_at          timestamptz

All tenant queries require tenant_id. Sensitive projections additionally require workspace, role, permission, and policy checks.

3. Shared Tenant Spine

3.1 Identity and Tenancy

  • tenants: id, slug, name, plan, industry, region, continuity_score, schema_version.
  • workspaces: id, tenant_id, name, type, department, industry, projection_manifest_id, status.
  • users: id, tenant_id, email, display_name, title, department, manager_id, timezone, locale.
  • teams: id, tenant_id, name, department, owner_user_id.
  • roles: id, tenant_id, name, department, scope, governance_posture.
  • permissions: id, key, resource, action, risk_level.
  • role_permissions: role_id, permission_id, conditions.
  • memberships: user_id, workspace_id, role_id, status.

3.2 Entity and Relationship Truth

  • entities: canonical entity anchor with entity_type, name, external_keys, attributes, lifecycle, owner_user_id.
  • relationships: from_entity_id, to_entity_id, relationship_type, strength, valid_from, valid_to.
  • entity_versions: append-only snapshots by entity version.
  • timeline_events: append-only operational history with event_type, subject_entity_id, payload, evidence_refs.
  • evidence: source citations, hashes, document spans, connector references, and observed timestamps.
  • attachments: object references only; binary data remains in object storage.

3.3 Work, Governance, and Signals

  • tasks: title, description, assignee_id, priority, due_at, entity_id, source, completion_state.
  • work_items: generalized operational item with work_type, queue_id, sla_due_at, payload.
  • queues: name, department, routing_policy, owner_team_id.
  • assignments: work_item_id, assignee_id, assigned_by, assigned_at, released_at.
  • approvals: proposal_id, capability_id, risk_level, approver_chain, decision, decided_by, decided_at.
  • proposals: proposal_type, subject_entity_id, recommended_action, reasoning_summary, confidence, evidence_refs.
  • signals: kind, priority, subject_entity_id, score, title, summary, detected_at, expires_at, resolution_state.
  • policies: approval, retention, write-back, data visibility, and capability policies.

3.4 Communications and Knowledge

  • communication_threads: channel, subject, participants, linked_entity_ids, last_message_at.
  • messages: thread_id, sender, recipients, body_ref, sent_at, classification.
  • calendar_events: title, starts_at, ends_at, attendees, linked_entity_ids, meeting_state.
  • meetings: calendar_event_id, summary, transcript_ref, decisions, actions.
  • calls: direction, participants, duration_seconds, recording_ref, outcome.
  • documents: title, document_type, storage_ref, mime_type, owner_id, linked_entity_ids.
  • document_chunks: document_id, chunk_index, content_hash, embedding_ref, classification.
  • notes: author_id, note_type, body, linked_entity_ids, visibility.
  • knowledge_articles: title, category, content_ref, status, reviewed_at.

3.5 Memory and Continuity

  • memory_items: scope (user|work|org|agent|development|conversation), memory_type, content, subject_refs, importance, retention_policy.
  • memory_proposals: proposed promotion with classification, confidence, dedupe cluster, and approval state.
  • conversation_sessions: session/channel continuity metadata.
  • agent_sessions: Twin/Triage runtime state references.
  • continuity_contexts: effective role, workspace, active entities, active goals, connected capabilities, and recent evidence.

3.6 Capability and Integration Spine

  • connectors: catalogue record with provider, category, auth_type, is_mcp, release_state, supported_objects.
  • connections: tenant-owned installation with connector_id, connected_by, provider_account, health, last_sync_at.
  • credential_refs: vault references only; raw secrets are never projected.
  • sync_jobs: connection_id, sync_type, cursor, started_at, completed_at, records_processed, error_class.
  • field_mappings: source-to-canonical field mappings and transformation rules.
  • webhooks: endpoint registration, signature policy, event subscriptions, health.
  • capabilities: key, plane, inputs, outputs, required_scopes, governance_policy, surface_compatibility.
  • capability_invocations: request, authorization, execution, result, rollback, and audit state.
  • mcp_servers and mcp_tools: MCP registry, tool manifests, resource URIs, scopes, and health.
  • ai_models: provider, model, capability class, tenant policy, cost and latency metadata.

3.7 Platform Operations

  • deployments, environments, service_health, incidents, audit_events, billing_accounts, subscriptions, usage_events, api_clients, api_keys, security_events.

4. Department Projection Schemas

4.1 Account Success

Tables: accounts, account_contacts, account_health_logs, account_tasks, account_playbooks, account_signals, renewals, adoption_milestones.
KPIs: managed ARR, average health, renewals due, accounts at risk.
Signals: churn risk, adoption decline, executive silence, renewal opportunity.
Capabilities: prepare QBR, create success plan, draft outreach, update CRM, schedule meeting.
Approval boundary: customer-facing sends and contractual changes require approval.
Views: Dashboard, Accounts, Contacts, Renewals, Risk Matrix, Meetings, Projects, Tasks, Documents, Calendar.

4.2 Sales

Tables: leads, opportunities, deals, sales_activities, quotes, sales_sequences, sales_signals, forecast_snapshots.
KPIs: pipeline value, weighted forecast, win rate, stalled deals.
Signals: buying intent, stage stall, close-date slip, competitor mention, forecast risk.
Capabilities: qualify lead, update stage, draft follow-up, create quote, schedule call.
Approval boundary: discounts, pricing changes, legal commitments, and external sends follow policy.
Views: Dashboard, Pipeline, Deals, Leads, Activities, Sequences, Forecast, Quota, Accounts, Contacts.

4.3 Marketing

Tables: campaigns, campaign_members, content_assets, attribution_events, audience_segments, marketing_spend, marketing_signals, forms.
KPIs: sourced pipeline, influenced pipeline, campaign ROI, qualified leads.
Signals: channel anomaly, content gap, audience saturation, attribution conflict.
Capabilities: create campaign, publish content, adjust budget, generate brief, route lead.
Approval boundary: public publishing, spend changes, and regulated claims require approval.
Views: Dashboard, Campaigns, Leads, Email Studio, Social, Blog, Website, Forms, Attribution, Analytics.

4.4 Revenue Operations

Tables: pipelines, pipeline_stages, routing_rules, territories, quota_plans, forecast_models, revenue_metrics, revops_signals.
KPIs: coverage ratio, conversion by stage, forecast accuracy, routing SLA.
Signals: funnel leakage, routing failure, duplicate ownership, forecast variance, capacity risk.
Capabilities: modify routing rule, reconcile pipeline, assign territory, publish forecast, repair ownership.
Approval boundary: production routing, quota, compensation, and ownership model changes require elevated approval.
Views: Command Center, Pipeline Health, Routing, Territories, Forecast, Quotas, Data Quality, Analytics.

4.5 Finance

Tables: invoices, payments, budgets, expenses, subscriptions, vendors, cashflow_snapshots, finance_signals.
KPIs: cash balance, overdue receivables, burn, runway, budget variance.
Signals: late payment, cashflow risk, anomaly, duplicate invoice, renewal exposure.
Capabilities: approve expense, mark paid, generate invoice, reconcile payment, update forecast.
Approval boundary: payment release, voids, bank changes, budget overrides, and high-value expenses.
Views: Dashboard, Revenue, Expenses, Invoices, Invoice Approvals, Reports, Forecasting, Budget.

4.6 Operations / Business Ops

Tables: operating_plans, projects, milestones, dependencies, processes, workflows, operational_metrics, ops_signals.
KPIs: active initiatives, milestone health, blocked work, SLA attainment.
Signals: dependency risk, milestone slip, process failure, capacity bottleneck.
Capabilities: create project, assign owner, update milestone, trigger workflow, escalate blocker.
Approval boundary: cross-department priority changes and irreversible workflow actions.
Views: Dashboard, Command Center, Strategic Hub, Projects, Tasks, Calendar, Workflows, Metrics, Analytics.

4.7 Product & Engineering

Tables: products, roadmap_items, features, requirements, sprints, engineering_tasks, bugs, releases, repositories, deployments, engineering_signals.
KPIs: roadmap progress, sprint completion, escaped defects, deployment health.
Signals: release risk, regression, blocked dependency, incident recurrence, scope drift.
Capabilities: create issue, update roadmap, start release, request review, rollback deployment.
Approval boundary: production deployment, destructive repository actions, security-sensitive changes.
Views: Dashboard, Roadmap, Features, Bugs, Sprints, Releases, Feedback, Repositories, Deployments.

4.8 Support & Service

Tables: tickets, cases, sla_policies, sla_events, escalations, support_interactions, csat_responses, support_signals.
KPIs: open tickets, SLA risk, first-response time, CSAT, escalation count.
Signals: breach risk, customer frustration, repeated issue, deflection opportunity.
Capabilities: respond, resolve, escalate, create knowledge article, update priority.
Approval boundary: refunds, contractual concessions, sensitive disclosures, and bulk responses.
Views: Dashboard, Tickets, Customers, SLA, Escalations, CSAT, Knowledge, Queue.

4.9 IT & Security

Tables: systems, assets, licenses, certificates, vulnerabilities, incidents, access_requests, security_controls, it_signals.
KPIs: service availability, open incidents, critical vulnerabilities, expiring certificates.
Signals: outage, credential anomaly, certificate expiry, vulnerability exposure, license overage.
Capabilities: create incident, revoke session, rotate credential, patch asset, renew certificate.
Approval boundary: privileged access, key rotation, destructive remediation, production configuration.
Views: Dashboard, Systems, Incidents, Vulnerabilities, Certificates, Licenses, Access, Security.

4.10 HR & People Ops

Tables: employees, positions, teams, onboarding_plans, performance_cycles, leave_records, compensation_records, people_signals.
KPIs: headcount, open roles, onboarding completion, retention risk, leave load.
Signals: flight risk, onboarding blocker, review overdue, hiring milestone, policy exception.
Capabilities: start onboarding, approve leave, create review cycle, update position, initiate offboarding.
Approval boundary: compensation, termination, medical data, and sensitive employee actions.
Views: Dashboard, People, Org Chart, Hiring, Onboarding, Performance, Leave, Policies.

4.11 Legal & Compliance

Tables: contracts, contract_parties, obligations, legal_requests, policies, compliance_controls, evidence_requests, legal_signals.
KPIs: contracts awaiting review, obligations due, policy exceptions, control coverage.
Signals: renewal deadline, missing clause, compliance gap, data-processing risk, obligation breach.
Capabilities: request review, generate clause proposal, assign obligation, publish policy, open legal matter.
Approval boundary: signature, clause acceptance, regulatory representation, data-retention exceptions.
Views: Dashboard, Contracts, Matters, Obligations, Policies, Compliance, Evidence, Approvals.

4.12 Founder / Executive Ops

Tables: strategic_goals, company_metrics, executive_decisions, board_items, investor_updates, fundraising_pipeline, founder_projects, executive_signals.
KPIs: runway, revenue, pipeline, product delivery, customer risk, hiring plan.
Signals: cross-department blocker, strategic drift, runway risk, major account risk, release risk.
Capabilities: create decision, assign cross-functional action, approve exception, publish update, initiate review.
Approval boundary: Founder Ops can view across departments but writes remain subject to owning-domain policy.
Views: Founder Today, Company Pulse, Projects, Decisions, Customers, Revenue, Product, People, Risks, Knowledge.

5. Platform Projections

  • Integration Manager: connectors, connections, credentials, sync jobs, mappings, webhooks, integration signals.
  • Connector Marketplace: catalogue, listings, release state, installation, authorization, capabilities, documentation.
  • Activation Hub: onboarding sessions, role/department/industry selection, initial connectors, hydration progress, readiness.
  • Capability Manager: capability registry, policies, invocation history, compatibility, rollback.
  • MCP Pool: servers, tools, resources, operational/cognitive plane, health, scopes.
  • Knowledge: documents, chunks, articles, evidence, embeddings, publication workflow.
  • Memory & Continuity: intake, triage, promotion queue, user/work/org memory, continuity contexts.
  • Automation & Pipelines: workflows, triggers, runs, pipeline stages, retries, dead letters.
  • Governance: proposals, approvals, policies, exceptions, immutable provenance.
  • Observability: service health, traces, alerts, incidents, cost and latency.
  • Administration: organizations, users, roles, permissions, audit, billing, deployments, API keys, security.

6. Customer Zero Tenant Manifest

Customer Zero is not a separate schema. It is the first fully populated tenant using every shared domain and selected departmental extensions.

tenant:
  id: tnt_integratewise_customer_zero
  name: IntegrateWise LLP
  industry: b2b_saas_continuity_platform
  schema_version: tenant-spine-v1
  governance_posture: approval_first
  retention_days: 90

workspaces:
  - wsp_founder_ops
  - wsp_account_success
  - wsp_sales
  - wsp_marketing
  - wsp_revops
  - wsp_finance
  - wsp_operations
  - wsp_product_engineering
  - wsp_support
  - wsp_it_security
  - wsp_people_ops
  - wsp_legal
  - wsp_platform_ops

6.1 Seed Users and Roles

  • Nirmal Prince — Founder & CEO — Founder Ops, Platform Admin, Executive approvals.
  • Account Success Manager — accounts, renewals, QBRs, risk response.
  • Sales Lead — pipeline, opportunities, forecasts, outreach.
  • Marketing Lead — campaigns, content, attribution, leads.
  • Finance Manager — invoices, subscriptions, expenses, cashflow.
  • Product/Engineering Lead — roadmap, releases, defects, deployments.
  • Support Lead — queues, SLAs, escalations, knowledge.
  • Integration Manager — connector catalogue, sync health, mappings, MCP pool.
  • People Ops Manager — hiring, onboarding, performance, leave.
  • Legal/Compliance Owner — contracts, obligations, policies, evidence.

6.2 Seed Connections

  • GitHub organization and repositories.
  • Gmail or Microsoft 365 mail/calendar.
  • Slack or Microsoft Teams communications.
  • Coda and/or Notion knowledge sources.
  • Attio or current CRM source.
  • Cloudflare operational infrastructure.
  • Vercel/release frontend deployment source where applicable.
  • AI providers registered in the cognitive plane, not as operational truth connectors.

Each connection seeds connector capabilities, sync policy, health, cursors, source identifiers, and tenant ownership. Credentials remain vault-side.

6.3 Cross-Department Seed Entities

  • Company: IntegrateWise LLP.
  • Products/surfaces: IntegrateWise Workbench, IW-Spine-Network Plugin,
    IW-Spine-Network MCP and Connector Marketplace.
  • Projects: Public connector go-live, Work-Bench Spine wiring, Customer Zero activation, marketplace submission, infrastructure portability.
  • Customers/Prospects: Customer Zero plus realistic SaaS accounts and current founder-led opportunities.
  • Repositories: integratewise-live, work-bench, AI workspace and marketplace packages.
  • Connectors: the existing connector catalogue, with production/beta/preview/internal release states.
  • Documents: canonical architecture, marketplace package, onboarding specifications, deployment runbooks, security policies.
  • Decisions: provider choices, connector ownership doctrine, one-Spine projection rule, Twin/Triage boundaries.

6.4 Believable Operational Seed

  1. A connector token-expiry signal assigned to Integration Manager and visible in Founder Ops.
  2. A marketplace publication project with engineering tasks, legal review, marketing launch items, and executive milestones.
  3. A customer account with CRM opportunity, email thread, support risk, invoice, renewal, and QBR action linked to one canonical account.
  4. A production deployment with GitHub commit, deployment record, incident signal, approval, and remediation task.
  5. A document ingested into Knowledge, chunked and embedded, with a proposed Org Memory promotion awaiting approval.
  6. A Twin proposal backed by evidence, routed through Governance, approved by the user, executed through a capability, and written back to the timeline.

6.5 Minimum Seed Counts

  • 1 tenant and 13 workspaces.
  • 10 users, 12 roles, and role-permission mappings.
  • 12–20 connectors with mixed release/health states; existing full catalogue remains available.
  • 25 accounts/organizations, 60 contacts, 20 leads, 12 opportunities/deals.
  • 20 projects, 80 tasks/work items, 12 queues.
  • 40 communication threads, 30 calendar events, 15 meetings.
  • 50 documents/notes/knowledge records.
  • 30 signals, 12 proposals, 8 pending approvals.
  • 30 memory items across user, work, org, agent, development, and conversation scopes.
  • 10 deployments, 5 incidents, and 100 audit/timeline events.

7. Projection API Contract

GET /api/v1/workspaces/{workspaceId}/projection
GET /api/v1/projections/{department}/home
GET /api/v1/projections/{department}/entities
GET /api/v1/projections/{department}/signals
GET /api/v1/projections/{department}/work
GET /api/v1/projections/{department}/approvals
GET /api/v1/entities/{entityId}/360
POST /api/v1/work
POST /api/v1/proposals
POST /api/v1/approvals/{approvalId}/decision
POST /api/v1/capabilities/{capabilityKey}/invoke

Projection response envelope:

{
  "tenant": {},
  "workspace": {},
  "role": {},
  "continuity": { "score": 0, "lastSyncAt": null },
  "pulse": [],
  "records": [],
  "signals": [],
  "approvals": [],
  "capabilities": [],
  "twinContext": {},
  "provenance": []
}

8. Work-Bench Wiring Rule

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.

Required replacement seams:

  • useHydrateProjection(domain) → real Projection API query.
  • useSpine() → authenticated tenant/workspace metadata.
  • hard-coded navigation badges → work, communication, approval, and signal counts.
  • mock Twin responses → evidence-backed Twin/Triage endpoints.
  • local entity store → Entity 360 and governed mutation endpoints.

9. Implementation Sequence

  1. Convert this document into portable SQL migrations and typed contracts in integratewise-live.
  2. Add deterministic Customer Zero seed fixtures.
  3. Implement projection queries for Home, My Work, Communications, twelve departments, Platform, and Administration.
  4. Wire Work-Bench to those contracts.
  5. Validate one complete loop: connector event → pipeline → Spine → projection → proposal → approval → capability → source write-back → timeline/memory.
  6. Publish IW-Spine-Network Plugin, IW-Spine-Network MCP and provider connector
    surfaces only after this tenant loop is demonstrable.

10. Acceptance Criteria

  • The same canonical entity appears consistently across Sales, Account Success, Finance, Support, and Founder Ops.
  • Connected applications are tenant-owned and visible across all authorized surfaces without repeat OAuth.
  • Every departmental KPI is derived from stored fields or projection queries, never hard-coded UI values.
  • Every signal and AI proposal carries evidence, confidence, origin, and immutable provenance.
  • Every high-risk write passes Governance and appears on the audit/timeline history.
  • Work-Bench can switch departments without changing tenant truth or reconnecting infrastructure.