--- id: CON-PFM-CSH-001 name: Console Shell feature: FEAT-PFM-CSH-01 product_area: platform module: console-shell revision: 2 status: draft product_intent: proposed implementation_evidence: observed source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 definition: >- The console shell is the shared workspace around console pages. It brings identity, working context, navigation and common tools together after access has been resolved. owned_by: MOD-PFM-CSH synonyms: - console frame - shared page frame not_to_be_confused_with: - The member-facing portal and its separate presentation - A page displayed within the frame - The access decisions supplied by Platform facets: - name: Header meaning: The upper part of the frame brings working context and shared tools into view. used_for: Orienting the person without leaving their current work. - name: Side menu meaning: The left-hand space contains navigation and can change its visible size. used_for: Giving navigation a stable place alongside the page. - name: Page body and page widths meaning: 'The central space presents the current page, with a layout appropriate to its task.' used_for: Balancing room for work against readable content. - name: Context notice meaning: A message above the frame explains a change in starting context. used_for: Making an unexpected landing understandable. - name: Start-up screens meaning: >- Before a working frame is available, a separate screen represents access resolution or its failure. used_for: Keeping uncertain identity and access out of the working interface. - name: Keyboard shortcuts meaning: Shared commands offer keyboard access to common destinations and panels. used_for: Reducing repeated movement through menus. - name: User menu meaning: Personal identity and account-level actions occupy a distinct menu. used_for: Separating personal actions from record work. - name: Workspace home meaning: The opening workspace page combines orientation with work that needs attention. used_for: Providing a starting point for a session. - name: Shell mode meaning: The frame distinguishes Rhythm staff work from customer workspace work. used_for: Keeping the context of staff activity visible. relationships: - to: CON-PFM-CSH-002 statement: Navigation supplies the destinations presented within the shared frame. provenance: observed source: 'react-console:components/console/app-sidebar.tsx:AppSidebar' - to: CON-PFM-CSH-003 statement: The current address gives the shell its workspace and operating mode. provenance: observed source: 'react-console:components/console/use-shell-mode.ts:useShellMode' - to: CON-PFM-CSH-004 statement: The shell hosts the page-level application check. provenance: observed source: 'react-console:components/console/console-shell.tsx:ConsoleShell' lifecycle: - state: starting meaning: Identity and access are being resolved before a working frame is shown. how_it_changes: 'An answer establishes access, refuses it or reports a request failure.' - state: refused or failed meaning: A separate screen explains why the console cannot yet open. Recovery depends on the cause. how_it_changes: >- A failed request can be retried; access can be reconsidered after sign-out; configuration needs setup correction. - state: ready meaning: The common frame presents the established person and working context. how_it_changes: Entering another workspace establishes a new working context. acted_on_by: - CAP-PFM-CSH-001 - CAP-PFM-CSH-002 - CAP-PFM-CSH-003 - CAP-PFM-CSH-004 - CAP-PFM-CSH-005 - CAP-PFM-CSH-013 visible_to: - ACT-PFM-001 - ACT-PFM-002 - ACT-PFM-004 - ACT-PFM-005 evidence: - >- react-console at baf6dae: app/(console)/layout.tsx, app/(console)/console/[tenantId]/page.tsx, components/console/{console-shell,site-header,console-provider,console-boot-screens,page-layout,collapse-sidebar,app-sidebar,feedback-dialog,use-shell-mode}.tsx, components/ui/sidebar.tsx, lib/layout/page-width.ts, docs/page-layouts.md (accepted 2026-10-12), docs/migration/02-information-architecture.md ยง1. - >- services-platform at ad3f6a6: modules/security/aws/api/access.routes.ts (the security context the shell waits for; owned by MOD-PFM-SEC). supersedes: [] --- # Console Shell ## What It Is The console shell is the shared workspace around Rhythm's console pages. It gives the person a recognizable place to work as the content changes from a record to a list or a settings page. Identity, navigation and common tools belong to that surrounding workspace; the current page contributes the work in its centre. A reliable frame helps a person answer three questions without interrupting the task: who is signed in, where the work belongs, and how to move elsewhere. Access resolution comes before this working view. Until the console knows enough to present the person and their context, the experience is a start-up screen rather than a partly assembled workspace. ## What It Is Not A page inside the frame has its own purpose and owner. The shell does not define how a contact is edited, how attention items are calculated or how search results are ranked. It provides places for those experiences to appear. The member-facing portal is also a separate experience. The shell is not the authority for access. Its presentation uses Platform's answer about the person and their workspace. A visible control helps someone find a task; it does not replace the checks performed when that task opens or requests data. ## How It Is Used Customer staff use the frame throughout their daily work. Administrators use it to move from operational pages into settings. Rhythm staff use the same surrounding experience while working for Rhythm or entering a customer's workspace, with the operating context made visible. The shared tools let a person search, inspect recent work or open assistance without treating each application as a separate console. A context notice explains an unexpected starting point. If access cannot be established, the start-up experience explains the cause and offers the recovery appropriate to that cause. Those distinctions matter because a request failure, a permission refusal and missing configuration need different responses. ## Its Facets **Header and personal actions.** The header concentrates working context and shared tools. The user menu gives identity and personal actions their own place, apart from the navigation of business records. **Navigation space and page space.** The side menu and central page body divide orientation from the task at hand. Page layout and menu folding determine how much room a task receives without changing the page's meaning. **Context and mode.** Workspace identity, staff operating mode and explanatory notices help the person understand whose work they are performing. The workspace home supplies an initial point of orientation. **Readiness and interaction.** Start-up screens express whether a usable workspace has been established. Once ready, keyboard commands and common controls make repeated actions easier to reach. ## How It Relates Navigation supplies the destinations displayed in the frame. Console addresses identify the current workspace and position. Application access affects what the page body can present. Security supplies identity and authority; the shell translates that context into a coherent working experience. Other modules own the tools hosted in the frame, including search, attention, recent items, notifications, assistance and financial working context. Keeping those ownership boundaries explicit makes it possible to improve the frame without silently changing the meaning of a hosted tool. ## What It Could Become The product should decide which account warnings deserve a persistent place in the frame. The product should replace sample dashboard information with an agreed home-page purpose, complete the personal actions that currently have no durable result, and decide how a person's preferred navigation size should survive a new visit. These are product choices awaiting review rather than approved extensions of the shell.