Description
App Shell Navigation is the persistent cockpit around every authenticated web module. It supplies the module rail, top bar, breadcrumbs, module sidebar, page toolbar, right-drawer stack, workspace switcher, profile menu, global overlays, and desktop tab host. Users can move among Home, Dotabases, Chat, Marketplace, settings, and entitled runtime modules without each feature reinventing navigation or chrome.
The shell derives routes and visible controls from a canonical module registry. The same entitlement-filtered roster feeds routing, rail visibility, commands, sidebars, providers, global mounts, and extension slots, preventing a hidden module from leaking stale UI elsewhere. It also owns shared resilience concerns such as connectivity banners, error boundaries, optimistic skeletons, focus-on-navigation, drawer sizing, and toast placement.
Selling Points
- Makes the platform feel like one product even though its modules have different workflows and data models.
- Keeps navigation honest by deriving routes, commands, and visible modules from the same entitlement-aware registry.
- Preserves context with breadcrumbs, sidebars, drawers, workspace switching, and desktop tabs instead of forcing users through repeated landing pages.
- Gives every module consistent keyboard, focus, loading, and error behavior, lowering cognitive and accessibility costs.
- Allows new in-repo modules to join the shell through declared seams rather than modifying every navigation component.
User Story
A user starts on Home, switches to Chat from the module rail, opens a cited row in a side peek, pins the drawer while comparing it with the conversation, then changes workspaces from the top bar. The chrome remains predictable throughout, and each transition retains the cues needed to understand where they are.
Extension Surface
The shell is extensible through designed in-repo registrations. apps/web/src/modules/registry.tsx defines module routes, sidebars, actions, global mounts, entity kinds, body renderers, and layout declarations. apps/web/src/modules/shell/extensions.ts composes those declarations into stable lookup surfaces. This is not an external plugin API by itself, so the rating stops at extensible rather than pluggable.
Capabilities & Limits
- Coordinates module routing, shared page chrome, overlay layers, drawer slots, tabs, workspaces, and global error presentation.
- Filters module navigation and routes by live tenant capabilities.
- Supports registry-contributed UI without shell-to-sibling component imports.
- Limit: the core shell layout and module-rail grammar are product-defined; end users cannot freely rearrange chrome or add arbitrary navigation items.
Implementation Map
apps/web/src/modules/shell/AppShell.tsxapps/web/src/modules/shell/ModuleRail.tsxapps/web/src/modules/registry.tsxapps/web/src/modules/shell/extensions.ts