Frontend

Glossary

Relevant source files

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

This page provides definitions for codebase-specific terms, domain concepts, and technical abbreviations used throughout the Primebrick Frontend. It serves as a reference for onboarding engineers to understand the "language" of the project and how high-level concepts map to implementation.

Domain Concepts

Backoffice Shell

The "Shell" refers to the persistent UI framework that wraps all application modules. It includes the AppSidebar, AppTopbar, and the global SheetHost. It is responsible for cross-cutting concerns like navigation, health monitoring, and the command palette.

Implementation: AppShell.svelte acts as the root wrapper for all routes under the (app) group. src/lib/components/AppShell.svelte
Navigation: Managed via shellNav which dynamically loads available modules. src/lib/components/AppSidebar.svelte:14

Entity List Table

The primary data grid component used for displaying, filtering, and managing records (Entities). It is a highly composable system that supports multiple view modes (Table, Cards, List).

Implementation: EntityListTable.svelte src/lib/components/entity-list-table/EntityListTable.svelte:1-42
Composables: Logic is split into specialized runes like useRowActions, useSelection, and useExport. src/lib/components/entity-list-table/EntityListTable.svelte:44-64

Impact Level

A taxonomy used to categorize application errors and determine their UI representation (e.g., Toast vs. Dialog vs. Sidebar entry).

Levels: CRITICAL, HIGH, MEDIUM, LOW. src/lib/errors/app-errors.ts
Usage: pushImpactError is the primary entry point for reporting categorized issues. src/lib/components/AppSidebar.svelte:62-73

RFC 7807 (Problem Details)

The standard used by the backend to communicate machine-readable error details. The frontend parses these into a specific RFC7807Error type to provide granular feedback (e.g., field-level validation errors).

Structure: Includes type, title, status, detail, and instance. src/lib/errors/rfc7807.ts
Integration: Handled via pushRFC7807Error. src/lib/components/entity-list-table/EntityListTable.svelte:22

Technical Abbreviations & Terms

Term	Definition	Code Pointer
Runes	Svelte 5's new reactivity primitives (`$state`, `$derived`, `$props`).	AGENTS.md:12-25
IDP	Identity Provider. Refers to the external system managing user authentication.	src/lib/i18n/messages/en-GB.json:175-185
Audit Box	UI component showing metadata about record creation, updates, and deletion.	src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte
Delta	The difference between two versions of a record in the audit log.	src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:165-178
Sheet	A global side-panel (overlay) used for complex forms or details without navigating.	src/lib/shell/sheets/sheet-manager.svelte.ts

Architecture Diagrams

From Concept to Code: Error Handling

This diagram bridges the natural language concept of "Reporting an Error" to the specific code entities involved in the data flow.

Code
graph TD
    subgraph "Natural Language Space"
        A["Network Failure"]
        B["Validation Error"]
    end

    subgraph "Code Entity Space"
        C["apiFetch"] 
        D["pushRFC7807Error"]
        E["pushImpactError"]
        F["appErrors (Store)"]
        G["ErrorsPanel.svelte"]
        H["toast (svelte-sonner)"]
    end

    A --> C
    C -- "400/422" --> D
    C -- "500/Timeout" --> E
    B --> D
    D --> F
    E --> F
    F --> G
    E -- "if toast: true" --> H

Sources: src/lib/api.ts, src/lib/errors/app-errors.ts, src/lib/components/AppSidebar.svelte:55-83

From Concept to Code: Health Monitoring

Mapping the "System Health" concept to the reactive monitoring loop in the code.

Code
graph LR
    subgraph "Natural Language Space"
        "Is Backend Up?"
        "Is Database Down?"
    end

    subgraph "Code Entity Space"
        P["probeHealth()"]
        BS["backendState (Runes)"]
        HC["HealthChip (UI)"]
        AF["apiFetch (Middleware)"]
    end

    P --> BS
    AF -- "on 503/Gateway Error" --> BS
    BS --> HC
    HC -- "Displays" --> "shell.health.beOffline"

Sources: src/lib/backend-availability.svelte.ts, src/lib/components/AppSidebar.svelte:121-123, src/lib/components/AppSidebar.svelte:144-166

Entity-Specific Glossary

Version History

The audit trail system for entities.

Audit Action: The type of change (CREATE, UPDATE, DELETE, RESTORE). src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:102-116
Audit Delta: A Record containing old and new values for changed fields. src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:165-178

Internationalization (i18n)

Locale Files: JSON files in src/lib/i18n/messages/ containing namespaced keys. src/lib/i18n/messages/en-GB.json
$t Rune: A reactive translation function that updates UI when the language changes. src/lib/components/entity-list-table/EntityListTable.svelte:4

Shell Components

Command Palette: A searchable interface for quick actions (Cmd+K). src/lib/i18n/messages/en-GB.json:115-128
Organization Switcher: A dropdown in the sidebar for switching between tenant contexts. src/lib/components/AppSidebar.svelte:45-50

Sources: src/lib/i18n/messages/en-GB.json, src/lib/components/AppSidebar.svelte, src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte

Last modified on July 13, 2026

Global Side Sheet System Internationalization (i18n)