Backend architecture

Bootstrap sequence

The application starts in main.ts:

Global middleware stack

Applied in order in main.ts:

Order	Middleware	Purpose
1	`express.json({ limit: '20mb' })`	Parse JSON bodies, up to 20MB for large imports
2	`compression()`	gzip all responses; reduces report payloads by roughly 90%
3	`helmet()`	HTTP security headers (CSP disabled for SPA compatibility)
4	`cookie-parser`	Parse cookies for better-auth session tokens
5	`cors()`	Allow cross-origin requests from `FRONTEND_ORIGIN` with credentials
6	`ValidationPipe`	Validate and strip all DTOs

Global exception filters

Two filters are registered globally in main.ts.

PrismaExceptionFilter

Catches Prisma.PrismaClientKnownRequestError and maps Prisma error codes to semantic HTTP responses:

Prisma code	HTTP status	Meaning
`P2002`	409 Conflict	Unique constraint violation
`P2003`	400 Bad Request	Foreign key constraint failure
`P2025`	404 Not Found	Record not found for update/delete
`P2034`	409 Conflict	Transaction conflict / serialization failure
Other	400 Bad Request	Generic database error

The filter humanizes constraint names (for example Order_submittedById_fkey becomes “order”) for user-facing messages.

HttpExceptionFilter

Catch-all filter. Passes NestJS HttpException subclasses through with their original status codes. Any unknown error is logged and returned as a sanitized 500:

{
  "statusCode": 500,
  "message": "An internal server error occurred.",
  "error": "Internal Server Error"
}

No stack traces or internal details reach the client.

Authorization stack

Every request passes through three guards registered by the global AuthModule: The guards’ configuration and internals are documented in Authorization.

Rate limiting

Configured via @nestjs/throttler:

ThrottlerModule.forRoot([{
  ttl: 60_000,      // 60 seconds
  limit: 100,       // 100 requests per ttl window
}])

Applied globally with no per-route overrides. Bulk operations use single batched requests instead of N individual calls precisely so large selections stay under this limit.

Request timeout

Set to 15 minutes in main.ts:

httpServer.requestTimeout = 15 * 60_000;

This accommodates large report generation and CSV imports.

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Bootstrap sequence

Global middleware stack

Global exception filters

PrismaExceptionFilter

HttpExceptionFilter

Authorization stack

Rate limiting

Request timeout

​Bootstrap sequence

​Global middleware stack

​Global exception filters

​PrismaExceptionFilter

​HttpExceptionFilter

​Authorization stack

​Rate limiting

​Request timeout

Bootstrap sequence

Global middleware stack

Global exception filters

PrismaExceptionFilter

HttpExceptionFilter

Authorization stack

Rate limiting

Request timeout