Copy page

Frontend

Overview

Overview

Relevant source files

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

• .githooks/pre-commit
• .windsurfintructions
• AGENTS.md
• README.md
• docs/ai/README.md
• docs/ai/SKILLS.md
• docs/ai/patterns.md
• docs/gitflow.md
• package.json
• scripts/version-sync.mjs
• src/lib/api-types.ts
• src/lib/api.ts
• src/lib/app-connectivity-events.ts
• src/lib/backend-availability.svelte.ts
• src/lib/components/AppShell.svelte
• src/lib/components/AppSidebar.svelte
• src/routes/login/+page.svelte
• vite.config.ts

Primebrick Frontend is a modern backoffice application built with SvelteKit and Svelte 5. It serves as the administrative interface for the Primebrick ecosystem, providing a high-performance, reactive shell for managing entities, customers, and system configurations.

The architecture emphasizes a "Backoffice Shell" concept, where a central AppShell manages global concerns like authentication, connectivity health, and navigation, while domain-specific modules are loaded within a consistent UI framework.

Tech Stack

The project leverages a cutting-edge frontend stack:

Technology	Role
Svelte 5	Core framework using Runes ($state, $derived, $props) for fine-grained reactivity AGENTS.md:12-25.
SvelteKit	Meta-framework for routing, SSR, and build orchestration package.json:21.
TypeScript	Static typing across the entire codebase package.json:42.
TailwindCSS 4	Utility-first styling with a modern CSS-variable-based theme package.json:40.
Shadcn-Svelte	Vendored UI primitives located in src/lib/components/ui README.md:38-39.

High-Level Component Relationship

The following diagram illustrates how the core UI entities relate to the underlying Svelte 5 logic and the API layer.

UI to Code Entity Mapping

Code
graph TD
    subgraph "Natural Language Space"
        A["Global Layout"]
        B["Navigation Sidebar"]
        C["Connectivity Status"]
        D["API Requests"]
    end

    subgraph "Code Entity Space"
        A --- AppShell["src/lib/components/AppShell.svelte"]
        B --- AppSidebar["src/lib/components/AppSidebar.svelte"]
        C --- backendState["src/lib/backend-availability.svelte.ts"]
        D --- apiFetch["src/lib/api.ts"]
    end

    AppShell --> AppSidebar
    AppSidebar --> backendState
    apiFetch --> backendState

Sources: src/lib/components/AppShell.svelte:5-14, src/lib/components/AppSidebar.svelte:10-18, src/lib/api.ts:1-3

Core Subsystems

1. The Backoffice Shell

The application is wrapped in AppShell.svelte, which acts as the root layout src/lib/components/AppShell.svelte:1-16. It coordinates:

• Connectivity Monitoring: Periodically probes the /api/v1/health endpoint to update the global backendState src/lib/backend-availability.svelte.ts:125-169.
• Global Error Boundary: Listens for unhandled rejections and window errors to display them in the ErrorsPanel src/lib/components/AppShell.svelte:26-45.
• Module Navigation: Manages the loading state of the sidebar navigation via shellNav src/lib/components/AppSidebar.svelte:14.

2. API & Authentication

All backend communication flows through apiFetch, a wrapper around the native fetch API src/lib/api.ts:139. It handles:

• SSR URL Rewriting: Automatically prepends PUBLIC_API_ORIGIN when executing on the server src/lib/api.ts:142-145.
• Auth Lifecycle: Manages 401 Unauthorized responses by attempting a token refresh or redirecting to /login src/lib/api.ts:177-210.
• Error Mapping: Automatically parses RFC 7807 "Problem Details" from the backend to populate global error stores src/lib/api.ts:122-137.

3. Entity Management

The frontend is designed to handle complex data grids and forms efficiently.

• Entity List Table: A highly composable data grid system used for customers, users, and organizations.
• Form Architecture: Utilizes sveltekit-superforms in SPA mode for client-side validation and submission src/routes/login/+page.svelte:42-47.

System Subsystem Relationship

Code
graph LR
    subgraph "Core Infrastructure"
        API["apiFetch (api.ts)"]
        Health["probeHealth (backend-availability.svelte.ts)"]
        Auth["userProfileStore (user-profile-store.svelte.ts)"]
    end

    subgraph "UI Shell"
        Shell["AppShell.svelte"]
        Sidebar["AppSidebar.svelte"]
        Sheet["SheetHost.svelte"]
    end

    subgraph "Domain Modules"
        Customers["/customers"]
        Settings["/system/settings"]
    end

    Shell --> Sidebar
    Shell --> Sheet
    Sidebar --> Health
    API --> Health
    Customers --> API
    Settings --> Auth

Sources: src/lib/components/AppShell.svelte:5-14, src/lib/api.ts:139-150, src/lib/backend-availability.svelte.ts:19-30

---

Child Pages

For deeper technical details, please refer to the following sections:

1.1. Getting Started

Developer onboarding: prerequisites, pnpm workspace setup, running the dev server, environment variables, and the Vite proxy for /api.

• Key files: package.json, vite.config.ts.

1.2. Project Structure

Walkthrough of the directory layout, including the separation between UI primitives (src/lib/components/ui/*) and domain components.

• Key files: src/routes/, src/lib/.

1.3. Development Conventions & AI Agent Rules

Mandatory coding standards for Svelte 5 Runes and specific instructions for AI agents regarding GitFlow and file operations.

• Key files: AGENTS.md, docs/gitflow.md, .windsurfintructions.

---