# Application Shell

# Application Shell

<details>
<summary>Relevant source files</summary>

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

- [src/app.css](src/app.css)
- [src/lib/api-types.ts](src/lib/api-types.ts)
- [src/lib/app-connectivity-events.ts](src/lib/app-connectivity-events.ts)
- [src/lib/backend-availability.svelte.ts](src/lib/backend-availability.svelte.ts)
- [src/lib/components/AppShell.svelte](src/lib/components/AppShell.svelte)
- [src/lib/components/AppSidebar.svelte](src/lib/components/AppSidebar.svelte)
- [src/lib/components/AppTopbar.svelte](src/lib/components/AppTopbar.svelte)
- [src/lib/components/CommandPalette.svelte](src/lib/components/CommandPalette.svelte)
- [src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte](src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte)
- [src/lib/components/ui/button/button.svelte](src/lib/components/ui/button/button.svelte)
- [src/lib/components/ui/checkbox/checkbox.svelte](src/lib/components/ui/checkbox/checkbox.svelte)
- [src/lib/components/ui/input/input-chrome.ts](src/lib/components/ui/input/input-chrome.ts)
- [src/lib/components/ui/input/input.svelte](src/lib/components/ui/input/input.svelte)
- [src/lib/components/ui/kbd/index.ts](src/lib/components/ui/kbd/index.ts)
- [src/lib/components/ui/kbd/kbd.svelte](src/lib/components/ui/kbd/kbd.svelte)
- [src/lib/components/ui/sidebar/sidebar-inset.svelte](src/lib/components/ui/sidebar/sidebar-inset.svelte)
- [src/lib/components/ui/sidebar/sidebar-provider.svelte](src/lib/components/ui/sidebar/sidebar-provider.svelte)

</details>



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`:
1.  **`AppSidebar`**: Handles primary navigation, organization switching, and system health status [src/lib/components/AppSidebar.svelte:1-124]().
2.  **`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]().
3.  **`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**
```mermaid
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](#3.1).

### 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](#3.2).

### 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](#3.3).

### 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](#3.4).

## Code-to-Entity Mapping

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

**Entity Mapping**
```mermaid
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]()

---