Client isolation

Tenancy model

MUZE is a shared-database, row-level multi-tenant system. All clients (for example Boxer, Clicks) share the same PostgreSQL database and the same application instance. Tenant isolation is enforced at the application layer: tenant-owned queries include a role/store scope, a clientId filter, or both. There is no database-level row-level security (RLS) and no separate schemas or databases per client. MUZE enforces boundaries at two levels:

URL level: ScopeGuard verifies the user can access the entity referenced in the URL
Query level: service methods filter database queries to the user’s scope

The query level is not automated; it is enforced by convention in each service and covered by code review. See Data scoping for the implementation patterns.

How client scoping works

Every tenant-scoped model includes a clientId foreign key:

model Store {
  id       String @id @default(cuid())
  name     String
  clientId String
  client   Client @relation(fields: [clientId], references: [id])

  @@index([clientId])
}

When a request arrives, the authorization layer resolves the user’s scope from their UserRole record. Every subsequent database query filters by it.

Role	Scope source	Data visibility
SUPER_ADMIN	Bypasses scope checks	All clients
MUZE_ADMIN	Bypasses scope checks; `clientId` param may narrow	All clients
HR	`userRole.clientId`	One assigned client
STORE_MANAGER	`userRole.storeId`	One assigned store
EMPLOYEE	No API access	None

For Muze Admin and Super Admin, the global client selector supplies an optional clientId to client-scoped APIs. The resolver treats it as a narrowing filter and never replaces the caller’s role or store scope. Aggregate manager order, approval, and employee views use this filter. Their React Query keys also include the active client, and they do not reuse rows from the previous client while the new request is loading.

Tenant-scoped models

Model	Scoping
`Region`, `Department`, `Store`, `UniformCategory`, `Product`	Direct `clientId`
`EntitlementRuleSet`	Direct `clientId`
`Employee`	Via store
`Order`, `StoreOrder`	Via store/employee

User, UserRole, and Session are global: a user can hold roles across clients.

What each role can and cannot see

An HR user is assigned to exactly one client and can see:

All stores within their client
All employees in their client’s stores
All orders from their client’s employees
All entitlement rule sets for their client

They cannot see data from other clients, even though it exists in the same tables. A Store Manager is assigned to exactly one store and can see their store’s employees and orders. They cannot see other stores’ data, even within the same client.

Potential risks and mitigations

Risk	Mitigation
Forgotten clientId filter	`ScopeGuard` catches URL-level violations; service-layer filters are convention-based and covered by code review
Admin accidentally over-scoping	Service methods check `request.isAdmin` before applying or relaxing clientId filters
Cross-client data in reports	Reports resolve the client from the user’s roles before generating any query
CSV import across clients	Imports are scoped to the importer’s client; every imported row is assigned to it

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Tenancy model

How client scoping works

Tenant-scoped models

What each role can and cannot see

Potential risks and mitigations

​Tenancy model

​How client scoping works

​Tenant-scoped models

​What each role can and cannot see

​Potential risks and mitigations

Tenancy model

How client scoping works

Tenant-scoped models

What each role can and cannot see

Potential risks and mitigations