# Initiative Brief: Canonical Workspaces Host Architecture and Complete Orchestrator Shell Integration ## Desired outcome Establish and enforce a canonical Workspaces host architecture that fully composes platform-owned workspace facilities, then migrate the Orchestrator workspace onto that architecture without rewriting its existing routing or domain topology. After this initiative: - Workspaces provides a clear, reusable, documented composition path for platform-owned workspace facilities. - Workspace implementations contribute domain UI, declarative navigation, semantic context, capabilities, and other workspace-specific data rather than reconstructing shared shell behavior. - Orchestrator consumes the real platform navigation/menu rail, conversation history, Composer, attachments/screenshots, runtime integration, confirmation/audit UX, responsive behavior, and other applicable shared Workspaces facilities. - The existing Orchestrator placeholder conversation/Composer regions are removed. - Future workspace implementations, including Web, have an authoritative architectural path that strongly discourages or prevents ad-hoc replacements for platform facilities. This initiative must **not** be interpreted as an instruction to rewrite Orchestrator onto canonical Sales routing, convert it to the Sales module topology, or migrate its URLs to `/w/:workspaceId/*`. The goal is canonical **platform ownership and composition**, not canonical application routing. ## Motivation The original Workspace Shell, Context Contract, and Conversational Runtime work established the correct platform ownership model and delivered most of the shared facilities required by workspace applications. However, those architectural ideas and implementations are currently fragmented across: - the workspace contract; - shared `@xyence/shell` components; - Composer and conversation documentation; - Sales as the most complete consumer; - an older Orchestrator-local `PlatformShell`; - historical documentation that still describes conversation and Composer regions as placeholders. This allowed Orchestrator to consume part of the new shell architecture while leaving the conversation history and Composer regions unintegrated. The current Orchestrator application therefore presents an incomplete platform experience even though the shared capabilities already exist. More importantly, the same ambiguity could affect future workspace implementations. A developer or implementation agent following the repository today can discover the correct principles, but still has enough freedom to manually assemble or omit platform facilities. That is an architectural gap, not merely an Orchestrator UI bug. Before implementing additional workspace applications such as Web, Workspaces should expose an authoritative path that makes the intended ownership boundary unmistakable: **the platform owns the workspace experience; a workspace owns its domain.** ## Current state - `@xyence/shell` contains shared workspace UI and conversational infrastructure. - The platform Composer is already implemented. - Shared conversation history, persistence, runtime send/retry, attachments, screenshots, confirmations, receipts, and semantic-context plumbing already exist. - The workspace contract describes navigation, context types, capabilities, landing metadata, and related declarative workspace information. - Contract validity is already enforced by a shared CI harness. - Sales is currently the most complete consumer of the shared conversation surface. - Orchestrator uses an app-local `PlatformShell`. - The Orchestrator shell currently renders real navigation and domain content but placeholder conversation-history and Composer regions. - Orchestrator has a standalone Next topology with root-level routes, its own auth/scope composition, and existing control-plane/domain adapters. - Orchestrator is not currently mounted through the canonical Sales-style `WorkspaceContainer` routing topology. - Existing Workspaces documentation contains the correct ownership principles but is partly historical and inconsistent about the current full shell architecture. - `docs/adding-a-workspace-app.md` currently points developers toward Orchestrator as a reference host shape even though Orchestrator itself is missing the complete conversational integration. - The existing workspace contract harness validates workspace declarations but does not necessarily prove that a host consumed every mandatory platform-owned facility. ## Product principles - Conversation is a platform capability, not a workspace-specific chat feature. - Navigation chrome is a platform capability, not app-local UI. - The Composer is a platform capability, not an optional design pattern. - Shared mutation confirmation and receipt behavior is platform-owned. - Workspace applications should feel like different domains within one coherent product system. - Domain content remains first-class; the platform shell should support it rather than dominate it. - Workspace switching must switch conversation and platform scope without cross-workspace leakage. - In-workspace navigation refines semantic context without implicitly creating a conversation. - Users should not need to understand whether a workspace uses SPA routing, standalone Next routing, module routing, or another supported host topology. ## Architectural principles - Prefer one canonical Workspaces host-composition API over manual assembly of many independent platform components. - The composition API should own the standard platform facilities and expose narrow extension/adaptation points for host-specific concerns. - Workspace contracts provide declarative data, not shell-region JSX. - Platform shell facilities should live in shared Workspaces packages rather than being copied into individual apps. - Application-specific adapters are acceptable when topology differs, but those adapters connect into the platform architecture rather than replace it. - Shared APIs should not assume Sales routing unless that assumption is fundamental to the platform contract. - Existing authenticated/scoped `ApiClient` infrastructure should be reused for conversation/runtime/upload clients. - Backend authorization remains authoritative. - Browser-side code must not receive controller credentials, provider credentials, service JWTs, or equivalent secrets. - Active organization/workspace selection remains authoritative browser-side scope input. - Shared components should degrade visibly and safely when dependent platform APIs are unavailable. - Architectural exceptions should be deliberate and documented, not accidental consequences of local implementation.