Copy page

Frontend

Customer List & CRM

Customer List & CRM

Relevant source files

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

• src/lib/entity-list/sheets/panels/FiltersPanel.svelte
• src/lib/entity-list/types.ts
• src/lib/i18n/date-format.ts
• src/routes/(app)/crm/pipeline/+page.svelte
• src/routes/(app)/customers/+page.svelte

The Customer List and CRM module provides the primary interface for managing customer entities and tracking sales pipelines. It leverages the EntityListTable architecture for high-performance data grids, featuring advanced server-side filtering, metadata-driven UI configuration, and robust state persistence.

Customer List Architecture

The /customers route is a specialized implementation of the entity list pattern. It manages the lifecycle of customer data from metadata retrieval to paginated row loading.

Lifecycle and Data Flow

The route follows a strict loading sequence: loadMeta (UI configuration) followed by loadRows (data).

1. Metadata Caching: To prevent redundant API calls during navigation or HMR, customer metadata is cached in globalThis.__pbCustomerMetaCache src/routes/(app)/customers/+page.svelte:149-163.
2. State Restoration: Upon mounting, the component restores visibleKeys, sortKey, and searchInKeys from sessionStorage src/routes/(app)/customers/+page.svelte:107-111.
3. Connectivity Recovery: The route listens for onConnectivityRestored events to automatically refresh data after a network outage src/routes/(app)/customers/+page.svelte:273-276.

Metadata and Row Lifecycle

The following diagram illustrates the initialization and data fetching sequence for the Customer List.

Customer List Initialization Sequence

Code
sequenceDiagram
    participant B as Browser/User
    participant C as CustomerPage
    participant G as globalThis Cache
    participant A as API (/api/v1/customers)

    B->>C: Mount /customers
    C->>G: getMetaCache()
    alt Cache Miss
        C->>A: GET /meta
        A-->>C: CustomerMeta
        C->>G: setMetaCache(meta)
    else Cache Hit
        G-->>C: CustomerMeta
    end
    C->>C: restoreSessionState()
    C->>C: ensureVisibleKeys()
    C->>A: GET /rows (params: page, sort, filters)
    A-->>C: ListResponse (rows, total)
    C->>C: Update $state(rows)

Sources: src/routes/(app)/customers/+page.svelte:165-244, src/routes/(app)/customers/+page.svelte:149-163, src/routes/(app)/customers/+page.svelte:107-111

---

Filtering and Search

The module supports three layers of data restriction: global search, standard filters, and advanced logical filters.

Search Implementation

• Search Syntax: Supports wildcard tokens and field-specific overrides.
• Debouncing: Search input is debounced via a searchTimer to prevent excessive API requests while typing src/routes/(app)/customers/+page.svelte:73-73.
• Search In Keys: Users can restrict the search to specific columns, persisted in sessionStorage src/routes/(app)/customers/+page.svelte:99-109.

Advanced Filters

The FiltersPanel provides a UI for complex queries using AND/OR connectors and various operators (e.g., BETWEEN, contains, startsWith) src/lib/entity-list/types.ts:136-146.

Operator	Applicable Types	Description
= / !=	All	Exact match or inequality
contains	text	Substring search
BETWEEN	date, datetime	Range selection
> / <	date, datetime, number	Comparison operators

Sources: src/lib/entity-list/sheets/panels/FiltersPanel.svelte:74-85, src/lib/entity-list/types.ts:157-170

---

Connectivity & Error Handling

The Customer List is designed for resilience, handling backend unavailability through the AppError system.

• RFC 7807 Handling: API errors are parsed into Problem Details objects. If a fetch fails due to a database being unavailable (ApiDatabaseUnavailableError) or the server being unreachable (ApiUnreachableError), a pushImpactError is triggered with a HIGH impact level src/routes/(app)/customers/+page.svelte:18-19.
• Automatic Retry: When the onConnectivityRestored event fires (managed by the AppShell health probe), the page automatically invokes loadRows() to refresh the UI src/routes/(app)/customers/+page.svelte:273-276.

Entity State to Code Mapping

Code
graph TD
    subgraph "Natural Language Space"
        Error["Connection Lost"]
        Retry["Auto Refresh"]
        Meta["UI Config"]
    end

    subgraph "Code Entity Space"
        ApiErr["ApiUnreachableError"]
        ConnRest["onConnectivityRestored"]
        MetaCache["__pbCustomerMetaCache"]
        PushErr["pushImpactError"]
    end

    Error --> ApiErr
    ApiErr --> PushErr
    ConnRest --> Retry
    MetaCache --> Meta

Sources: src/routes/(app)/customers/+page.svelte:18-20, src/lib/app-connectivity-events.ts, src/lib/errors/app-errors.ts

---

Date and Time Localization

The customer list handles complex timezone scenarios, particularly for datetime columns.

• IANA Toggling: Users can toggle between browser (local) and record (stored IANA) timezones for datetime columns src/routes/(app)/customers/+page.svelte:104-105.
• Formatting Pipeline: Raw values are passed through formatListCellValue, which utilizes Intl.DateTimeFormat cached by locale tag and timezone src/lib/i18n/date-format.ts:102-121.
• UTC Normalization: When applying date filters, values are converted to UTC ISO strings before being sent to the API, ensuring server-side consistency src/lib/entity-list/sheets/panels/FiltersPanel.svelte:142-145.

Sources: src/lib/i18n/date-format.ts:4-7, src/lib/i18n/date-format.ts:102-121, src/lib/entity-list/sheets/panels/FiltersPanel.svelte:134-162

---

CRM Pipeline

The CRM Pipeline (/crm/pipeline) serves as a placeholder for the upcoming sales management features.

• Structure: Uses AppPageScaffold and AppPageBreadcrumb for shell consistency src/routes/(app)/crm/pipeline/+page.svelte:10-24.
• Navigation: Integrates with shellNav.modules via the crmModuleMenuSegment to provide contextual breadcrumbs src/routes/(app)/crm/pipeline/+page.svelte:15-20.
• Content: Currently displays static information regarding lead tracking and pipeline stages as defined in the i18n bundles src/routes/(app)/crm/pipeline/+page.svelte:26-40.

Sources: src/routes/(app)/crm/pipeline/+page.svelte:1-42, src/lib/breadcrumb/crm-breadcrumb.ts

---