Backend Architecture

Goal

Build a clean, maintainable NestJS backend with consistent patterns that scales with the team and codebase.

Three-Layer Architecture

Controllers → Services (optional) → Repositories → Database

Layer	Purpose	When to Use
Controllers	HTTP handling, validation, routing	Always
Services	Business logic, orchestration	When logic needed
Repositories	Database access via Prisma	Always

Two Patterns

Simple Pattern: Controller → Repository

Use for straightforward CRUD without business logic.

Full Pattern: Controller → Service → Repository

Use when you need:

Business rules or validation beyond DTOs
Multiple database operations
External service calls
Background jobs (BullMQ)

Default: Start simple, add service layer when complexity grows.

Project Structure

src/
├── modules/           # Feature modules
│   ├── employees/
│   │   ├── employees.controller.ts
│   │   ├── employees.service.ts    # Optional
│   │   ├── employees.repository.ts
│   │   └── dto/
│   ├── time-off/
│   ├── documents/
│   └── ...
├── common/            # Shared utilities
│   ├── guards/
│   ├── decorators/
│   └── pipes/
└── main.ts

Required NestJS Features

Feature	Why Required
TenantGuard	Security - validates tenant context from x-tenant-id header (MVP uses Auth.js sessions, not JWT)
ValidationPipe	Validate all DTOs automatically (configured globally in main.ts)
ParseIntPipe	Type-safe route parameters

Optional Features (Use When Needed)

Interceptors - Logging, response transforms, timeouts
Custom Pipes - Complex data transformations
Exception Filters - Custom error formatting

NOT Used

EventEmitter - Use BullMQ for background jobs instead
Complex patterns (CQRS, Event Sourcing) - Keep it simple

Key Principles

Tenant Isolation

Every repository method takes tenantId as first parameter
Every query filters by tenantId
Never expose data across tenants

Data Access Policy

API-First: All frontend data fetching must go through the API (apps/api).
Auth Exception: The ONLY exception is apps/web connecting to the database for Auth.js (NextAuth). This is due to library limitations.