nestjs-production-backend

Project overview

nestjs_pg_be is a learning-focused, production‑style backend built with NestJS, PostgreSQL, and Prisma.
The goal of this project is to practice NestJS while deliberately covering core backend concepts:

• Authentication & authorization (JWT access tokens, refresh tokens, guards, strategies)
• Modular architecture (separate auth and users domains)
• Database layer with Prisma and PostgreSQL
• Validation & DTOs with class-validator / class-transformer
• Environment‑based configuration (.env, JWT_SECRET, DATABASE_URL)

This is not a full product, but a production‑grade learning playground where features are implemented in a realistic way.

Tech stack

• Runtime: Node.js
• Framework: NestJS (TypeScript)
• Database: PostgreSQL
• ORM: Prisma
• Auth: @nestjs/jwt, passport-jwt, HTTP‑only refresh token cookie
• Validation: class-validator, class-transformer

Features (current)

• User model

  • Basic fields: id, full_name, username, email, password, role, timestamps
  • Email verification fields: emailVerificationToken, emailVerificationExpires
  • Persistent refreshToken hash stored per user

• Auth module (/api/auth)

  • POST /api/auth/register
    • Creates a user, hashes password with bcrypt
    • Generates access & refresh tokens
    • Stores hashed refresh token in DB
    • Sends a verification link via EmailService (currently logs to console)
    • Sets refreshToken as an HTTP‑only cookie
  • POST /api/auth/login
    • Login with email or username + password
    • Rejects unverified emails
    • Issues new access & refresh tokens
    • Sets refreshToken cookie
  • POST /api/auth/refresh
    • Reads refreshToken cookie
    • Verifies JWT, checks DB hash, rotates refresh token
    • Returns a new access token and updates the refreshToken cookie
  • POST /api/auth/logout
    • Clears stored refresh token in DB and removes cookie

• Users module (/api/users)

  • GET /api/users/profile
    • Protected by JwtGuard / JwtStrategy
    • Returns the authenticated user’s profile from the database

• JWT strategy & typing

  • JwtStrategy uses passport-jwt with bearer tokens
  • JwtPayload and JwtUser interfaces model the raw JWT payload and the user attached to req.user

Project structure (high level)

• src/main.ts – app bootstrap, global prefix api, validation pipe, cookie parser
• src/app.module.ts – root module wiring AuthModule, UsersModule, PrismaModule
• src/auth – authentication & authorization
  • auth.controller.ts, auth.service.ts
  • dto/ register & login DTOs
  • strategies/jwt.strategy.ts
  • guards/jwt.guard.ts
  • interfaces/jwt-payload.interface.ts
  • utils/token.util.ts for email verification tokens
• src/users – user‑facing domain (currently profile)
  • users.controller.ts, users.service.ts
• src/prisma – Prisma module & service
• prisma/schema.prisma – data model (User + Role enum)

Getting started

1. Prerequisites

• Node.js and npm installed
• PostgreSQL instance running and reachable

2. Install dependencies

npm install

3. Environment variables

Create an .env file in the project root (already .gitignored). Example:

DATABASE_URL="postgresql://user:password@localhost:5432/db_name"
PORT=4000
JWT_SECRET="replace_with_a_long_random_secret"

You can generate a strong secret with:

openssl rand -base64 32

4. Database setup

Run Prisma migrations (once your schema and DATABASE_URL are correct):

npx prisma migrate dev

You can also inspect the DB with:

npx prisma studio

5. Run the server

# development
npm run start

# watch mode
npm run start:dev

# production build + run
npm run build
npm run start:prod

The API will be available at http://localhost:4000/api.

API quick reference

• Auth

  • POST http://localhost:4000/api/auth/register
  • POST http://localhost:4000/api/auth/login
  • POST http://localhost:4000/api/auth/refresh
  • POST http://localhost:4000/api/auth/logout

• Users (protected)

  • GET http://localhost:4000/api/users/profile
    • Requires Authorization: Bearer <access_token>

Learning focus / backend concepts covered

This project is intentionally structured to practice backend fundamentals while learning NestJS:

• Clean module separation (auth vs users)
• DTOs and validation for input safety
• JWT auth with short‑lived access tokens and long‑lived refresh tokens
• Guards and strategies (JwtGuard, JwtStrategy) for protecting routes
• Persistent sessions via hashed refresh tokens in the database
• Prisma data access layer and migrations
• Environment‑driven configuration for secrets and DB URLs

As you extend this project, you can add more concepts (RBAC/roles, pagination, file uploads, background jobs, etc.) while staying within this production‑style structure.

Useful links

• NestJS documentation
• Prisma documentation