Frontend

Project Structure

Relevant source files

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

This page provides a technical walkthrough of the Primebrick Frontend directory layout and architectural organization. The project is built with SvelteKit and Svelte 5, utilizing a modular structure that separates core business logic, UI primitives, and domain-specific components.

High-Level Directory Layout

The codebase follows a standard SvelteKit structure with additional directories for AI governance, documentation, and automation scripts.

Directory	Purpose
`src/routes/`	SvelteKit routing tree, including the primary `(app)` route group.
`src/lib/`	Shared frontend logic, components, and state management.
`docs/`	Technical documentation and AI-specific guidelines.
`scripts/`	Automation scripts (e.g., version synchronization).
`.devin/`	AI agent configurations and custom instructions.

Sources: README.md:32-40, AGENTS.md:42-47

The `src/routes` Tree

The routing structure utilizes SvelteKit's layout system to manage different application states (e.g., public login vs. authenticated backoffice).

The `(app)` Route Group

The majority of the application resides within the (app) route group. This group shares a common AppShell.svelte layout, which provides the sidebar, topbar, and global error boundaries.

Navigation is driven by the shellNav state, which tracks module availability and loading status.

Path: src/lib/shell/modules-shell.svelte
Key Function: loadShellNav() is called on mount in AppShell.svelte to populate the sidebar navigation based on backend modules.

Sources: src/lib/components/AppShell.svelte:12-24, src/lib/components/AppSidebar.svelte:14-14

The `src/lib` Directory

src/lib is the heart of the application logic. It is organized into several functional subdirectories:

UI Components (`src/lib/components`)

The component library is split into two distinct tiers:

UI Primitives (ui/*): Vendored and customized Shadcn-Svelte components (e.g., Button, Input, Sidebar). These are located in src/lib/components/ui/ README.md:37-40.
Domain Components: Higher-level components specific to Primebrick (e.g., AppSidebar, AppTopbar, BrowserClientInfo).

Shell and Infrastructure (`src/lib/shell`)

Contains the logic for the application's global UI state:

Sheet Manager: A singleton sheet-manager.svelte.ts that manages the global side-sheet infrastructure (opening, closing, and stacking panels).
Entity List: Composable logic for the data-grid system used throughout the app.

State and Logic

composables/: Svelte 5 runes-based logic for reusable behavior (e.g., useSelection, useRowActions).
errors/: Centralized error handling using the appErrors store and pushImpactError function src/lib/components/AppSidebar.svelte:15-15.
i18n/: Internationalization system using a derived $t store for reactive translations src/lib/components/AppSidebar.svelte:11-11.
user-profile-store.svelte.ts: Reactive state for the currently authenticated user src/lib/components/AppSidebar.svelte:19-19.

Backend Availability and Health Monitoring

The application implements a robust health monitoring system to handle backend, database, or Identity Provider (IDP) failures gracefully.

Component Relationship Diagram

The following diagram illustrates how the shell components interact with the health monitoring system.

Title: Health Monitoring & Shell Integration

Code
graph TD
    subgraph "Code Entity Space"
        BS["backendState (src/lib/backend-availability.svelte.ts)"]
        PH["probeHealth() (src/lib/backend-availability.svelte.ts)"]
        AS["AppShell.svelte (src/lib/components/AppShell.svelte)"]
        SB["AppSidebar.svelte (src/lib/components/AppSidebar.svelte)"]
        ACE["app-connectivity-events.ts"]
    end

    AS -- "onMount calls" --> PH
    AS -- "polling loop (5s)" --> PH
    PH -- "updates" --> BS
    BS -- "reactive state" --> SB
    SB -- "renders" --> HC["Health Chip UI"]
    PH -- "triggers" --> ACE
    ACE -- "CustomEvent" --> DIS["dispatchConnectivityRestored"]

Sources: src/lib/backend-availability.svelte.ts:19-30, src/lib/components/AppShell.svelte:22-24, src/lib/components/AppShell.svelte:49-58, src/lib/app-connectivity-events.ts:10-14

AI and Development Governance

The project includes strict rules for AI agents and development workflows to maintain code quality.

`.devin` and `AGENTS.md`

AGENTS.md: Contains mandatory Svelte 5 and TypeScript rules, such as the requirement to use Runes ($state, $derived, $props) and the prohibition of automatic commits AGENTS.md:1-26.
docs/ai/patterns.md: Documents UI patterns and the Shadcn vendor update workflow docs/ai/README.md:7-7.

Versioning Automation

A script located at scripts/version-sync.mjs (triggered by a prebuild hook) ensures that the version in package.json stays in sync with Git tags and branch names (release/* or hotfix/*) docs/gitflow.md:46-54.

Data Flow: API to UI

The diagram below shows the flow from an API response to the UI, including error handling.

Title: API Data Flow and Error Handling

Code
sequenceDiagram
    participant API as "API (src/lib/api.ts)"
    participant BS as "backendState"
    participant ERR as "app-errors (src/lib/errors/)"
    participant UI as "AppSidebar / UI"

    API->>API: apiFetch()
    alt Gateway Failure (502/503/504)
        API->>BS: noteGatewayFailure(status)
        BS->>BS: setBackendOffline(true)
        BS->>UI: Update HealthChip ('backend_offline')
    else Application Error
        API->>UI: Return Response (not ok)
        UI->>ERR: pushImpactError(payload)
        ERR->>UI: Show Toast / ErrorsPanel
    end

Sources: src/lib/backend-availability.svelte.ts:171-180, src/lib/components/AppSidebar.svelte:55-74, src/lib/api-types.ts:34-38

Last modified on July 13, 2026

Overview Row Actions, Selection & Bulk Operations

Frontend

Project Structure

Relevant source files

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

High-Level Directory Layout

The codebase follows a standard SvelteKit structure with additional directories for AI governance, documentation, and automation scripts.

Directory	Purpose
`src/routes/`	SvelteKit routing tree, including the primary `(app)` route group.
`src/lib/`	Shared frontend logic, components, and state management.
`docs/`	Technical documentation and AI-specific guidelines.
`scripts/`	Automation scripts (e.g., version synchronization).
`.devin/`	AI agent configurations and custom instructions.

Sources: README.md:32-40, AGENTS.md:42-47

The `src/routes` Tree

The routing structure utilizes SvelteKit's layout system to manage different application states (e.g., public login vs. authenticated backoffice).

The `(app)` Route Group

The majority of the application resides within the (app) route group. This group shares a common AppShell.svelte layout, which provides the sidebar, topbar, and global error boundaries.

Navigation is driven by the shellNav state, which tracks module availability and loading status.

Path: src/lib/shell/modules-shell.svelte
Key Function: loadShellNav() is called on mount in AppShell.svelte to populate the sidebar navigation based on backend modules.

Sources: src/lib/components/AppShell.svelte:12-24, src/lib/components/AppSidebar.svelte:14-14

The `src/lib` Directory

src/lib is the heart of the application logic. It is organized into several functional subdirectories:

UI Components (`src/lib/components`)

The component library is split into two distinct tiers:

UI Primitives (ui/*): Vendored and customized Shadcn-Svelte components (e.g., Button, Input, Sidebar). These are located in src/lib/components/ui/ README.md:37-40.
Domain Components: Higher-level components specific to Primebrick (e.g., AppSidebar, AppTopbar, BrowserClientInfo).

Shell and Infrastructure (`src/lib/shell`)

Contains the logic for the application's global UI state:

Sheet Manager: A singleton sheet-manager.svelte.ts that manages the global side-sheet infrastructure (opening, closing, and stacking panels).
Entity List: Composable logic for the data-grid system used throughout the app.

State and Logic

composables/: Svelte 5 runes-based logic for reusable behavior (e.g., useSelection, useRowActions).
errors/: Centralized error handling using the appErrors store and pushImpactError function src/lib/components/AppSidebar.svelte:15-15.
i18n/: Internationalization system using a derived $t store for reactive translations src/lib/components/AppSidebar.svelte:11-11.
user-profile-store.svelte.ts: Reactive state for the currently authenticated user src/lib/components/AppSidebar.svelte:19-19.

Backend Availability and Health Monitoring

The application implements a robust health monitoring system to handle backend, database, or Identity Provider (IDP) failures gracefully.

Component Relationship Diagram

The following diagram illustrates how the shell components interact with the health monitoring system.

Title: Health Monitoring & Shell Integration

Code
graph TD
    subgraph "Code Entity Space"
        BS["backendState (src/lib/backend-availability.svelte.ts)"]
        PH["probeHealth() (src/lib/backend-availability.svelte.ts)"]
        AS["AppShell.svelte (src/lib/components/AppShell.svelte)"]
        SB["AppSidebar.svelte (src/lib/components/AppSidebar.svelte)"]
        ACE["app-connectivity-events.ts"]
    end

    AS -- "onMount calls" --> PH
    AS -- "polling loop (5s)" --> PH
    PH -- "updates" --> BS
    BS -- "reactive state" --> SB
    SB -- "renders" --> HC["Health Chip UI"]
    PH -- "triggers" --> ACE
    ACE -- "CustomEvent" --> DIS["dispatchConnectivityRestored"]

Sources: src/lib/backend-availability.svelte.ts:19-30, src/lib/components/AppShell.svelte:22-24, src/lib/components/AppShell.svelte:49-58, src/lib/app-connectivity-events.ts:10-14

AI and Development Governance

The project includes strict rules for AI agents and development workflows to maintain code quality.

`.devin` and `AGENTS.md`

AGENTS.md: Contains mandatory Svelte 5 and TypeScript rules, such as the requirement to use Runes ($state, $derived, $props) and the prohibition of automatic commits AGENTS.md:1-26.
docs/ai/patterns.md: Documents UI patterns and the Shadcn vendor update workflow docs/ai/README.md:7-7.

Versioning Automation

Data Flow: API to UI

The diagram below shows the flow from an API response to the UI, including error handling.

Title: API Data Flow and Error Handling

Code
sequenceDiagram
    participant API as "API (src/lib/api.ts)"
    participant BS as "backendState"
    participant ERR as "app-errors (src/lib/errors/)"
    participant UI as "AppSidebar / UI"

    API->>API: apiFetch()
    alt Gateway Failure (502/503/504)
        API->>BS: noteGatewayFailure(status)
        BS->>BS: setBackendOffline(true)
        BS->>UI: Update HealthChip ('backend_offline')
    else Application Error
        API->>UI: Return Response (not ok)
        UI->>ERR: pushImpactError(payload)
        ERR->>UI: Show Toast / ErrorsPanel
    end

Sources: src/lib/backend-availability.svelte.ts:171-180, src/lib/components/AppSidebar.svelte:55-74, src/lib/api-types.ts:34-38

Last modified on July 13, 2026

Overview Row Actions, Selection & Bulk Operations

Project Structure

Project Structure

High-Level Directory Layout

The `src/routes` Tree

The `(app)` Route Group

Navigation and Module Loading

The `src/lib` Directory

UI Components (`src/lib/components`)

Shell and Infrastructure (`src/lib/shell`)

State and Logic

Backend Availability and Health Monitoring

Component Relationship Diagram

AI and Development Governance

`.devin` and `AGENTS.md`

Versioning Automation

Data Flow: API to UI

Project Structure

Project Structure

High-Level Directory Layout

The `src/routes` Tree

The `(app)` Route Group

Navigation and Module Loading

The `src/lib` Directory

UI Components (`src/lib/components`)

Shell and Infrastructure (`src/lib/shell`)

State and Logic

Backend Availability and Health Monitoring

Component Relationship Diagram

AI and Development Governance

`.devin` and `AGENTS.md`

Versioning Automation

Data Flow: API to UI

Project Structure

High-Level Directory Layout

The src/routes Tree

The (app) Route Group

Navigation and Module Loading

The src/lib Directory

UI Components (src/lib/components)

Shell and Infrastructure (src/lib/shell)

State and Logic

Backend Availability and Health Monitoring

Component Relationship Diagram

AI and Development Governance

.devin and AGENTS.md

Versioning Automation

Data Flow: API to UI

Project Structure

High-Level Directory Layout

The src/routes Tree

The (app) Route Group

Navigation and Module Loading

The src/lib Directory

UI Components (src/lib/components)

Shell and Infrastructure (src/lib/shell)

State and Logic

Backend Availability and Health Monitoring

Component Relationship Diagram

AI and Development Governance

.devin and AGENTS.md

Versioning Automation

Data Flow: API to UI

The `src/routes` Tree

The `(app)` Route Group

The `src/lib` Directory

UI Components (`src/lib/components`)

Shell and Infrastructure (`src/lib/shell`)

`.devin` and `AGENTS.md`

The `src/routes` Tree

The `(app)` Route Group

The `src/lib` Directory

UI Components (`src/lib/components`)

Shell and Infrastructure (`src/lib/shell`)

`.devin` and `AGENTS.md`