{"slug":"architecture/spineworkspace","title":"SpineWorkspace Architecture","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/spineworkspace.mdx","bytes":24132,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## 1. Rooted access-and-projection tree\n\n### Core mental model\n\n- SpineWorkspace is a **rooted access-and-projection tree**.\n- **Root:** OneAuth (`auth.spineworkspace.com`) is the single root of trust and access control.\n- **Branches:** Hostnames/subdomains (`www`, `platform`, `sales`, `cs`, etc.) are projection targets, not separate apps.\n- **Leaves:** Concrete workspace projections rendered by a shared `apps/web` execution shell.\n\n### OneAuth as root\n\n- OneAuth is the **authentication and authorization root**.\n- It resolves, for every session:\n  - Identity\n  - Tenant\n  - Workspace\n  - Roles\n  - Entitlements\n  - Policies\n- No other surface (marketing, platform, domain workspace) is allowed to mint or validate auth; all authenticated paths traverse OneAuth first.\n- OneAuth also acts as the **navigation root**: it decides _whether_ a user may enter a projection, and _how_ they should be routed there.\n\n### Edges (subdomains) as projections\n\n- Each subdomain is a **projection selector**, not a state owner:\n  - It indicates _which_ workspace shape should load.\n  - It never owns credentials, connector state, or business truth; those live in Spine, connectors, memory, and platform services.\n- Adding a new subdomain means adding a **new projection configuration** (host → projection key → Twin + capabilities), not a new app.\n\n### Edge types\n\n- **Public edge:** `www.spineworkspace.com`\n  - Unauthenticated marketing and docs.\n  - Owns the story, SEO, solution catalog, and routes into OneAuth when a user chooses to sign in/sign up.\n\n- **Identity edge:** `auth.spineworkspace.com`\n  - Only surface for login, SSO, delegated host auth, and session lifecycle.\n  - Converts an anonymous visitor into an entitled workspace user.\n\n- **Control-plane edge:** `platform.spineworkspace.com`\n  - Control plane UI for operating Spine itself: integrations, activation, capabilities, governance, agent fleet, observability, portfolio, administration.\n  - Only reachable for platform‑scoped roles, always downstream of OneAuth. This mirrors modern SaaS “control plane UI over data planes” patterns.[1]\n\n- **Domain workspace edges:**\n  - `founder.spineworkspace.com`\n  - `sales.spineworkspace.com`\n  - `cs.spineworkspace.com`\n  - `marketing.spineworkspace.com`\n  - `finance.spineworkspace.com`\n  - `operations.spineworkspace.com` / `ops.spineworkspace.com`\n  - `product.spineworkspace.com`\n  - `engineering.spineworkspace.com`\n  - `account-success.spineworkspace.com`\n  - `technical-account-success.spineworkspace.com`\n  - `business-intelligence.spineworkspace.com`\n  - `campaigns.spineworkspace.com`\n  - `knowledge-management.spineworkspace.com`\n  - `revops.spineworkspace.com`\n  - `support.spineworkspace.com`\n  - `brandstore.spineworkspace.com`\n  - `book-of-records.spineworkspace.com`\n  - `…` future domains\n- All of these are **the same `apps/web` shell**; the host only changes:\n  - The projection key (which views/entities/canvases to load)\n  - The domain Twin configuration\n  - The default entry views and domain‑specific affordances\n\n### Traversal rules\n\n- If a user hits a **domain or platform edge** without a valid session:\n  - Redirect to `auth.spineworkspace.com` with the original target encoded.\n- After successful authentication:\n  - OneAuth resolves tenant, workspace, roles, entitlements, policies.\n  - If user is _entitled_ to that projection:\n    - Route back to the target host, load `apps/web`, inject projection key + role context.\n  - If user is _not entitled_:\n    - Route to the nearest allowed projection (e.g., default Home) or to an access/upgrade path, according to governance and plans.\n\n> **Canonical rule:** OneAuth determines _who_ may enter; the subdomain determines _which workspace projection_ loads; `apps/web` renders the shell; Spine, connectors, and agents supply the live work inside it.\n\n---\n\n## 2. Domain and subdomain map\n\n### Root domain & public front-door\n\n- `spineworkspace.com` / `www.spineworkspace.com` — `apps/marketing`\n  - **Root public front-door of the product ecosystem.**\n  - All public traffic enters through `apps/marketing` (`www.spineworkspace.com`), exposing product narrative, platform capabilities, and the `/solutions/*` catalog.\n  - Acts as the primary discovery & funnel engine, routing users into OneAuth (`auth.spineworkspace.com`) and domain workbenches (`*.spineworkspace.com`).\n\n### Key subdomains\n\n- `www.spineworkspace.com` — public marketing (`apps/marketing`, canonical root)\n- `auth.spineworkspace.com` — OneAuth (identity, SSO, sessions)\n- `platform.spineworkspace.com` — platform control plane (`apps/platform`)\n\n- Domain workspaces (all powered by `apps/web`):\n  - `founder.spineworkspace.com`\n  - `sales.spineworkspace.com`\n  - `marketing.spineworkspace.com`\n  - `finance.spineworkspace.com`\n  - `ops.spineworkspace.com`\n  - `engineering.spineworkspace.com`\n  - `account-success.spineworkspace.com`\n  - `technical-account-success.spineworkspace.com`\n  - `business-intelligence.spineworkspace.com`\n  - `campaigns.spineworkspace.com`\n  - `knowledge-management.spineworkspace.com`\n  - `support.spineworkspace.com`\n  - `brandstore.spineworkspace.com` (internal)\n  - `book-of-records.spineworkspace.com` (internal)\n  - Future domain workspaces…\n\nEach domain subdomain corresponds to a **real domain workspace configuration** in `apps/web` (projection + Twin + capabilities + starter connectors).\n\n---\n\n## 3. Common Workbench sidebar (IW grammar)\n\nAll domain workspaces share a **common sidebar grammar** in `apps/web`. Only the **Work** section is projection‑aware; everything else is shared:\n\n### Home — my operational context\n\n- Personal operational dashboard, cross‑domain aggregation.\n- Workspace awareness, recent activity, priority ranking, personal KPIs.\n- Pending approvals, AI recommendations, quick actions, workspace continuity.\n- Personal Twin context and cross‑projection navigation.\n\n### My Work — personal execution surface\n\n- Assigned work, delegated work.\n- Waiting on others / waiting for me.\n- Tasks, goals, deliverables, follow‑ups.\n- Approvals and SLA commitments.\n- Calendar‑linked work and Twin‑assisted execution.\n\n### Inbox — unified operational inbox\n\n- Aggregated from:\n  - Email, chat, CRM, tickets, comments, mentions.\n  - Notifications, AI‑generated follow‑ups, connector events, workflow events, approval requests.\n- With:\n  - Priority scoring, deduplication, threading.\n  - AI summaries and suggested actions.\n\n### Tasks — universal task execution\n\n- Manual tasks, workflow tasks.\n- Agent‑generated and connector‑generated tasks.\n- Scheduled and recurring tasks.\n- Approvals, dependencies, SLA tracking.\n- Context‑aware execution surface.\n\n### My Queue — dynamic execution queue\n\n- Generated by:\n  - Priority engine, OODA loop, signals.\n  - Deadlines, dependencies, AI prioritization.\n  - Role, current context, business impact, attention management.\n\n### Approvals — human-in-the-loop governance\n\n- Publishing, budget, connector and AI approvals.\n- Write‑back, customer, deployment, security, and policy approvals.\n- Escalation workflows and full audit trail.\n\n### Notifications — workspace event stream\n\n- Events from:\n  - Connectors, pipelines, agents, skills, workflows.\n  - Governance, security, platform, workspace, Twin, human collaboration.\n- Intelligently grouped and prioritized.\n\n### Recent Work — continuity surface\n\n- Recently viewed entities, edited records.\n- Recent conversations, workflows, approvals.\n- Recent Twin sessions, canvas work, documents, context.\n- “Resume previous work” entry point.\n\n### Favorites — pinned operational assets\n\n- Views and dashboards.\n- Accounts, campaigns, customers, reports.\n- Skills, agents, workflows.\n- Documents, canvases, pipelines.\n\n### Communications cluster\n\n- **Activity Feed** — unified operational timeline:\n  - CRM activity, emails, meetings, chats, deployments.\n  - Customer interactions, agent activity, workflow execution, connector and platform events.\n- **Email** — multi‑provider email workspace:\n  - Unified inbox, AI summaries, draft generation, smart replies.\n  - CRM/entity linking, Twin memory, knowledge retrieval, workflow initiation.\n- **Calendar** — unified scheduling:\n  - Multi‑provider calendars, availability, AI scheduling.\n  - Meeting prep, agenda and follow‑up generation, linked entities and workflows.\n- **Meetings** — meeting operating system:\n  - Preparation, briefing, live assistance.\n  - Recording, transcript, actions, decisions, follow‑ups, memory promotion.\n- **Chat** — unified conversation layer:\n  - Slack, Teams, Discord, internal chat, MCP messaging, AI conversations.\n  - Context retrieval, entity linking, workspace memory, suggested actions.\n- **Calls** — voice workspace:\n  - Call prep, live notes, transcript.\n  - CRM linking, entity extraction, tasks, decisions, follow‑ups, memory updates.\n- **Documents Shared** — collaborative document workspace:\n  - Google Docs, Office, Notion, Coda, PDFs, internal docs.\n  - Semantic indexing, context retrieval, version awareness, AI understanding, knowledge promotion.\n\n### Personal cluster\n\n- **Notes** — personal operational memory:\n  - Quick capture, linked entities, AI organization, tags.\n  - Knowledge promotion, Twin context, search, continuity.\n- **Knowledge Base** — workspace knowledge graph:\n  - Canonical knowledge, policies, procedures, docs.\n  - Product, customer, and organizational knowledge.\n  - Semantic search, RAG context, source traceability.\n- **Brainstorming Sessions** — collaborative ideation:\n  - Whiteboards, structured thinking, AI ideation, Twin collaboration.\n  - Decision capture, research, concept evolution, memory promotion.\n- **Activity** — personal operational timeline:\n  - Work history, AI activity, decisions, context switches.\n  - Workflow participation, learning, memory evolution, workspace interactions.\n\n### Work — projection-aware domain workspace\n\n- Routed based on:\n  - Role, department, industry, workspace policy.\n- Built from:\n  - Spine projections, views, canvas, tool capabilities.\n  - Twin execution via OODA, skills, agents, workflows.\n  - Pipelines, frontend–backend mappings, operational DBs, context gathering, Entity360, continuity memory.\n- Each domain projection contains enough operational depth for someone to do their **entire job** in that domain in the agentic era.\n\n### Platform & Administration entries in sidebar\n\n- **Platform** — shared capability layer (mirrors `apps/platform` screens):\n  - Integration Manager, Connector Marketplace, Activation Hub, Capability Manager, MCP Pool, AI Models, Knowledge, Memory & Continuity, Automation, Pipelines, Governance, Observability.\n- **Administration** — workspace and platform governance:\n  - Organizations, workspaces, users, roles, permissions, security, billing, licensing, API access, deployments, feature access, compliance, audit, tenant policies, identity, subscription management.\n  - Permission‑aware: users only see admin functions they are allowed to manage.\n\n---\n\n## 4. `apps/platform`: control plane UI\n\n### Role of `apps/platform`\n\n- `apps/platform` is the **control plane UI** for Spine.\n- Every screen in `apps/platform` is a **window onto one or more platform services and agents**, never a separate product silo.\n- It exposes the control plane for agents + tools + data, analogous to modern AI/MCP gateways and observability control planes.[2][1]\n\n### Top-level responsibilities\n\n- Operate Spine across tenants and domains:\n  - Integrations & connectors.\n  - Capability and MCP tool registry.\n  - Activation & readiness.\n  - Agent & Twin fleet.\n  - Knowledge, memory, pipelines, automation.\n  - Governance and observability.\n  - Portfolio and administration.\n\n### Screen → services → agents → packages matrix\n\n| Screen                         | Primary services                                                                                        | Agents / Twins                                                                                                       | Key packages / APIs                                                                                                 |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\n| Integration Manager            | Integration Manager, Connector Marketplace, Capability Manager, Observability (connector)               | Discovery Agent, Schema Agent, Adaptive Autotuner, Hermes                                                            | `connector-contracts`, `capability-registry`, `spine-schema`, `spine-entities`                                      |\n| Connector Marketplace          | Connector Marketplace, Integration Manager, Billing/Usage                                               | Discovery Agent, Policy Enforcer                                                                                     | `connector-contracts`, marketplace UI config, `governance-core`                                                     |\n| Activation Hub                 | Activation Service, Pipeline Orchestrator, Spine Graph Service, OneAccess, Workbench Config, Governance | Discovery Agent, Schema Agent, Twin Manager, Policy Enforcer, Adaptive Autotuner                                     | `spine-entities`, `spine-projections`, `workbench-config`, `agent-runtime`, `governance-core`, `observability-core` |\n| Capability Manager             | Capability Manager, OneAccess, Integration Manager, MCP Gateway / MCP Pool                              | Hermes, Governed Co‑Worker                                                                                           | `capability-registry`, `one-access-core`, `mcp-gateway`, `connector-contracts`                                      |\n| MCP Pool / Tool Registry       | MCP Gateway / MCP Pool, Capability Manager, Observability, Governance                                   | Hermes, Research Subagent, Policy Enforcer                                                                           | `mcp-gateway`, `capability-registry`, `governance-core`, `observability-core`                                       |\n| Agent Fleet / Runtime Manager  | Agent Runtime Service, Twin Manager, Queue/Job Service, Observability                                   | Triage Bot, Silent Twin, Hermes, Governed Co‑Worker, Discovery Agent, Schema Agent, Adaptive Autotuner, domain Twins | `agent-runtime`, domain Twin packages, `observability-core`                                                         |\n| Knowledge, Memory & Continuity | Knowledge Service, Memory & Continuity Service, Spine Graph Service                                     | Silent Twin, all domain Twins, Insight Synthesizer                                                                   | `spine-schema`, `spine-entities`, `knowledge-memory` / memory SDK                                                   |\n| Pipelines & Automation         | Pipeline Orchestrator, Automation Service, Observability, Integration Manager                           | Discovery Agent, Schema Agent, Adaptive Autotuner                                                                    | pipeline orchestration package, `spine-schema`, `spine-entities`, `observability-core`                              |\n| Governance                     | Governance Service, Admin Service, Observability, Capability Manager                                    | Policy Enforcer, Governed Co‑Worker, Twins (annotated proposals)                                                     | `governance-core`, Admin SDK, `observability-core`                                                                  |\n| Observability                  | Observability Service, Metric Service, Log/Trace ingestion, Cost/Usage Service                          | Adaptive Autotuner, Policy Enforcer (signal-driven triggers)                                                         | `observability-core`, metrics/logging libraries, dashboard configs                                                  |\n| Portfolio                      | Portfolio Service, Spine Graph Service (multi-workspace), Metric/Cohort Service, OneAccess              | Founder‑Twin, BI‑Twin, Ops/RevOps Twins                                                                              | `spine-projections` (portfolio module), `spine-entities`                                                            |\n| Administration (Tenants, etc.) | Admin Service, OneAccess, Billing & Usage                                                               | Policy Enforcer (role/governance alignment)                                                                          | `one-access-core`, Admin SDK, Billing SDK                                                                           |\n\n---\n\n## 5. `apps/marketing`: solutions-by-domain catalog\n\n### Role of `apps/marketing`\n\n- `apps/marketing` (served at `www.spineworkspace.com`) is **one public Next.js App Router application** rooted at `apps/marketing/app`.\n- The **Solutions** section is organized by domain (Sales, CS, Founder, Engineering, Finance, Ops, etc.) namespaced explicitly under `/solutions/*`.\n- Each solution page is a “pre‑onboard mini domain landing” that:\n  - Explains that domain’s workspace and Twin.\n  - Shows real Workbench screenshots and flows.\n  - Offers **domain‑scoped signup/sign‑in** that lands the user in the correct domain subdomain in `apps/web` via OneAuth.\n\n### Public URL contract & URL-stability invariant\n\nTop-level product/company routes and `/solutions/*` namespace routes are distinct canonical URLs and must remain stable:\n\n> **The Marketing application is a public Next.js App Router application rooted at `apps/marketing/app`. Top-level route folders represent canonical public URLs, while solution landing pages remain explicitly namespaced under `/solutions/*`. Internal code organization may change, but public URLs must remain stable unless the same change includes explicit redirects, sitemap updates, canonical metadata updates, and link rewrites.**\n\n- Top-level public routes: `/`, `/about`, `/product`, `/platform`, `/spine`, `/spine-workspace`, `/services`, `/integrations`, `/pricing`, `/resources`, `/security`, `/why`\n- Solution routes: `/solutions`, `/solutions/customer-success`, `/solutions/finance`, `/solutions/finance-leaders`, `/solutions/founders`, `/solutions/manufacturing`, `/solutions/operations`, `/solutions/professional-services`, `/solutions/retail`, `/solutions/revops`, `/solutions/saas`, `/solutions/services`\n\nNote: `/services` (top-level product/service narrative) ≠ `/solutions/services` (solution for services companies). Do not flatten `/solutions/*` to top-level routes.\n\n### Public Marketing versus Authenticated Workbenches\n\n```text\nPUBLIC MARKETING: www.spineworkspace.com/solutions/finance\nAUTHENTICATED WORKBENCH: finance.spineworkspace.com\n```\n\nAnonymous visitors to domain subdomains (e.g., `finance.spineworkspace.com`) may be redirected via 302/307 to `www.spineworkspace.com/solutions/finance`, while authenticated users route to `apps/web` with the domain projection.\n\n### CTA and auth flow\n\nFor each domain solution page:\n\n1. **CTA click** (e.g., “Start with Sales Workspace”) → `auth.spineworkspace.com` with `?domain=sales` (plus campaign params).\n2. OneAuth:\n   - Authenticates user.\n   - Resolves tenant, workspace, roles, entitlements.\n3. Activation:\n   - If new workspace, uses `domain` hint to enable the domain projection, suggest connectors, and set first landing to that domain subdomain.\n4. Post‑auth redirect:\n   - If user is entitled to that domain: route to `sales.spineworkspace.com` (or relevant subdomain) and load `apps/web` with the appropriate projection key.\n   - If not, present a lightweight “enable [Domain] Workspace” mini‑activation instead of an error.\n\n### Content & SEO patterns\n\n- Each `/solutions/:domain` page:\n  - Is optimized around a clear category keyword (“sales workspace”, “customer success workspace”, etc.).\n  - Shows real UI and flows instead of abstract AI marketing.\n  - Aligns with search intent by focusing on domain‑specific workflows and outcomes (pipeline, QBRs, DORA metrics, ARR waterfall, etc.).\n\n### Canonical marketing → Workbench rule\n\n> Every **Solutions** page in `apps/marketing` must correspond to a **real domain workspace configuration** in `apps/web` (subdomain + projection + Twin + connectors), and its primary CTA must route through OneAuth into that exact configuration.\n\n---\n\n## 6. Platform stack layering\n\n### Shared control-plane services (global)\n\nTenant‑wide, not per‑domain; everything sits on these:\n\n- OneAuth / OneAccess:\n  - Identity, SSO, tenants, workspaces, roles, policies, sessions.\n- Connector Marketplace & Integration Manager:\n  - Host connectors + MCP connectors (definitions, scopes, health, versions).\n- MCP Gateway / MCP Pool:\n  - Shared MCP client/gateway and registry for all agents and Workbenches.\n- Platform backend services:\n  - Activation, Capability Manager, Spine Graph, Knowledge & Memory, Agent Runtime, Pipelines/Automation, Governance, Observability, Admin, Portfolio.\n\n### Product Package (capability layer, shared, role-aware)\n\nShared logic, role‑filtered per user:\n\n- Discovery:\n  - Enumerates host apps, data, tools, MCP servers.\n- Capabilities:\n  - Computes “what can be done” (read/analyze/propose/write‑back) per connector, MCP tool, domain, and role.\n- Spine cache + anchor keys:\n  - Canonical entities and relationships (Entity360).\n- Orchestrator + business context:\n  - Routes tools and agents while preserving business context (account, opportunity, customer, workstream).\n- Loader + Normalizer:\n  - Loads data from hosts and maps into Spine entities.\n- MCP Connector + tool capability:\n  - Unified connector/gateway pattern for MCP tools, exposed into agents and Workbench under auth and policy.[6][2]\n\n### Platform backend: packages & services\n\nKey packages:\n\n- `spine-schema`, `spine-entities`, `spine-projections`\n- `workbench-config`\n- Connector contracts, capability registry\n- `mcp-gateway` / MCP client packages\n- `agent-runtime` and domain Twin packages\n- `governance-core`, `observability-core`\n- Design system / UI packages\n\nKey services:\n\n- Identity & access: OneAuth/OneAccess, Admin.\n- Integration & MCP: Integration Manager, Connector Marketplace, Capability Manager, MCP Pool.\n- Graph & knowledge: Spine Graph, Knowledge & Memory.\n- Agents & runtime: Agent Runtime, Twin Manager.\n- Pipelines & automation: Pipeline Orchestrator, Automation.\n- Governance & observability: Governance, Observability, Metrics/Logs/Traces, Cost & Usage.\n- Portfolio & billing: Portfolio, Billing & Usage.\n\n### User Workbench (`apps/web`)\n\n- Shared web shell (plus desktop/mobile clients using same API).\n- Projection‑aware:\n  - Hostname selects projection key and domain Twin.\n  - OneAuth/OneAccess and Capability Manager constrain what the user actually sees and can do.\n- Embeds:\n  - Common sidebar grammar (Home, My Work, Inbox, Work, Platform, Admin).\n  - Canvas, views, Twin/OODA affordances (“Store in Spine”, “Ask Twin”, “Assign Twin”, “Approve Twin Action”).\n- No local business state; all state flows through Spine, connectors, memory, and platform services.\n\n---\n\nThis combined document gives you:\n\n- The **rooted access-and-projection model** (OneAuth root, subdomains as projections, `apps/web` as the shell).\n- The **full domain/subdomain map**.\n- The **common Workbench sidebar grammar**.\n- The **apps/platform control plane UI** mapping to services, agents, and packages.\n- The **apps/marketing solutions catalog** and its routing contract into domain workspaces.\n- The **shared platform stack layering** that everything runs on.\n"}