# Project Structure # Project Structure
Relevant source files The following files were used as context for generating this wiki page: - [.windsurfintructions](.windsurfintructions) - [AGENTS.md](AGENTS.md) - [README.md](README.md) - [components.json](components.json) - [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) - [postcss.config.js](postcss.config.js) - [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/ui/input-group/input-group-addon.svelte](src/lib/components/ui/input-group/input-group-addon.svelte) - [src/lib/components/ui/input-group/input-group-button.svelte](src/lib/components/ui/input-group/input-group-button.svelte) - [src/lib/components/ui/input-group/input-group-input.svelte](src/lib/components/ui/input-group/input-group-input.svelte) - [src/lib/components/ui/input-group/input-group-text.svelte](src/lib/components/ui/input-group/input-group-text.svelte) - [src/lib/components/ui/input-group/input-group-textarea.svelte](src/lib/components/ui/input-group/input-group-textarea.svelte) - [src/lib/components/ui/input-group/input-group.svelte](src/lib/components/ui/input-group/input-group.svelte) - [src/lib/components/ui/textarea/index.ts](src/lib/components/ui/textarea/index.ts)
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 and Module Loading 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: 1. **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](). 2. **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** ```mermaid 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** ```mermaid 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]() ---