Production-minded backend foundation with secure authentication, role-based access control, user management, PostgreSQL, OpenAPI documentation, and operational tooling. Everything you need to start shipping business logic without rebuilding authentication and authorization from scratch.
Authentication
Secure user authentication with modern password hashing, JWT tokens, and protected routes out of the box.
- User registration with email, password, and display name
- Argon2id password hashing (64 MiB memory, 3 iterations, 1 parallelism)
- JWT access token generation with configurable secret and expiry
- JWT Bearer token extraction and validation via passport-jwt strategy
- JwtAuthGuard for protecting any route
- Password change with current-password verification
- Duplicate email detection with 409 Conflict
- Invalid credentials returning 401 Unauthorized
- Passwords excluded from all API responses
Role-Based Access Control (RBAC)
Built-in role-based authorization with global guards, decorators, and automatic role assignment.
- Two built-in roles — ADMIN and USER — seeded at startup
- Role entity with UUID primary key, unique name, and timestamps
- User-role junction entity with composite primary key
- Global RolesGuard checking @Roles() decorator metadata
- Route-level @Roles(...) decorator for per-endpoint access control
- ADMIN-only routes returning 403 for unauthorized users
- Routes without @Roles() allow any authenticated user
- Unauthenticated requests blocked on all protected routes
- Automatic USER role assignment on registration
- Duplicate role assignment prevention
User Management
Self-service profile management for users and paginated admin-only user listing with role enrichment.
- Current user profile endpoint — GET /api/v1/users/me
- Display name update with max-length validation
- Paginated user listing for admins with metadata
- User detail endpoint for admins with role enrichment
- Custom repository with findOneBy, findAndCount, and save
- Public service interface pattern for cross-module access
- Role enrichment from RBAC module on user responses
Database & TypeORM
PostgreSQL integration with auto-discovered entities, migration scripts, and production-safe settings.
- TypeORM with PostgreSQL via @nestjs/typeorm forRootAsync
- autoLoadEntities discovering entities from forFeature() registrations
- synchronize disabled in production, configurable via DB_SYNC env
- Standalone DataSource for CLI tools with dotenv
- Migration CLI scripts for generate, show, run, and revert
Configuration & Validation
Centralized, typed environment configuration validated at bootstrap with Joi schemas.
- Centralized .env loading via @nestjs/config
- Joi validation schema checking 12 environment variables at bootstrap
- Conditional JWT secret validation — minimum 32 characters in production
- Typed ConfigService with port, nodeEnv, database, jwt, and cors getters
- Sensible defaults for all environment variables in development
OpenAPI / Swagger
Interactive API documentation generated automatically from DTOs and controller decorators.
- Swagger UI at /api/docs via SwaggerModule.setup()
- Raw OpenAPI JSON at /api/docs-json for tooling consumption
- JWT Bearer auth scheme configured globally
- @ApiTags on every controller
- @ApiOperation summaries on every endpoint
- @ApiResponse with HTTP status codes on every endpoint
- @ApiBearerAuth() on all JWT-protected endpoints
- @ApiProperty with examples on all DTO fields
Health Checks
Liveness and readiness probes for container orchestration and load balancers outside the versioned API prefix.
- Liveness — GET /health/live returns 200 without database access
- Readiness — GET /health/ready pings the database and returns 200 or 503
- Health routes live outside the /api/v1 prefix
API Infrastructure
Global pipes, filters, and CORS configuration providing consistent validation and error handling.
- Global prefix — /api/v1
- Global ValidationPipe with whitelist, forbidNonWhitelisted, and transform
- Global AllExceptionsFilter with unified error shape
- CORS configurable via CORS_ORIGIN env, defaulting to *
- No stack traces in production error responses
Idempotent Seeder
Repeatable database seeding for roles and admin users that safely skips existing records.
- Idempotent role seeding — ADMIN and USER skipped if already present
- Idempotent admin user seeding via ADMIN_EMAIL and ADMIN_PASSWORD env vars
- Argon2id password hashing in seeder matching auth service parameters
- Error handling with logged errors and exit code 1
Docker & Compose
Containerized local development setup with multi-stage builds, health checks, and persistent data.
- Multi-stage Dockerfile — builder stage with pnpm build, runtime on node:22-alpine
- docker-compose.yml with PostgreSQL 17 and API service
- PostgreSQL pg_isready health check and service dependency orchestration
- Named pgdata volume for persistent database storage
- .dockerignore excluding node_modules, dist, .git, and coverage
Testing
Unit and end-to-end test setup with Jest, path aliases, and dedicated configurations.
- 7 unit test spec files covering 33 test cases
- Auth — registration, login, and password-change flows
- RBAC — role assignment, retrieval, and duplicate prevention
- Users — find, create, update, and pagination operations
- Configuration, database, and common module spec coverage
- E2E smoke test verifying GET /api/v1 returns 200
- Jest path aliases synced with tsconfig.json
- Separate E2E Jest config with adjusted path resolution
Modular Monolith Architecture
NestJS monorepo with seven libraries, public service interfaces, and strict module boundaries.
- NestJS monorepo — one API application plus seven libraries
- Modular boundaries with public service interfaces and injection tokens
- Custom repository classes wrapping TypeORM Repository
- Cross-module communication only via public/ interfaces
- Barrel exports at every library root
- Path aliases (@modules/*, @shared/*) in tsconfig.json and Jest config