# Application Routes & Modules

# Application Routes & Modules

<details>
<summary>Relevant source files</summary>

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

- [src/lib/entity-list/sheets/panels/FiltersPanel.svelte](src/lib/entity-list/sheets/panels/FiltersPanel.svelte)
- [src/lib/entity-list/types.ts](src/lib/entity-list/types.ts)
- [src/lib/i18n/date-format.ts](src/lib/i18n/date-format.ts)
- [src/lib/user-profile-store.svelte.ts](src/lib/user-profile-store.svelte.ts)
- [src/routes/(app)/+layout.svelte](src/routes/(app)/+layout.svelte)
- [src/routes/(app)/crm/pipeline/+page.svelte](src/routes/(app)/crm/pipeline/+page.svelte)
- [src/routes/(app)/customers/+page.svelte](src/routes/(app)/customers/+page.svelte)
- [src/routes/(app)/system/settings/+page.svelte](src/routes/(app)/system/settings/+page.svelte)
- [src/routes/(app)/system/settings/profile/+page.svelte](src/routes/(app)/system/settings/profile/+page.svelte)
- [src/routes/(app)/system/settings/security/+page.svelte](src/routes/(app)/system/settings/security/+page.svelte)

</details>



The application's functional surface is organized under the SvelteKit route group `src/routes/(app)`. This group shares the `AppShell` layout and provides the primary business modules of the Backoffice, including Customer Relationship Management (CRM) and System Administration.

## Module Structure Overview

The frontend routes are logically partitioned into domain-specific modules. Navigation between these modules is managed by the `shellNav` state, which coordinates the sidebar and topbar content based on the active route.

| Route Group | Description | Primary Components |
|:---|:---|:---|
| `/customers` | Customer lifecycle management and CRM entity lists. | `EntityListTable`, `FiltersPanel` |
| `/crm/pipeline` | Visual sales pipeline and opportunity tracking (Placeholder). | `AppPageScaffold` |
| `/system/settings` | User profile, security, and administrative configurations. | `FormPageLayout`, `userProfileStore` |

### Route Entity Mapping

The following diagram illustrates how SvelteKit routes map to domain entities and their respective UI controllers.

```mermaid
graph TD
    subgraph "Natural Language Space"
        CustomerList["Customer Management"]
        Settings["User & System Settings"]
        Pipeline["CRM Pipeline"]
    end

    subgraph "Code Entity Space"
        RouteCustomers["src/routes/(app)/customers/+page.svelte"]
        RouteSettings["src/routes/(app)/system/settings/"]
        RoutePipeline["src/routes/(app)/crm/pipeline/+page.svelte"]
        
        MetaCache["globalThis.__pbCustomerMetaCache"]
        ProfileStore["userProfileStore"]
        
        EntityTable["EntityListTable.svelte"]
    end

    CustomerList --> RouteCustomers
    RouteCustomers --> MetaCache
    RouteCustomers --> EntityTable

    Settings --> RouteSettings
    RouteSettings --> ProfileStore

    Pipeline --> RoutePipeline
```
Sources: [src/routes/(app)/customers/+page.svelte:1-28](), [src/routes/(app)/system/settings/+page.svelte:1-5](), [src/lib/user-profile-store.svelte.ts:41-56](), [src/lib/shell/modules-shell.svelte:1-20]()

## Customer List & CRM

The `/customers` route is the primary implementation of the `EntityListTable` pattern for high-volume data. It features a robust metadata caching strategy to minimize API overhead and uses `sessionStorage` to persist user UI preferences like column visibility and sort order.

Key features include:
- **Metadata Caching**: Uses `globalThis.__pbCustomerMetaCache` to store `CustomerMeta` across HMR and component remounts [src/routes/(app)/customers/+page.svelte:149-163]().
- **Advanced Filtering**: Integration with `FiltersPanel.svelte` supporting complex `AND/OR` logic and `BETWEEN` operators for dates [src/lib/entity-list/sheets/panels/FiltersPanel.svelte:74-85]().
- **State Persistence**: Syncs `visibleKeys`, `sortKey`, and `searchInKeys` to `sessionStorage` [src/routes/(app)/customers/+page.svelte:107-111]().

For implementation details on metadata lifecycle and filter normalization, see **[Customer List & CRM](#6.1)**.

Sources: [src/routes/(app)/customers/+page.svelte:149-179](), [src/lib/entity-list/sheets/panels/FiltersPanel.svelte:132-165]()

## System Settings

The `/system/settings` area is a collection of forms and lists for managing the application environment and user identity. It uses a 307 redirect at the root to land users on the Profile section [src/routes/(app)/system/settings/+page.svelte:4-4]().

### Administrative Sub-sections
- **Profile**: Manages user-specific data (display name, avatar) via `userProfileStore` [src/lib/user-profile-store.svelte.ts:45-56]().
- **Security**: Handles password updates and OpenID Connect (OIDC) configuration [src/routes/(app)/system/settings/security/+page.svelte:108-144]().
- **Organizations & Users**: Management of multi-tenant entities and user access.
- **Modules & Templates**: Administrative tools for system extensibility and document generation.

For details on form validation, avatar generation, and security audit logs, see **[System Settings](#6.2)**.

Sources: [src/routes/(app)/system/settings/+page.svelte:1-5](), [src/lib/user-profile-store.svelte.ts:1-74](), [src/routes/(app)/system/settings/security/+page.svelte:1-62]()

## Data Flow: Route to Store

The relationship between the route lifecycle and the global application state is centered around reactive stores that sync with the backend.

```mermaid
sequenceDiagram
    participant R as SvelteKit Route
    participant S as userProfileStore
    participant A as API (/api/v1/auth/me)
    participant B as Browser Storage

    R->>S: Mounts (onMount)
    S->>B: loadFromStorage()
    R->>A: apiFetch() bootstrap
    A-->>R: UserProfile Data
    R->>S: set(profile)
    S->>B: sessionStorage.setItem('user')
    S-->>R: Reactive $state update
```
Sources: [src/routes/(app)/+layout.svelte:10-42](), [src/lib/user-profile-store.svelte.ts:32-56]()

---