> ## 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.

# Reporting

> Report generation for store spend, replacement tracking, and production

## Report types

MUZE generates three core reports, all served through the NestJS backend:

| Report                   | Endpoint                              | Description                                              |
| ------------------------ | ------------------------------------- | -------------------------------------------------------- |
| Store and regional spend | `GET /api/v1/reports/store-ops`       | Per-store uniform spending with company/employee splits  |
| Replacement due          | `GET /api/v1/reports/replacement-due` | Employees approaching or past replacement boundaries     |
| Production requirements  | `GET /api/v1/reports/production`      | Manufacturing requirements from active production orders |

User-facing descriptions of each report live in the [user guide](https://doc.muzemus.online/reports/overview). This page covers how reports are generated.

## Report architecture

```mermaid theme={null}
flowchart LR
    A[Frontend report page] -->|API request| B[NestJS controller]
    B -->|Service call| C[ReportsService]
    C -->|SQL query| D[PostgreSQL]
    D -->|Result set| C
    C -->|Formatted data| B
    B -->|JSON response| A
    A -->|Client-side| E[Recharts visualization]
    A -->|Client-side| F[SheetJS CSV export]
```

The replacement-due report reuses `computeEntitlementPhase()` from the entitlement engine, so report data and order-time eligibility always agree on phase and cycle boundaries.

## Export

| Format     | Implementation      | Notes                                                                      |
| ---------- | ------------------- | -------------------------------------------------------------------------- |
| CSV        | SheetJS client-side | Instant download, no server load; large datasets limited by browser memory |
| ZIP bundle | adm-zip server-side | CSV + PDF bundles for bulk downloads                                       |
| PDF        | pdf-lib server-side | Generated on request                                                       |

## Permission scoping

| Role                       | Report visibility                             |
| -------------------------- | --------------------------------------------- |
| STORE\_MANAGER             | Replacement-due for their store               |
| HR                         | Spend and replacement-due across their client |
| MUZE\_ADMIN / SUPER\_ADMIN | All reports, all clients                      |

The production requirements report is admin-only by permission (`reports.production`).