{"slug":"architecture/TENANT_LIFECYCLE_SCHEMA_REGISTER","title":"Tenant Lifecycle Schema Register","section":"architecture","sectionLabel":"Architecture","status":"current","type":"document","path":"architecture/TENANT_LIFECYCLE_SCHEMA_REGISTER.mdx","bytes":20275,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** current derived implementation register  \n**Date:** 2026-07-28  \n**Authority chain:** `ARCHITECTURE_LOCK.md` → `CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md` → `SPINE_ENTITY_TABLE_SCHEMA.md` → `TENANT_SPINE_FORTRESS_OPERATIONAL_FLOW_MODEL.md` → `APP_CATEGORY_ENTITY_DOMAIN_CLASSIFICATION.md` → `migrations/037_pure_entity_spine_tables.sql` + `migrations/038_tenant_lifecycle_entity_tables.sql` + `migrations/039_tenant_network_scope_and_promotion_flow.sql` + `migrations/040_scope_global_events_provenance_and_evidence.sql` + `migrations/041_app_category_entity_domain_classification.sql`\n\n## Purpose\n\nThis document corrects the modeling direction explicitly:\n\n```text\ntenant-level schema\n→ entity-based tables\n→ lifecycle/event-driven truth\n→ RBAC projections\n→ no department-based physical schema\n```\n\nDepartment, industry, and role can affect what a user sees, but they do not\nget their own storage schema families. The physical truth model is tenant\nscoped.\n\n## Non-negotiable storage rule\n\n- The platform uses one shared public schema.\n- `tenant_id` is the storage isolation boundary for tenant-owned truth.\n- `workspace_id` can narrow context, but it never replaces `tenant_id`.\n- Department is a projection/filter attribute only. It is not a partition key.\n- Every durable entity family belongs to its own table.\n- Views such as `home`, `inbox`, `accounts`, `renewals`, `roadmap`, `finance`,\n  and `governance` are projections over entity, work, event, memory, and\n  policy tables.\n- Human approval remains the promotion gate from operational memory and agent\n  memory into governed Fortress truth.\n\n## Canonical grouping keys\n\nFor tenant-owned durable rows, use the following grouping logic:\n\n| Concern                     | Canonical key                                                                         |\n| --------------------------- | ------------------------------------------------------------------------------------- |\n| Tenant boundary             | `tenant_id`                                                                           |\n| Tenant operating account    | `tenant_account_id`                                                                   |\n| Tenant Spine Network        | `spine_network_id`                                                                    |\n| Workspace context           | `workspace_id`                                                                        |\n| Durable identity            | `canonical_id`                                                                        |\n| Version lineage             | `version`                                                                             |\n| External connector binding  | `connector_binding_id`                                                                |\n| Provider connection lineage | `spine_connection_id`                                                                 |\n| User/actor responsibility   | `owner_user_id`, `assigned_user_id`, `submitted_by_user_id`, or equivalent role field |\n\nImportant clarification:\n\n```text\nUse spine_network_id as the canonical tenant network grouping key.\nUse spine_connection_id only as the lineage of one connector/provider connection.\nDo not create a separate department schema.\nDo not create per-department copies of the same business entity.\n```\n\n## Common entity envelope\n\nEvery tenant-scoped durable entity table should follow this shape:\n\n| Column class        | Required                                 | Meaning                                                                 |\n| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------- |\n| `tenant_id`         | yes                                      | storage and policy boundary                                             |\n| `tenant_account_id` | yes for new writes                       | the tenant root account; distinct from a customer/business `account_id` |\n| `spine_network_id`  | yes for new writes                       | the tenant's Spine Network grouping key                                 |\n| `app_category`      | yes through entity classification        | connector/source category that originated the entity                    |\n| `business_domain`   | yes through entity classification        | RBAC classification; never a department table family                    |\n| `lifecycle_stage`   | yes through entity classification        | cross-domain signal, playbook and projection routing key                |\n| `workspace_id`      | recommended                              | active workspace scope                                                  |\n| `<entity>_id`       | yes                                      | opaque stable row identity                                              |\n| `canonical_id`      | yes                                      | dedupe/merge/projection identity                                        |\n| `version`           | yes                                      | mutable truth lineage                                                   |\n| `status`            | yes                                      | current operating state                                                 |\n| `lifecycle_stage`   | recommended                              | the current lifecycle step for that entity family                       |\n| ownership fields    | recommended                              | user/person responsible for the record                                  |\n| connector lineage   | optional but preferred for imported rows | `connector_binding_id`, `spine_connection_id`                           |\n| provenance          | yes                                      | `source_class`, `confidence`, `provenance_jsonb`                        |\n| metadata            | yes                                      | `metadata_jsonb` for additive attributes                                |\n| timestamps          | yes                                      | `created_at`, `updated_at` and entity-specific dates                    |\n\n## Tenant lifecycle stages\n\n### 1. Identity and membership\n\nThis stage establishes who the tenant is, which users belong to it, and what\nauthority they have.\n\nPrimary tables:\n\n- `spine_organizations`\n- `spine_users`\n- `spine_memberships`\n- `spine_user_roles`\n- `spine_role_permissions`\n- `spine_policies`\n\nPrimary surfaces:\n\n- onboarding\n- organizations\n- users\n- roles\n- permissions\n- security\n- profile\n\nLifecycle events:\n\n- `tenant.created`\n- `workspace.created`\n- `membership.granted`\n- `membership.revoked`\n- `role.assigned`\n- `permission.changed`\n\n### 2. Activation and connector consent\n\nThis stage binds the tenant to approved external systems.\n\nPrimary tables:\n\n- `spine_connector_catalog`\n- `spine_connectors`\n- `spine_activation_runs`\n- `spine_mcp_routes`\n- `spine_model_registry`\n- approved connector-binding runtime records (`connector_binding_id`, `spine_connection_id`)\n\nPrimary surfaces:\n\n- connector-marketplace\n- integration-manager\n- activation-hub\n- data-sources\n- integrations\n- capabilities\n- platform-health\n\nLifecycle events:\n\n- `connector.selected`\n- `connector.authorized`\n- `connector.binding.validated`\n- `schema.discovered`\n- `activation.started`\n- `activation.completed`\n\n### 3. External intake and communication\n\nThis stage captures inbound activity before it becomes work, knowledge, or\nmemory.\n\nPrimary tables:\n\n- `spine_events`\n- `spine_messages`\n- `spine_calendar_events`\n- `spine_meetings`\n- `spine_calls`\n- `spine_documents`\n- `spine_document_chunks`\n- `spine_source_links`\n- `spine_evidence`\n\nPrimary surfaces:\n\n- activity-feed\n- email\n- calendar\n- meetings\n- calls\n- documents-shared\n\nLifecycle events:\n\n- `message.ingested`\n- `meeting.recorded`\n- `call.completed`\n- `document.ingested`\n- `artifact.linked`\n\n### 4. Triage, continuity, and organizational memory\n\nThis stage turns raw activity into governed context.\n\nPrimary tables:\n\n- `spine_timeline_events`\n- `spine_signals`\n- `spine_memory_items`\n- `spine_memory_promotions`\n- `spine_agent_context_windows`\n- `spine_agent_memory`\n- `spine_continuity_runs`\n- `spine_continuity_checks`\n- `brainstorm_sessions`\n- `brainstorm_messages`\n- `brainstorm_ideas`\n- `brainstorm_canvas_states`\n- `brainstorm_decisions`\n- `brainstorm_insights`\n- `spine_knowledge_items`\n- `spine_canvas_documents`\n\nPrimary surfaces:\n\n- triage / chat hub\n- brainstorming\n- notes\n- knowledge\n- knowledge-base\n- memory-continuity\n- organizational memory / company wiki projection\n\nLifecycle events:\n\n- `signal.detected`\n- `memory.candidate.created`\n- `memory.promotion.requested`\n- `memory.promoted`\n- `brainstorm.session.started`\n- `knowledge.promoted`\n\n### 5. Operational work and execution\n\nThis is the main user-facing SSOT of day-to-day work.\n\nPrimary tables:\n\n- `spine_work_items`\n- `spine_commitments`\n- `spine_work_queues`\n- `spine_tasks`\n- `spine_projects`\n- `spine_objectives`\n- `spine_outcomes`\n- `spine_approvals`\n- `spine_decisions`\n- `spine_favorites`\n- `spine_projection_views`\n\nPrimary surfaces:\n\n- home\n- inbox\n- tasks\n- my-queue\n- approvals\n- notifications\n- recent-work\n- favorites\n- projects\n- task-manager\n\nLifecycle events:\n\n- `work.created`\n- `work.assigned`\n- `work.blocked`\n- `approval.requested`\n- `approval.granted`\n- `outcome.verified`\n\n### 6. Commercial and customer lifecycle\n\nThis stage holds customer, pipeline, revenue, billing, and renewal truth.\n\nPrimary tables:\n\n- `spine_accounts`\n- `spine_leads`\n- `spine_opportunities`\n- `spine_subscriptions`\n- `spine_invoices`\n- `spine_renewals`\n- `spine_contracts`\n- `spine_budgets`\n- `spine_expenses`\n- `spine_billing_ledger`\n\nPrimary surfaces:\n\n- accounts\n- account-master\n- account-health\n- at-risk\n- contacts\n- renewals\n- pipeline\n- deals\n- forecast\n- quota\n- revenue\n- invoices\n- invoice-approvals\n- reports\n- forecasting\n- budget\n- finance-manager\n\nLifecycle events:\n\n- `lead.captured`\n- `opportunity.opened`\n- `opportunity.won`\n- `invoice.issued`\n- `invoice.paid`\n- `renewal.risk.detected`\n- `renewal.completed`\n\n### 7. Product, delivery, and operating systems lifecycle\n\nThis stage covers product engineering, service delivery, operations, and\nsystems.\n\nPrimary tables:\n\n- `spine_processes`\n- `spine_workflows`\n- `spine_tickets`\n- `spine_incidents`\n- `spine_products`\n- `spine_features`\n- `spine_releases`\n- `spine_sprints`\n- `spine_assets`\n- `spine_meetings`\n\nPrimary surfaces:\n\n- roadmap\n- features\n- bugs\n- sprints\n- releases\n- incidents\n- feedback\n- architecture\n- data-flow\n- systems\n- vulnerabilities\n- certificates\n- licenses\n- tickets\n- sla\n- sessions\n\nLifecycle events:\n\n- `workflow.started`\n- `ticket.opened`\n- `incident.detected`\n- `feature.prioritized`\n- `release.shipped`\n- `sprint.closed`\n\n### 8. Vendor, procurement, and partner lifecycle\n\nThis stage models external spend and supply-side relationships.\n\nPrimary tables:\n\n- `spine_vendors`\n- `spine_orders`\n- `spine_contracts`\n- `spine_expenses`\n- `spine_accounts` (for partners/clients where needed)\n\nPrimary surfaces:\n\n- vendors\n- orders\n- contracts\n- spend\n- savings\n- spend-insights\n- partnerships\n\nLifecycle events:\n\n- `vendor.added`\n- `order.placed`\n- `contract.renewal_due`\n- `expense.submitted`\n- `expense.approved`\n\n### 9. Governance, security, billing, and observability\n\nThis stage is the tenant’s hard control plane.\n\nPrimary tables:\n\n- `spine_policies`\n- `spine_audit_log`\n- `spine_security_events`\n- `spine_capabilities`\n- `spine_capability_executions`\n- `spine_pipeline_runs`\n- `spine_observability_signals`\n- `spine_deployments`\n- `spine_api_keys`\n\nPrimary surfaces:\n\n- governance\n- observability\n- audit\n- billing\n- deployments\n- api-keys\n- security\n- pipelines\n- automation\n- ai-models\n- mcp-pool\n\nLifecycle events:\n\n- `policy.evaluated`\n- `execution.authorized`\n- `execution.failed`\n- `pipeline.completed`\n- `security.signal.raised`\n- `deployment.promoted`\n\n## Entity families required by the current view inventory\n\nThe current UI inventory implies the following tenant-level entity families.\n\n### Already present in the typed Spine\n\n| Entity family                                      | Table                 |\n| -------------------------------------------------- | --------------------- |\n| Person / stakeholder / employee / contact identity | `spine_persons`       |\n| Team                                               | `spine_teams`         |\n| Process                                            | `spine_processes`     |\n| Project / initiative                               | `spine_projects`      |\n| Objective / OKR                                    | `spine_objectives`    |\n| Outcome                                            | `spine_outcomes`      |\n| Asset / system / file                              | `spine_assets`        |\n| Signal / insight / risk                            | `spine_signals`       |\n| Conversation                                       | `spine_conversations` |\n| Activity                                           | `spine_activities`    |\n| Timeline container                                 | `spine_timelines`     |\n| Task                                               | `spine_tasks`         |\n| Meeting                                            | `spine_meetings`      |\n\n### Added for tenant lifecycle completeness\n\n| Entity family                                | Table                 |\n| -------------------------------------------- | --------------------- |\n| Account / client / customer / company record | `spine_accounts`      |\n| Lead                                         | `spine_leads`         |\n| Opportunity / deal                           | `spine_opportunities` |\n| Campaign                                     | `spine_campaigns`     |\n| Workflow / automation definition             | `spine_workflows`     |\n| Ticket / case                                | `spine_tickets`       |\n| Incident                                     | `spine_incidents`     |\n| Subscription                                 | `spine_subscriptions` |\n| Invoice                                      | `spine_invoices`      |\n| Renewal                                      | `spine_renewals`      |\n| Vendor                                       | `spine_vendors`       |\n| Contract                                     | `spine_contracts`     |\n| Order / purchase                             | `spine_orders`        |\n| Product / SKU / offering                     | `spine_products`      |\n| Feature                                      | `spine_features`      |\n| Release                                      | `spine_releases`      |\n| Sprint                                       | `spine_sprints`       |\n| Budget                                       | `spine_budgets`       |\n| Expense                                      | `spine_expenses`      |\n\n## Projection rule\n\nThe frontend does not own truth tables for each sidebar item. It renders RBAC\nand context scoped projections over these families.\n\nProjection inputs:\n\n- tenant identity and membership\n- allowed entity families\n- current work items and approvals\n- related messages, meetings, docs, and evidence\n- continuity and memory\n- allowed capabilities\n- current governance posture\n\nProjection outputs:\n\n- tables\n- record pages\n- editable canvases\n- timelines\n- Twin-ready contextual payloads\n\nThe product runtime contract is still projection-first:\n\n```text\nGateway event / query\n→ tenant + RBAC resolution\n→ projection composition\n→ frontend workbench state\n→ user action\n→ governed command\n→ backend write / execution\n→ projection invalidation and rehydrate\n```\n\n## Promotion boundary\n\nDraft operational-memory and agent-memory records can originate in the Product\nsurface, but persistent truth promotion still follows:\n\n```text\nWorkbench draft / agent output\n→ Triage classification\n→ human review / approval\n→ governed Spine write\n→ projection rehydrate\n```\n\nThis preserves the rule that AI proposes and humans approve.\n\n## Source reconciliation notes\n\nWhile reviewing the imported view inventory, two inconsistencies matter:\n\n1. `domain-route-manifest.ts` includes `cs-accounts-hub`, while\n   `domain-view-registry.tsx` currently exposes `csm-accounts-hub`.\n2. global navigation uses `triage`, while the backend surface map still uses\n   `chat` for the brainstorming/triage surface family.\n\nThese are naming inconsistencies, not reasons to create new tables. The schema\nshould stay semantic and tenant-level.\n\n## Appendix A — current view inventory grouped into tenant lifecycle meaning\n\n### Global tenant surfaces\n\n- Identity / control:\n  `home`, `organizations`, `users`, `roles`, `permissions`, `security`,\n  `audit`, `billing`, `deployments`, `api-keys`\n- Work:\n  `inbox`, `tasks`, `my-queue`, `approvals`, `notifications`,\n  `recent-work`, `favorites`\n- Communications:\n  `activity-feed`, `email`, `calendar`, `meetings`, `triage`, `calls`,\n  `documents-shared`\n- Personal / memory:\n  `notes`, `drafts`, `brainstorming`, `my-files`\n- Platform:\n  `integration-manager`, `connector-marketplace`, `activation-hub`,\n  `capability-manager`, `mcp-pool`, `ai-models`, `knowledge`,\n  `memory-continuity`, `automation`, `pipelines`, `governance`,\n  `observability`\n\n### Account-success views\n\nCommercial + customer success lifecycle:\n\n- `dashboard`\n- `cs-today`\n- `cs-accounts-hub` / `csm-accounts-hub`\n- `cs-account-detail`\n- `cs-contacts`\n- `cs-meetings`\n- `intelligence-center`\n- `accounts`\n- `account-master`\n- `account-health`\n- `at-risk`\n- `contacts`\n- `account-team`\n- `people-team`\n- `renewals`\n- `success-plans`\n- `risk-matrix`\n- `risk-register`\n- `engagement-log`\n- `meetings`\n- `initiatives`\n- `strategic-objectives`\n- `stakeholder-outcomes`\n- `business-context`\n- `projects`\n- `tasks`\n- `task-manager`\n- `documents`\n- `capabilities`\n- `platform-health`\n- `value-streams`\n- `insights`\n- `company-growth`\n- `strategic-account-success`\n- `calendar`\n\n### BizOps views\n\nCross-tenant command, planning, operations, and integration lifecycle:\n\n- `dashboard`\n- `bizops-today`\n- `command-center`\n- `operations-center`\n- `strategic-hub`\n- `strategy-leadership`\n- `sales-hub`\n- `founder-ops`\n- `ceo`\n- `coo`\n- `cio-cto`\n- `business-intelligence`\n- `human-resources`\n- `legal-compliance`\n- `knowledge-management`\n- `partnerships`\n- `crm`\n- `accounts`\n- `clients`\n- `tasks`\n- `calendar`\n- `documents`\n- `workflows`\n- `integrations`\n- `metrics`\n- `analytics`\n- `governance`\n- `cockpit`\n- `data-sources`\n- `iq-hub`\n\n### Finance views\n\n- `dashboard`\n- `revenue`\n- `expenses`\n- `invoices`\n- `invoice-approvals`\n- `reports`\n- `forecasting`\n- `budget`\n\n### IT admin views\n\n- `dashboard`\n- `systems`\n- `incidents`\n- `vulnerabilities`\n- `certificates`\n- `licenses`\n- `admin`\n- `settings`\n- `data-flow`\n\n### Marketing views\n\n- `dashboard`\n- `campaigns`\n- `leads`\n- `email`\n- `social`\n- `blog`\n- `website`\n- `forms`\n- `attribution`\n- `analytics`\n- `content`\n\n### Personal views\n\n- `dashboard`\n- `home`\n- `today`\n- `founder-today`\n- `founder-projects`\n- `founder-decisions`\n- `knowledge`\n- `bookmarks`\n- `focus`\n- `wealth`\n- `wellness`\n- `learning`\n- `relationships`\n- `whats-new`\n- `brainstorming`\n- `profile`\n- `insights`\n\n### Procurement views\n\n- `dashboard`\n- `vendors`\n- `orders`\n- `contracts`\n- `renewals`\n- `spend`\n- `savings`\n- `spend-insights`\n\n### Product-engineering views\n\n- `dashboard`\n- `roadmap`\n- `features`\n- `bugs`\n- `sprints`\n- `tasks`\n- `releases`\n- `incidents`\n- `feedback`\n- `analytics`\n- `architecture`\n- `data-flow`\n- `projects`\n\n### RevOps views\n\n- `dashboard`\n- `pipeline`\n- `forecast`\n- `quota`\n- `cohorts`\n- `team`\n- `metrics`\n- `analytics`\n- `pending-review`\n- `decision-log`\n\n### SalesOps views\n\n- `dashboard`\n- `pipeline`\n- `deals`\n- `contacts`\n- `activities`\n- `sequences`\n- `analytics`\n- `sales-hub`\n- `clients`\n- `client-detail`\n\n### Service views\n\n- `dashboard`\n- `tickets`\n- `customers`\n- `knowledge`\n- `csat`\n- `sla`\n- `analytics`\n- `sessions`\n\n### Student-teacher views\n\n- `dashboard`\n- `students`\n- `courses`\n- `assignments`\n- `gradebook`\n- `at-risk`\n\n## Bottom line\n\nThe schema root is not department.\n\nThe schema root is:\n\n```text\ntenant\n→ entity family\n→ lifecycle state\n→ event history\n→ governed projection\n```\n"}