CLAUDE.md Template: Express.js + PostgreSQL + Custom JWT + Sequelize ORM

Overview

CLAUDE.md template for Express.js + PostgreSQL + Custom JWT + Sequelize ORM is a copyable instruction page that guides engineers to scaffold a legacy migration hub API. It covers Express routes, PostgreSQL via Sequelize, and a secure JWT authentication flow tailored for a migration-oriented backend. This page is a CLAUDE.md template, not a generic blog post.

Direct answer: Use this template to rapidly bootstrap an API with modular structure, robust authentication, strict input validation, and migration-driven database changes using Sequelize in a Node.js + Express environment.

When to Use This CLAUDE.md Template

• You need a repeatable CLAUDE.md scaffold for an Express.js REST API backed by PostgreSQL.
• You require a custom JWT authentication flow with token expiry, rotation concepts, and middleware-based protection.
• You work with Sequelize ORM for models, migrations, and seed data in a migration hub context.
• You want a copyable instruction block to paste into CLAUDE.md and a stack-specific project structure.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, an AI assistant specialized in backend architecture for Express.js + PostgreSQL + Sequelize + JWT. Produce a precise, executable CLAUDE.md template block for this stack.

Architecture rules:
- Build a REST API using Express.js
- Use PostgreSQL as the database
- Use Sequelize ORM for models and migrations
- Implement a custom JWT authentication flow with HS256
- Structure code to be modular, testable, and deployable
- Do not rely on in-memory storage for production data

File structure rules:
- src/controllers
- src/models
- src/routes
- src/middlewares
- src/config
- src/migrations
- src/seeders
- app.js
- server.js
- config/*.js and .env.example

Authentication rules:
- Implement login to return a JWT with a 15-minute expiry and optional refresh token pattern
- Validate inputs with express-validator; sanitize inputs
- Protect routes with a JWT verification middleware
- Do not hard-code secrets; use environment variables

Database rules:
- PostgreSQL connection via Sequelize with pooling
- Models: User, MigrationJob, MigrationLog, AuditTrail
- Use Sequelize migrations for schema changes; maintain migration history
- Do not use raw SQL without parameterization; prefer Sequelize query interface when needed

Validation rules:
- Validate all request bodies against explicit schemas
- Return consistent error shapes: { error, field }

Security rules:
- Enable helmet and proper CORS configuration
- Do not log sensitive fields (password hashes, tokens)
- Enforce HTTPS in production; avoid exposing DB credentials

Testing rules:
- Unit tests for services and validators
- Integration tests for auth routes and migration endpoints
- Use Jest and Supertest; mock DB in unit tests

Deployment rules:
- Provide Dockerfile and docker-compose for dev and prod
- Use environment-based config; manage secrets securely in CI/CD
- Run migrations before app startup in production

Things Claude must not do:
- Do not access production secrets or databases directly
- Do not generate weak or hard-coded JWT secrets or insufficient expiries
- Do not skip input validation or rely on client-side checks
- Do not perform unparameterized raw SQL

Recommended Project Structure

project-root/
  src/
    controllers/
    models/
    routes/
    middlewares/
    config/
    migrations/
    seeders/
  app.js
  server.js
  package.json
  .env.example

Core Engineering Principles

• Explicit contracts: clear interfaces for controllers, services, and routes.
• Separation of concerns: authentication, authorization, DB access, validation, and logging are isolated.
• Defensive programming: fail fast with validation errors and meaningful status codes.
• Idempotent migrations: migrations should be replayable and deterministic.
• Testable by design: code is structured to enable unit and integration tests.

Code Construction Rules

• Use Sequelize model definitions with explicit data types and validations.
• Routes should be defined in dedicated modules under src/routes and mounted in server/app.
• Middleware order: helmet & CORS → body parsing → auth verification → routes.
• JWT handling: sign with HS256, include iat and exp, verify using a shared secret from env vars.
• Validation: enforce schemas on all inputs using express-validator.
• Error handling: central error handler that returns { error, field? } shapes.

Security and Production Rules

• Enable HTTPS; deploy behind a reverse proxy that handles TLS termination.
• Store secrets in environment variables; avoid hard-coded keys.
• Regularly rotate JWT secrets and use reasonable expiries.
• Limit JWT exposure by scoping permissions and shortest viable lifetimes.
• Audit logs for sensitive events; never log full JWTs or passwords.

Testing Checklist

• Unit tests for models, validators, and services.
• Integration tests for auth flow (login, protected routes).
• Database migration tests to ensure schema changes apply cleanly.
• End-to-end tests verifying migration hub endpoints with a test database.
• CI checks run linting, tests, and type checks (if TypeScript is introduced).

Common Mistakes to Avoid

• Using raw queries without parameterization; always use bindings.
• Storing secrets in code or environment without defaults in .env.example.
• Overexposing endpoints; enable proper authorization scopes per route.
• Ignoring migration drift between environments; ensure migrations run in CI/CD.
• Skipping input validation and relying solely on client-side validation.

FAQ

What is the CLAUDE.md template for this stack?

It provides a ready-to-paste CLAUDE.md block and a stack-specific project structure for Express.js + PostgreSQL + Sequelize + Custom JWT migrations hub.

Which files are essential in this template?

src/controllers, src/models, src/routes, src/middlewares, src/config, src/migrations, src/seeders, app.js, server.js.

How is authentication handled?

JWTs are issued with a 15-minute expiry, verified via middleware, and secrets are read from environment variables.

How are migrations managed?

Sequelize migrations track schema changes; migrations run before app startup in production.

How can I customize for production?

Configure env vars, secrets manager in CI/CD, and adapt CORS and helmet settings for the domain.