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

# Architecture overview

> High-level architecture of the MUZE Uniform Entitlement & Ordering System

MUZE is a staff-only B2B uniform entitlement and ordering platform. Employees do not have login accounts; only staff roles (Store Manager, HR, Muze Admin, Super Admin) authenticate.

The platform is built as a monorepo containing a NestJS backend, a React frontend, and a shared Prisma schema. It deploys as two services, a Firebase Hosting frontend and a Render backend, backed by a Neon PostgreSQL database, in two environments: **staging** (`stage.muzemus.online`) and **production** (`app.muzemus.online`). A static landing page (`muzemus.online`) and two Mintlify documentation sites (`doc.muzemus.online`, `system.muzemus.online`) complete the public surface.

## Architecture at a glance

```mermaid theme={null}
graph TB
    subgraph Client["Browser (React SPA)"]
        FE["React 19 + Vite 8<br/>shadcn/ui + Tailwind CSS v4"]
    end

    subgraph Backend["Render (NestJS API)"]
        API["NestJS + Prisma<br/>REST API /api/v1/*"]
    end

    subgraph Data["Neon PostgreSQL"]
        DB["Serverless PostgreSQL"]
    end

    subgraph External["External services"]
        R2["Cloudflare R2<br/>File storage"]
        Email["Brevo / SMTP<br/>Email delivery"]
    end

    FE -->|"HTTPS + session cookie"| API
    API -->|"Prisma Client (pooled)"| DB
    API -->|"S3-compatible PUT/GET"| R2
    API -->|"SMTP / API"| Email
```

## Key design principles

| Principle                          | What it means in MUZE                                                                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Multi-client tenancy**           | Every data-bearing row is scoped to a `clientId`. One deployment serves multiple retail clients (for example Boxer, Clicks).                     |
| **Session-based auth**             | better-auth stores sessions in the database. No JWT tokens. Cookie-based, `SameSite=None; Secure` in production for the cross-origin deployment. |
| **Capability-based authorization** | Routes declare required permissions via `@Permissions(...)`. `PermissionsGuard` resolves roles to a permission set.                              |
| **Store-scoped access**            | `ScopeGuard` ensures a Store Manager can only access their own store's data. HR can access any store within their client.                        |
| **Entitlement-driven ordering**    | Orders are validated against the employee's rule set and remaining balance at submission time.                                                   |
| **Zero self-registration**         | Portal accounts are created by Muze Admin only. Self-sign-up is disabled in better-auth.                                                         |

## What MUZE is not

* Not a public-facing e-commerce site. Employees cannot log in.
* Not a microservices architecture. It is a single NestJS application.
* No Redis, message queues, WebSockets, or SSE today.
* No per-client database isolation. All clients share one database with application-layer row scoping.

## Where to next

* [System context](/overview/system-context) for the people and external systems around MUZE
* [Core concepts](/overview/core-concepts) for the domain model every subsystem shares
* [System overview](/system-architecture/system-overview) for the request lifecycle
* [Technology stack](/overview/technology-stack) for the full library inventory