--- id: DOM-PFM-CSH-002 title: Navigation realises: CON-PFM-CSH-002 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: [] custom_fields: none identity: >- The rendered menu is derived for the person and working context. Section keys and destination addresses identify its parts, without a stored menu record. attributes: - name: application sections kind: collection required: true computed: false notes: >- The registry orders CRM, Membership, Boards & Committees, Marketing, then Accounting; the planning delta requires a different Accounting position. - name: menu entry kind: collection required: true computed: false notes: >- An entry combines label, destination, icon, optional permission, domain and build status. - name: tools and application links kind: collection required: true computed: false notes: >- Shared destinations include Tasks, Queries, Reports & Dashboards and the unconditional Websites link. - name: settings areas kind: collection required: true computed: false notes: >- Administrative areas carry roots, revealing permissions, groups and separate filters. - name: Rhythm HQ links kind: collection required: true computed: false notes: >- Staff HQ mode offers home, customers, staff, workspaces, jobs, notifications, AI usage and custom query tables. - name: custom placements kind: collection required: false computed: true notes: >- Metadata answers with active placements and their custom apps, restricted to readable records. - name: filter text kind: text required: false computed: false notes: >- Filtering trims the query and ignores case; a matched section label retains its entries. - name: active place kind: computed required: true computed: true notes: >- The current path highlights entries, including descendants unless exact matching is requested. - name: open section kind: computed required: false computed: true notes: >- Outside filtering, one section is open and the current destination selects it. relationships: - to: DOM-PFM-CSH-001 cardinality: one rendered menu to one shell ownership: The shell renders the menu and controls its desktop fold. cross_service: false - to: DOM-PFM-CSH-003 cardinality: one menu entry to one destination ownership: Menu destinations use workspace-relative routes from the shared builders. cross_service: false - to: DOM-PFM-CSH-004 cardinality: one domain section to one console domain ownership: The held application answer determines which domain sections can render. cross_service: true invariants: - id: INV-DOM-PFM-CSH-002-01 statement: >- Domain sections require enabled applications, filter their entries by permission and disappear when empty. enforced_at: - console provenance: test source: >- react-console:lib/console/__tests__/registries.test.ts#hides domains the user cannot access and keeps what they can - id: INV-DOM-PFM-CSH-002-02 statement: >- Menu filtering supplements page and API checks rather than authorizing access itself. enforced_at: - console - api provenance: documented source: >- services-platform:docs/proposals/application-access-and-entitlements.md#5.3 Tenant isolation, caching and staleness (a stale console can show a link, but the API refuses it) - id: INV-DOM-PFM-CSH-002-03 statement: >- A settings entry requires its area permission and at least one visible destination inside the area. enforced_at: - console provenance: test source: >- react-console:lib/console/__tests__/settings-area-menu.test.ts#does not offer Security or Maintenance to a person who holds only the areas' access keys - id: INV-DOM-PFM-CSH-002-04 statement: >- Initial placement loading or failure adds no entries and does not block the built-in menu. enforced_at: - console provenance: observed source: >- react-console:lib/custom-objects/use-custom-navigation.ts:useCustomNavigation - id: INV-DOM-PFM-CSH-002-05 statement: >- Metadata’s navigation result is trusted; fallback definitions undergo local checks that require an explicit type grant for restricted types. enforced_at: - console - api provenance: test source: >- react-console:lib/custom-objects/__tests__/navigation.test.ts#trusts the navigation route's answer, even where the key is held tenant-wide and no scoped entry names the object - id: INV-DOM-PFM-CSH-002-06 statement: >- Sections survive the build-status filter when they contain a built entry or a customer placement. enforced_at: - console provenance: test source: >- react-console:lib/custom-objects/__tests__/navigation.test.ts#keeps a hidden domain reachable when a custom object is placed under it - id: INV-DOM-PFM-CSH-002-07 statement: >- The first registered occurrence of a destination supplies its catch-all identity and section. enforced_at: - console provenance: observed source: 'react-console:components/console/nav-config.ts:allNav' - id: INV-DOM-PFM-CSH-002-08 statement: >- The planning delta requires Accounting directly after CRM while preserving the relative order of other applications. enforced_at: [] provenance: documented source: >- rhythm-v2-docs:specs/platform/console-shell/planning/capabilities/CAP-PFM-CSH-006-find-my-way-through-the-applications-menu.md:BR-CAP-PFM-CSH-006-13 physical: [] evidence: - >- react-console at baf6dae: components/console/{nav-config.ts,app-sidebar.tsx}; lib/console/{domains.ts, use-visible-nav.ts}; lib/custom-objects/{navigation.ts,use-custom-navigation.ts}; lib/authz/evaluate.ts. - >- services-platform at ad3f6a6: modules/custom-objects/aws/api/custom-objects.routes.ts (getCustomObjectsNavigation, listCustomObjects); custom-apps.routes.ts (listCustomApps). - >- rhythm-v2-docs:specs/platform/console-shell/FINDINGS.md:FND-PFM-CSH-042 (planned ordering is not enforced by the pinned console). --- # Navigation ## What It Models The navigation object organizes console destinations into application sections, tools and administrative areas. Customer record placements extend that map. Rhythm HQ presents a separate list for staff, and the current address identifies the active destination. ## Identity and Attributes Sections and entries have registry keys and destinations rather than persistent menu records. Entries carry labels, icons, permission hints and build status. Filter text and section expansion belong to the current rendered menu. At the pinned source, Accounting follows Marketing; the recorded planning change requires it immediately after CRM. ## Relationships The shell contains the menu, and each menu entry targets a console address. Application entitlements determine which sections can appear. Metadata supplies the record types and custom apps that extend the built-in map. ## Invariants The invariant rows distinguish observed filtering from documented obligations. Menu visibility does not replace destination authorization. Settings entries require visible work within their area, and customer placements load independently of built-in entries. The required Accounting order is not enforced at the pinned source. ## How It Is Stored and Shared The console computes the menu from code registries and the current context. Metadata retains the underlying placement records. Its navigation answer is trusted; fallback definition lists are filtered locally. No service stores or consumes this menu as a record. ## Open Design Questions Product has not settled how customers encounter unfinished destinations. Websites is an unconditional menu link. The rule that sections need a built screen or a placement has implementation evidence but lacks an inspected confirming product record.