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

# Repository structure

> How the MUZE monorepo is organized

MUZE is a monorepo with two primary directories, `backend/` and `frontend/`. The shared Prisma schema in `backend/prisma/` is the single source of truth for the data model.

## Top-level layout

```
Muze Uniform Solutions/
├── backend/                  # NestJS API (port 3001)
│   ├── src/
│   │   ├── main.ts           # Bootstrap: helmet, cors, ValidationPipe, global filters
│   │   ├── app.module.ts     # Root module, imports all feature modules
│   │   ├── auth/             # Session/permissions/scope guards, permission registry
│   │   ├── prisma/           # PrismaModule (global) + PrismaService
│   │   ├── config/           # Zod env validation, CORS origins
│   │   ├── filters/          # Prisma + HTTP exception filters
│   │   ├── clients/          # Client CRUD
│   │   ├── regions/          # Region CRUD
│   │   ├── departments/      # Department CRUD
│   │   ├── stores/           # Store CRUD + bulk CSV import
│   │   ├── catalog/          # Uniform categories + products
│   │   ├── employees/        # Employee management + CSV import
│   │   ├── entitlements/     # Entitlement engine, rule sets, CSV import
│   │   ├── orders/           # Order lifecycle, approvals, status transitions
│   │   ├── notifications/    # In-app notifications + email service
│   │   ├── reports/          # Spend, replacement-due, production reports
│   │   ├── users/            # Staff accounts + role assignment
│   │   ├── audit-logs/       # Audit trail
│   │   └── system-settings/  # System-wide settings
│   ├── prisma/
│   │   ├── schema.prisma     # Data model (SOURCE OF TRUTH)
│   │   └── migrations/       # Prisma migrations
│   ├── render.yaml           # Render deployment config
│   └── package.json
│
├── frontend/                 # React SPA (Vite)
│   ├── src/
│   │   ├── main.tsx          # Providers + router mount
│   │   ├── App.tsx           # Route tree, lazy loading, route guards, error boundaries
│   │   ├── index.css         # Brand tokens, Tailwind, motion vocabulary
│   │   ├── lib/              # api.ts, auth-client.ts, domain-types.ts, status.ts, seo.ts, constants.ts
│   │   ├── hooks/            # use-auth, use-active-client, use-permissions, use-document-title, ...
│   │   ├── components/       # ui/ (shadcn), common/, layout/, admin/, manager/, orders/
│   │   ├── pages/            # login, dashboard, profile, notifications + admin/, manager/
│   │   └── types/            # Shared TypeScript types
│   ├── scripts/              # Build-time generators (e.g. robots.txt + sitemap.xml)
│   ├── e2e/                  # Playwright E2E suite
│   └── package.json
│
├── .agents/                  # AI agent skill definitions
└── docs-site/                # Documentation sites (Mintlify)
    ├── docs/                 # User guide
    └── architecture/         # Architecture docs (this site)
```

## Backend modules

| Module                 | Purpose                            | Key service                                                     |
| ---------------------- | ---------------------------------- | --------------------------------------------------------------- |
| `PrismaModule`         | Global DB access                   | `PrismaService`                                                 |
| `AuthModule`           | Guards + auth handlers             | `AuthService`, `SessionGuard`, `PermissionsGuard`, `ScopeGuard` |
| `UsersModule`          | Staff accounts, roles, invitations | `UsersService`                                                  |
| `ClientsModule`        | Client CRUD                        | `ClientsService`                                                |
| `RegionsModule`        | Region CRUD                        | `RegionsService`                                                |
| `DepartmentsModule`    | Department CRUD                    | `DepartmentsService`                                            |
| `StoresModule`         | Store CRUD + bulk import           | `StoresService`                                                 |
| `CatalogModule`        | Uniform categories + products      | `CatalogService`                                                |
| `EmployeesModule`      | Employee management + CSV import   | `EmployeesService`                                              |
| `EntitlementsModule`   | Entitlement engine + rule sets     | `EntitlementEngineService`, `RuleSetsService`                   |
| `OrdersModule`         | Order lifecycle + approvals        | `OrdersService`                                                 |
| `NotificationsModule`  | In-app + email notifications       | `NotificationsService`, `EmailService`                          |
| `ReportsModule`        | Reporting engine                   | `ReportsService`                                                |
| `AuditLogsModule`      | Audit trail                        | `AuditLogsService`                                              |
| `SystemSettingsModule` | System settings                    | `SystemSettingsService`                                         |
| `HealthModule`         | Readiness check                    | `HealthController`                                              |

## Frontend pages

All route-level pages are lazy-loaded via `React.lazy()` in `App.tsx` for code splitting. Admin pages live in `pages/admin/`, Store Manager pages in `pages/manager/`, and shared pages (login, dashboard, notifications, profile) at the top level. See [Frontend architecture](/engineering/frontend-architecture) for the routing and state patterns.