Architecture overview

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

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 for the people and external systems around MUZE
Core concepts for the domain model every subsystem shares
System overview for the request lifecycle
Technology stack for the full library inventory

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Architecture at a glance

Key design principles

What MUZE is not

Where to next

​Architecture at a glance

​Key design principles

​What MUZE is not

​Where to next

Architecture at a glance

Key design principles

What MUZE is not

Where to next