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.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Using Skill Files to Stop SQL Injection in Generated Backend Code.

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.