NestJS + PostgreSQL + Passport.js JWT Auth + TypeORM Modular Blueprint | CLAUDE.md Template

Overview

The CLAUDE.md template is a copyable blueprint for building a production-grade NestJS API stack with PostgreSQL, Passport.js JWT-based authentication, and TypeORM in a modular architecture. It targets clean separation of concerns, testability, and maintainable growth in a real-world service.

Stack focus: NestJS, PostgreSQL, Passport.js for JWT authentication, TypeORM for ORM, modular architecture with feature-based modules.

When to Use This CLAUDE.md Template

• You need a scalable NestJS API skeleton with JWT-based authentication.
• You require a modular structure that cleanly separates domain logic, persistence, and authentication concerns.
• You want a TypeORM-based PostgreSQL setup with migrations and seeders for production readiness.
• You want Claude Code to generate consistent, testable scaffolding for new features.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior NestJS architect assembling a modular API stack using PostgreSQL, Passport.js JWT authentication, and TypeORM. Your output must be a clean, production-ready blueprint that Claude Code can paste and immediately scaffold.

Architecture rules:
- Use a feature-based module layout: src/modules/{auth, users, posts, shared}
- Use TypeORM for data access with PostgreSQL; include migrations and seed scripts
- Passport.js JWT strategy for access tokens; implement refresh tokens as a separate mechanism
- Centralized config via environment variables (dotenv or process.env) with a config service
- Controllers should be thin; business logic lives in services; DTOs validate input
- Use global pipes and guards for validation and auth where appropriate
- Enable CORS, helmet, and secure headers in production
- Use environment-specific logging with log levels

File structure rules:
- src/main.ts
- src/app.module.ts
- src/config/*.ts
- src/modules/auth/* (auth.controller.ts, auth.service.ts, jwt.strategy.ts, local.strategy.ts)
- src/modules/users/* (controllers, services, entities, dto)
- src/modules/shared/* (guards, interceptors, filters, utilities)
- src/entities/* (if using a shared repository pattern)
- src/database/migrations/*

Authentication rules:
- /auth/login returns a JWT access token; /auth/refresh returns a new token
- Use HttpOnly cookies for refresh tokens where possible; otherwise, store securely server-side
- Validate JWT with a strict secret and set reasonable expiration (e.g., 15m access, 7d refresh)
- Protect sensitive endpoints with JwtAuthGuard; avoid token exposure in logs

Database rules:
- PostgreSQL as the database; use TypeORM migrations for schema changes
- Connection via environment variables (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME)
- Use optimistic locking where applicable; index frequently queried fields
- Do not hard-code credentials; never commit secrets to repo

Validation rules:
- Use class-validator with DTOs for request payloads
- Global ValidationPipe with whitelist, forbidNonWhitelisted, transform enabled
- Validate nested DTOs where present

Security rules:
- Do not disable TLS in production; enable TLS termination at the edge/proxy
- Do not store secrets in code; load from environment
- Implement rate limiting on authentication endpoints
- Regularly rotate JWT signing keys and use short-lived access tokens

Testing rules:
- Unit tests for services and guards; integration tests for auth and user flows
- Use a test database (e.g., PostgreSQL) and clean state between tests
- Include test data factories for deterministic tests

Deployment rules:
- Provide npm run build and npm run start:prod scripts
- Include migration execution step as part of deployment (e.g., npm run typeorm:migrate)
- Use Docker or cloud-native deployments with health checks and graceful restarts

Things Claude must not do:
- Do not propose a non-modular architecture
- Do not use Mongoose or non-TypeORM data access in this blueprint
- Do not embed plaintext credentials or secrets
- Do not bypass input validation or security checks

Recommended Project Structure

src/
  main.ts
  app.module.ts
  config/
    app.config.ts
    database.config.ts
  modules/
    auth/
      controllers/
      dtos/
      guards/
      jwt.strategy.ts
      auth.module.ts
      auth.service.ts
    users/
      controllers/
      dtos/
      entities/
      services/
      users.module.ts
    posts/
      controllers/
      dtos/
      entities/
      services/
      posts.module.ts
    shared/
      guards/
      interceptors/
      utilities/
  entities/
  database/
    migrations/
    seeds/

Core Engineering Principles

• Modularity: feature-based modules with clear boundaries.
• Type safety: full use of TypeScript, DTO validation, and strict typing.
• Environment-driven: all secrets and configs sourced from the environment.
• Testability: unit and integration tests for services, guards, and controllers.
• Security-first: proper JWT handling, input validation, and secure headers.
• Observability: structured logs and metrics for auth and DB requests.

Code Construction Rules

• Always use DTOs with class-validator; enable global validation pipe.
• Authenticate endpoints with JwtAuthGuard; protect sensitive routes.
• Implement a dedicated TypeORM module with migrations and a seed script.
• Keep business logic in services; keep controllers thin.
• Use feature modules; avoid cross-cutting dependencies that create tight coupling.
• Do not use non-TypeORM ORMs in this blueprint.

Security and Production Rules

• Store all secrets in environment variables; do not commit them.
• Use HTTPs in production; enable helmet and secure headers.
• Configure short-lived access tokens with a refresh workflow.
• Limit authentication request rates to prevent brute force.
• Rotate signing keys periodically and validate token audience/issuer.

Testing Checklist

• Unit tests for services: cover success and error paths.
• Integration tests for auth flows: login, refresh, protected routes.
• Migration tests: schema aligns with entities after migrations.
• End-to-end tests if possible for the critical user journey.
• CI checks run type checks, lint, and test suite before merge.

Common Mistakes to Avoid

• Skipping DTO validation or using loosely typed inputs.
• Overloading a single module with unrelated responsibilities.
• Embedding database credentials in code or in environment-less configs.
• Disabling security headers in production for convenience.

FAQ

What is the CLAUDE.md Template for this stack?

A copyable blueprint that Claude Code can paste to scaffold a modular NestJS API with PostgreSQL, Passport.js JWT auth, and TypeORM.

Which files are generated by this template?

Auth guards, strategies, DTOs, entities, services, modules, and config scaffolding aligned to a modular layout.

How are tokens handled?

Access tokens are JWTs with short lifetimes; refresh tokens are rotated and stored securely server-side or in HttpOnly cookies.

Can I customize the database schema?

Yes. The template includes migrations and a seed process; modify entities and run migrations to align with your domain.

How do I test this blueprint?

Run unit tests for services/guards and integration tests for auth and user flows; use a dedicated test database.