# Overview # Overview
Relevant source files The following files were used as context for generating this wiki page: - [.githooks/pre-commit](.githooks/pre-commit) - [.windsurfintructions](.windsurfintructions) - [AGENTS.md](AGENTS.md) - [README.md](README.md) - [docs/ai/README.md](docs/ai/README.md) - [docs/ai/SKILLS.md](docs/ai/SKILLS.md) - [docs/ai/patterns.md](docs/ai/patterns.md) - [docs/gitflow.md](docs/gitflow.md) - [package.json](package.json) - [scripts/version-sync.mjs](scripts/version-sync.mjs) - [src/lib/api-types.ts](src/lib/api-types.ts) - [src/lib/api.ts](src/lib/api.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/routes/login/+page.svelte](src/routes/login/+page.svelte) - [vite.config.ts](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** ```mermaid 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** ```mermaid 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`. ---