🎯 Core Features

• User registration/login with validation (email + strong password)
• JWT access tokens (15m) + refresh tokens (7d) with rotation
• Password reset and email verification flows
• Admin-only token minting for health/logs endpoints
• Role-based access control (user, admin)
• Fire-and-forget email processing via microservice
• Automated token cleanup via dedicated microservice
• Centralized error handling
• Strong logging with global metadata (version, environment, service)
• Secure CORS configuration per environment
• Queue-based architecture for async operations

📁 Project Structure

src/
├── app.ts                         # Express app wiring (CORS, security, parsers, routes, errors)
├── server.ts                      # Server bootstrap + startup logs
├── config/
│   ├── env.ts                     # getEnvVar helper (no defaults; explicit envs)
│   └── index.ts                   # Typed config, reads env vars
├── controllers/
│   ├── authController.ts          # register, login, logout, refresh, password reset, email verify
│   ├── exampleController.ts
│   └── healthController.ts
├── middleware/
│   ├── errorHandler.ts            # Central error middleware
│   └── tokenAuthHandler.ts        # JWT verification + blacklist check
├── routes/
│   ├── index.ts                   # Route aggregation
│   └── v1/
│       ├── authRoute.ts           # /v1/auth routes
│       ├── healthRoute.ts
│       ├── logsRoute.ts
│       └── homeRoute.ts
├── services/
│   ├── redis/
│   │   ├── jwtBlacklist.ts        # blacklistToken, isTokenBlacklisted
│   │   ├── refreshTokens.ts       # refresh token management
│   │   └── redisClient.ts         # Redis connection
│   ├── authTokenService.ts        # password reset & email verification tokens
│   └── emailQueueService.ts       # fire-and-forget email processing
├── utils/
│   ├── assertions/                # Validation (isValidEmail, isStrongPassword)
│   └── logger.ts                  # Winston logger

microservices/
├── email-service/                 # Dedicated email processing microservice
│   ├── src/
│   ├── Dockerfile
│   ├── package.json
│   └── README.md
└── token-cleanup/                 # Automated token cleanup microservice
    ├── src/
    ├── Dockerfile
    ├── package.json
    └── README.md

📍 Quick Start

Option 1: Railway Template (Recommended)

1. Click the "Deploy on Railway" button above
2. Connect your GitHub account
3. Railway will automatically:
   • Fork this repository
   • Set up PostgreSQL and Redis
   • Deploy all microservices
   • Configure environment variables
4. Your app will be live in ~3 minutes!

Option 2: Local Development

Prerequisites

• Node.js 18+
• PostgreSQL database per environment (dev/staging/prod)
• Redis instance per environment (or shared with env-specific keys)

Install & Setup

# Clone and install
git clone <your-repo-url>
cd nodejs-microservices-starter
yarn install

Environment Files

Create the following files in the repo root (values are examples):

# .env.development
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp_dev
JWT_SECRET=dev_jwt_secret
HEALTH_SECRET=dev_health_secret
LOGS_SECRET=dev_logs_secret
REDIS_URL=redis://localhost:6379
ALLOWED_ORIGINS=http://localhost:3001

# .env.staging
NODE_ENV=staging
DATABASE_URL=postgresql://...staging
JWT_SECRET=staging_jwt_secret
HEALTH_SECRET=staging_health_secret
LOGS_SECRET=staging_logs_secret
REDIS_URL=redis://...
ALLOWED_ORIGINS=https://staging-frontend.yourapp.com

# .env.production
NODE_ENV=production
DATABASE_URL=postgresql://...production
JWT_SECRET=prod_jwt_secret
HEALTH_SECRET=prod_health_secret
LOGS_SECRET=prod_logs_secret
REDIS_URL=redis://...
ALLOWED_ORIGINS=https://yourapp.com,https://www.yourapp.com

Notes:

• No defaults are used for critical variables; missing envs will throw at startup.
• Railway sets PORT automatically; you do not need to set it there.

🤖 AI Development Workflow

This template is optimized for AI-assisted development:

Claude Code Integration

• 📄 CLAUDE.md: Complete project context for Claude Code sessions
• 🎯 Conventions: AI-aware coding patterns and architecture
• 🛠️ Commands: Pre-configured yarn scripts for AI suggestions

Cursor IDE Setup

• 📄 cursor_context.md: Mirrors CLAUDE.md for Cursor AI
• ⚙️ .cursorrules: Auto-applied coding standards
• 🔄 Sync: Automatic context synchronization

What Makes This AI-Enhanced?

🧠 Smart Context Files

• CLAUDE.md - Complete project context for Claude Code
• cursor_context.md - Mirrors context for Cursor IDE
• .cursorrules - Auto-applied coding standards
• Synchronized documentation across all AI tools

🎯 AI-Optimized Patterns

# AI understands these semantic commands
yarn quality              # Runs type-check + lint + format
yarn release:minor        # Intelligent version bumping
yarn migrate:dev          # Context-aware DB migrations
yarn dev                  # Hot reload with AI suggestions

🚀 Instant AI Onboarding

• Zero configuration needed for Claude Code or Cursor
• AI instantly understands your architecture and patterns
• Contextual suggestions based on microservices best practices
• Automated code quality and consistency

📜 Scripts

{
  "dev": "dotenv -e .env.development -- ts-node-dev --respawn --transpile-only -r tsconfig-paths/register src/server.ts",
  "staging": "dotenv -e .env.staging -- ts-node-dev --respawn --transpile-only -r tsconfig-paths/register src/server.ts",
  "build": "tsc",
  "start": "dotenv -e .env.production -- node dist/server.js",
  "migrate:generate": "dotenv -e .env.development -- prisma migrate dev --create-only",
  "migrate:dev": "dotenv -e .env.development -- prisma migrate deploy",
  "migrate:staging": "dotenv -e .env.staging -- prisma migrate deploy",
  "migrate:prod": "dotenv -e .env.production -- prisma migrate deploy"
}

🏃‍♂️ Run Locally

# Development backend on http://localhost:3000
yarn dev

# Staging-config backend locally
yarn staging

# Start all services with Docker
docker-compose up

🗄 Database Setup (Prisma + PostgreSQL)

🚀 Quick Database Setup

Option 1: Railway Template (Automatic)

When you deploy via Railway template:

1. PostgreSQL is auto-provisioned and connected
2. Migrations run automatically during deployment
3. Ready to use - no manual setup needed!

Option 2: Local Development Setup

1. Set up PostgreSQL locally or use a cloud provider
2. Configure DATABASE_URL in your .env.development:

   DATABASE_URL=postgresql://user:password@localhost:5432/myapp_dev
   

3. Run initial migration to create tables:

   yarn migrate:dev
   

4. Generate Prisma client:

   yarn prisma generate
   

📊 Database Schema

The starter includes a minimal authentication schema:

• users - User accounts with email verification
• auth_tokens - Password reset & email verification tokens

Location: prisma/schema.prisma | Generated client: generated/prisma/

🔄 Migration Commands

# Development: Apply migrations and generate client
yarn migrate:dev

# Production environments: Apply migrations only  
yarn migrate:staging  # For staging environment
yarn migrate:prod     # For production environment

# Create new migration (when you modify schema)
yarn migrate:generate -- --name your_migration_name

# Generate Prisma client after schema changes
yarn prisma generate

🚨 Important Setup Notes

For Railway Deployment:

• Database is auto-configured ✅
• Migrations run automatically ✅
• No manual setup required ✅

For Manual Deployment:

• Run yarn migrate:prod after first deployment
• Run migrations after each schema change
• Generate client in build process

For Local Development:

• Run yarn migrate:dev after cloning
• This creates tables and generates the client
• Redis also required (see docker-compose.yml)

🆕 First-Time Setup

When you first clone this template:

1. No existing migrations - The template starts clean
2. Run yarn migrate:dev - This will:
   • Create your first migration based on the schema
   • Apply it to your database
   • Generate the Prisma client
3. Database ready - You now have users and auth_tokens tables

The starter schema includes everything needed for authentication!

🔐 Authentication

Endpoints

• POST /v1/auth/register (with email verification)
• POST /v1/auth/login
• POST /v1/auth/refresh (refresh access token)
• POST /v1/auth/logout (blacklists token, optional ?all=true)
• POST /v1/auth/forgot-password
• POST /v1/auth/reset-password
• POST /v1/auth/change-password (authenticated)
• POST /v1/auth/verify-email
• POST /v1/auth/resend-verification
• GET /v1/auth/health-token (admin only)
• GET /v1/auth/logs-token (admin only)

JWT Tokens

• Access token: 15 minutes, signed with JWT_SECRET
• Refresh token: 7 days, stored in Redis with session rotation
• Password reset tokens: 1 hour, database-backed with single use
• Email verification tokens: 24 hours, database-backed with single use
• Health/Logs tokens: 1 hour, signed separately (HEALTH_SECRET, LOGS_SECRET). Intended for service endpoints like /v1/health and /v1/logs

Middleware: tokenAuthHandler

• Verifies token using the expected secret (based on route scope) and populates req.user.
• Checks Redis blacklist for access tokens (revoked on logout). If blacklisted → 401.

Logout

• Blacklists current access token in Redis with TTL matching token expiry.
• Health/Logs tokens are not blacklisted during user logout (different scope/use).

✅ Validation

• Email: utils/assertions/isValidEmail.ts
• Password strength: utils/assertions/isStrongPassword.ts

🌐 CORS

Configured in src/app.ts using `config.a