> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Data flow

> How data moves through the system from user action to database and back

## Order creation flow (primary use case)

The most complex data flow in MUZE is order creation. It touches every tier:

```mermaid theme={null}
sequenceDiagram
    actor SM as Store Manager / HR
    participant FE as React SPA
    participant API as NestJS API
    participant EE as Entitlement Engine
    participant DB as PostgreSQL

    SM->>FE: Select employees, products, sizes, quantities
    FE->>FE: React Hook Form + Zod validation
    FE->>API: POST /api/v1/orders
    API->>API: SessionGuard → PermissionsGuard → ScopeGuard
    API->>API: ValidationPipe strips unknown fields
    API->>DB: BEGIN TRANSACTION, lock employee row
    API->>EE: Evaluate entitlements for each employee
    EE->>DB: Load matching rule set + entitlement period
    EE->>EE: Phase (INITIAL/REPLACEMENT) + criteria match + balance per product
    EE-->>API: Company-paid / employee-paid split per line
    API->>DB: INSERT Order + OrderItems (+ StoreOrder link)
    API->>DB: Record entitlement consumption per item
    API->>DB: COMMIT
    API-->>FE: 201 Created + order
    FE->>FE: Invalidate React Query cache
    FE-->>SM: Success toast
```

The entitlement evaluation steps are detailed in [Entitlement engine](/business-engines/entitlement-engine).

## Authentication flow

```mermaid theme={null}
sequenceDiagram
    actor User as Staff member
    participant FE as React SPA
    participant API as NestJS API
    participant BA as better-auth
    participant DB as PostgreSQL

    User->>FE: Enter email + password
    FE->>API: POST /api/auth/sign-in
    API->>BA: authService.handler (Express middleware)
    BA->>DB: SELECT user WHERE email = $1
    BA->>BA: Verify password hash
    BA->>DB: INSERT session
    BA-->>FE: Set-Cookie: better-auth session token
    FE->>FE: SessionProvider updates useSession()
```

On subsequent requests the browser sends the session cookie automatically. `SessionGuard` validates it against the `Session` table.

## Data scoping flow

Every data query resolves scope the same way:

```mermaid theme={null}
flowchart TD
    A[API request] --> B[Resolve user roles from request.auth]
    B --> C{Is admin?}
    C -->|Yes| D[No clientId filter: see all clients]
    C -->|No| E{Is HR?}
    E -->|Yes| F[Filter by assigned clientId]
    E -->|No| G{Is Store Manager?}
    G -->|Yes| H[Filter by assigned storeId]
    G -->|No| I[No access]
```

URL-level enforcement is handled by `ScopeGuard`; query-level filtering happens in each service method. The implementation patterns are in [Data scoping](/security/data-scoping).

## Client switching

For admins, the active client is application-wide state. Every client-sensitive query embeds `activeClientId` in its React Query key and sends `?clientId=` to the API, so switching clients produces a new cache identity and an automatic refetch. The `clientId` parameter can only narrow a query, never widen it (see [API design](/system-architecture/api-design)).