--- id: DOM-PFM-CSH-001 title: Console Shell realises: CON-PFM-CSH-001 product_area: platform module: console-shell revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 owned_by: SVC-PFM-CSH-console-shell readable_by: [] lifecycle: STATE-PFM-CSH-001 custom_fields: none identity: >- A browser tab holds one shell for its signed-in person and selected working context; there is no persistent shell identifier. attributes: - name: signed-in person kind: reference required: true computed: false notes: >- Security supplies the person’s identity, customer and staff status in the held context. - name: start-up phase kind: enum required: true computed: false notes: >- Loading, setup missing, no access, failed or ready describe the provider phase. - name: working context kind: reference required: false computed: false notes: >- The selected workspace is optional; staff can hold a context with no selected workspace. - name: reachable workspaces kind: collection required: true computed: false notes: The context’s reachable-workspace list supplies switcher choices. - name: shell mode kind: computed required: true computed: true notes: Address and selected context derive workspace or staff HQ presentation. - name: switching kind: enum required: true computed: false notes: The boolean indicates an in-flight entry or programmatic workspace switch. - name: context notice kind: text required: false computed: false notes: >- The current context explanation remains until dismissed or another context change clears it. - name: side menu fold kind: enum required: true computed: false notes: >- The desktop menu is open or folded; its cookie is written but not restored. - name: assistant panel open kind: enum required: true computed: false notes: Local open state controls the hosted assistant dock. - name: quick search open kind: enum required: true computed: false notes: Local open state controls the hosted search dialog. - name: sample working currency kind: enum required: true computed: false notes: The demonstration-money helper selects from five fixed currencies. - name: page width kind: enum required: true computed: false notes: >- The rendering page chooses Full or Standard, with Standard capped at eleven hundred pixels. - name: keyboard commands kind: collection required: true computed: false notes: >- Shared commands cover search, Configuration and assistant; SidebarProvider separately handles menu folding. relationships: - to: DOM-PFM-CSH-002 cardinality: one shell to one rendered menu ownership: 'The shell contains the menu, whose assembly selects entries.' cross_service: false - to: DOM-PFM-CSH-003 cardinality: one shell to one current address ownership: >- Address entry requests the context; provider operations install and refresh the held answer. cross_service: false - to: DOM-PFM-CSH-004 cardinality: one shell to one held application list ownership: >- The shell retains Security’s personal application answer backed by Operations records. cross_service: true invariants: - id: INV-DOM-PFM-CSH-001-01 statement: >- Production start-up withholds the frame and page until a context is available; demonstration mode can provide a fixed context. enforced_at: - console provenance: test source: >- react-console:e2e/dev/initialisation.dev.spec.ts#asks the Platform exactly one thing first, and shows nothing until it is answered - id: INV-DOM-PFM-CSH-001-02 statement: >- A final boot refusal shows no access and other request failures offer retry without granting authority. enforced_at: - console provenance: observed source: >- react-console:lib/security-context/provider.tsx:SecurityContextProvider (boot) - id: INV-DOM-PFM-CSH-001-03 statement: >- Non-staff use workspace mode, and the main menu presents HQ or workspace links according to the shared mode. enforced_at: - console provenance: observed source: >- react-console:components/console/use-shell-mode.ts:useShellMode; components/console/app-sidebar.tsx:MainNavigation - id: INV-DOM-PFM-CSH-001-04 statement: >- Workspace selection changes remount the keyed client subtree, and entry clears shared SWR data. enforced_at: - console provenance: observed source: >- react-console:lib/security-context/provider.tsx:SecurityContextProvider (AuthzProvider key) - id: INV-DOM-PFM-CSH-001-05 statement: >- Explicit sign-out removes drafts and workspace memory, clears SWR data and ends the session. enforced_at: - console provenance: observed source: 'react-console:lib/security-context/provider.tsx:signOut' - id: INV-DOM-PFM-CSH-001-06 statement: >- The rendering page selects width independently of the surrounding route area. enforced_at: - console provenance: documented source: 'react-console:docs/page-layouts.md#Rules' - id: INV-DOM-PFM-CSH-001-07 statement: Search shortcuts are intercepted only when search is permitted. enforced_at: - console provenance: observed source: 'react-console:components/console/console-provider.tsx:ConsoleProvider' - id: INV-DOM-PFM-CSH-001-08 statement: Home attention work mounts independently of dashboard-summary readiness. enforced_at: - console provenance: observed source: 'react-console:app/(console)/console/[tenantId]/page.tsx:HomePage' physical: [] evidence: - >- react-console at baf6dae: app/(console)/layout.tsx; components/console/{console-shell,console-provider,site-header, console-boot-screens,use-shell-mode,collapse-sidebar,page-layout}.tsx; components/ui/sidebar.tsx; lib/security-context/{provider.tsx,boot.ts,context.ts}; docs/page-layouts.md. - >- services-platform at ad3f6a6: modules/security/aws/api/access.routes.ts; docs/security/console-authentication.md#Console initialisation. --- # Console Shell ## What It Models The shell gives signed-in staff a common place to work. It surrounds pages with navigation, context information and entry points for search, recent records, alerts and the assistant. The modules responsible for those tools retain their behavior and data. ## Identity and Attributes A shell instance belongs to a browser tab and the person using it. Its held context identifies the selected workspace and reachable alternatives. Presentation state includes start-up progress, open panels, menu folding, context notices and page width. The demonstration currency helper is separate from the financial context shown in the header. ## Relationships The shell renders the menu, reads the address and holds the application list supplied by Security. Addresses request a workspace, while provider operations install or refresh its context. Operations owns the licensing records behind application availability. ## Invariants The structured invariants identify the gates and cleanup operations that are actually supported. Production pages wait for a context; demonstration mode can supply one locally. Workspace changes remount the keyed subtree and clear the shared SWR data. Explicit sign-out removes drafts and the remembered workspace before ending the session. ## How It Is Stored and Shared This is a client object with no service table or metadata registration. Browser storage remembers a workspace for each person, and a cookie records the menu fold. The cookie is not restored on load. Other services supply answers to the shell rather than reading its presentation state. ## Open Design Questions The context parser does not reject an unfamiliar contract version. Product still needs to settle the scope of refresh when a tab returns and the source of home-page figures. Removing the demonstration currency helper should accompany replacement of those figures.