Frontend

Application Shell

Relevant source files

The following files were used as context for generating this wiki page:

The Application Shell provides the top-level layout and infrastructure for the Primebrick frontend. It manages the global UI state, including backend health monitoring, module navigation, side-sheet orchestration, and the command palette.

Shell Infrastructure

The shell is composed of three primary structural components defined in AppShell.svelte:

AppSidebar: Handles primary navigation, organization switching, and system health status src/lib/components/AppSidebar.svelte:1-124.
AppTopbar: Contains the global search (Command Palette), language switcher, theme toggle, and status indicators for errors and notifications src/lib/components/AppTopbar.svelte:118-180.
Sidebar.Inset: The main content area where SvelteKit route components are rendered src/lib/components/AppShell.svelte:86-97.

Component Hierarchy

The following diagram illustrates the relationship between the shell components and the global state managers.

Shell Architecture Overview

Code
graph TD
    subgraph "Root Context"
        AS["AppShell.svelte"]
    end

    subgraph "Global State & Services"
        BS["backendState (backend-availability.svelte.ts)"]
        SN["shellNav (modules-shell.svelte)"]
        SM["sheetState (sheet-manager.svelte.ts)"]
        UP["userProfileState (user-profile-store.svelte)"]
    end

    subgraph "Layout Components"
        ASB["AppSidebar.svelte"]
        ATB["AppTopbar.svelte"]
        SH["SheetHost.svelte"]
        CP["CommandPalette.svelte"]
    end

    AS --> ASB
    AS --> ATB
    AS --> SH
    ATB --> CP

    ASB -.-> BS
    ASB -.-> SN
    ASB -.-> UP
    SH -.-> SM
    CP -.-> SN

Sources: src/lib/components/AppShell.svelte:1-16, src/lib/components/AppSidebar.svelte:10-19, src/lib/shell/sheets/SheetHost.svelte:1-10 (implied by src/lib/components/AppShell.svelte:9)

Core Subsystems

AppShell & Health Monitoring

AppShell.svelte acts as the root wrapper for all authenticated routes. It initializes the probeHealth() loop to monitor backend, database, and IDP availability src/lib/components/AppShell.svelte:22-24. If connectivity is lost, it triggers a polling interval every 5 seconds until the system recovers src/lib/components/AppShell.svelte:49-58.

For details, see AppShell, Sidebar & Topbar.

Global Side Sheet System

The application uses a centralized side-sheet infrastructure to manage slide-over panels (e.g., Error Logs, Version History). The sheet-manager.svelte.ts singleton provides a type-safe API (openSheet, closeSheet) to control the SheetHost.svelte registry src/lib/shell/sheets/sheet-manager.svelte.ts:1-50.

For details, see Global Side Sheet System.

Command Palette

The CommandPalette.svelte component provides a "Spotlight-style" interface for global search and quick actions src/lib/components/CommandPalette.svelte:122-125. It is activated via keyboard shortcuts (Ctrl+K or Cmd+K) and integrates with the shellNav module system to surface available pages src/lib/components/CommandPalette.svelte:55-59.

For details, see Command Palette.

Theming & Styling

The shell implements a dual-layer CSS system using Tailwind CSS v4 and HSL/OKLCH variables src/app.css:9-71. It defines semantic tokens for different impact levels (e.g., --color-critical) and "chrome" tokens for sidebar and topbar backgrounds src/app.css:38-70.

For details, see Theming & Global Styles.

Code-to-Entity Mapping

This diagram maps natural language shell concepts to their specific TypeScript and Svelte implementations.

Entity Mapping

Code
classDiagram
    class GlobalShellState {
        +backendState : backend-availability.svelte.ts
        +shellNav : modules-shell.svelte
        +userProfileState : user-profile-store.svelte
    }
    class UIComponents {
        +AppShell : AppShell.svelte
        +AppSidebar : AppSidebar.svelte
        +AppTopbar : AppTopbar.svelte
        +SheetHost : SheetHost.svelte
    }
    class Utilities {
        +probeHealth() : backend-availability.svelte.ts
        +openSheet() : sheet-manager.svelte.ts
        +pushAppError() : app-errors.ts
    }

    AppShell --|> GlobalShellState : consumes
    AppSidebar --|> GlobalShellState : consumes
    AppTopbar --|> Utilities : calls
    SheetHost --|> Utilities : calls

Sources: src/lib/components/AppShell.svelte:12-15, src/lib/backend-availability.svelte.ts:19-30, src/lib/shell/sheets/sheet-manager.svelte.ts:1-20

Key Files

File	Responsibility
`src/lib/components/AppShell.svelte`	Root layout wrapper and health probe lifecycle src/lib/components/AppShell.svelte:1-98.
`src/lib/components/AppSidebar.svelte`	Module navigation, org switcher, and health chip UI src/lib/components/AppSidebar.svelte:1-170.
`src/lib/components/AppTopbar.svelte`	Global search, language/theme toggles, and error/notification badges src/lib/components/AppTopbar.svelte:118-180.
`src/lib/backend-availability.svelte.ts`	Reactive state for backend/DB/IDP health status src/lib/backend-availability.svelte.ts:19-30.
`src/app.css`	Global styles, Tailwind v4 theme, and semantic color tokens src/app.css:1-71.

Sources: src/lib/components/AppShell.svelte:1-98, src/lib/components/AppSidebar.svelte:1-170, src/lib/components/AppTopbar.svelte:118-180, src/lib/backend-availability.svelte.ts:19-30, src/app.css:1-71

Last modified on July 13, 2026

Application Routes & Modules AppShell, Sidebar & Topbar