⬅️ Back to Frontend Architecture Index

App Shell

1️⃣ Section Purpose

This section documents the App Shell: the top-level UI structure that wraps pages and provides shared layout, global UI state, and cross-cutting user interactions.

It exists to keep application-wide concerns consistent (navigation chrome, header/sidebar, settings entry points, notifications) and to ensure the UI has a single, predictable place where these concerns are orchestrated.

Design decisions captured here include the “thin orchestrator” approach (shell coordinates, sub-components render), separation between authenticated vs. public shells, and how user preferences like theme and locale are applied consistently across the app.

2️⃣ Scope & Boundaries

Included: - Shell composition and responsibilities (authenticated shell vs. public shell) - Layout coordination (header / sidebar / main content orchestration) - Global UI state owned by the shell (drawer open/close, settings dialog visibility) - Cross-cutting UI capabilities surfaced through the shell (theme mode, locale switching, toast notifications) - Preference persistence at shell level (e.g., theme and locale stored in browser storage)

Excluded: - Feature/domain page structure (documented under Domains) - API/data-fetching implementation details (documented under Data Access) - Component-level UI patterns (documented under UI Components) - Detailed routing rules and route guards (documented under Routing) - Authentication implementation (documented under the relevant auth sections)

3️⃣ High-Level Diagram

graph TB Routes["Routes"] -->|public| PublicShell["Public Shell\n(header + content + toast)"] Routes -->|authenticated| AppShell["App Shell\n(header + sidebar + main)"] PublicShell --> Theme["Theme + Locale"] AppShell --> Theme PublicShell --> Toast["Toast Notifications"] AppShell --> Toast AppShell --> Settings["Settings Entry Points"] AppShell --> Help["Context Help (route → topic)"]

Contents

⬅️ Back to Frontend Architecture Index