A production-grade backend capstone project built with Node.js, TypeScript, PostgreSQL, Redis, BullMQ, Cloudinary, and JWT, demonstrating real-world backend architecture, authentication, caching, background processing, and scalable API design.
This project is the final capstone backend application for a comprehensive Node.js development journey.
The goal is to go beyond basic CRUD APIs and build a backend that follows production-ready engineering practices.
The application implements a role-based system with two primary roles:
- 👤 User
- 🛡️ Admin
It combines authentication, task management, database architecture, caching, rate limiting, background jobs, file management, logging, and centralized error handling into one complete backend system.
- JWT-based authentication
- Google OAuth authentication
- Secure password handling
- Role-based authorization
- Protected routes
- User/Admin access control
Users can manage support tasks through a complete CRUD system.
- Create tasks
- View tasks
- Update tasks
- Delete tasks
- Task ownership
- Administrative oversight
- Role-based task operations
Redis is integrated to improve API performance.
The project follows the Cache-Aside Pattern:
Client
│
▼
API
│
▼
Redis
│
├── Cache Hit ──────► Return Data
│
└── Cache Miss
│
▼
PostgreSQL
│
▼
Store in Redis
│
▼
Return Data
Redis is used for:
- API caching
- Banner caching
- Rate limiting
- Fast temporary data access
- Pub/Sub capabilities
Long-running or non-critical operations are handled asynchronously using BullMQ.
For example, Cloudinary image deletion does not need to block the main API request.
API Request
│
▼
Backend
│
├── Main Operation ──────► Response
│
└── Add Job
│
▼
Redis
│
▼
BullMQ
│
▼
Worker
│
▼
Cloudinary
- Cloudinary image deletion
- Heavy processing
- Notifications
- Cleanup operations
- Other asynchronous tasks
This approach keeps API responses fast and prevents unnecessary blocking.
The application uses PostgreSQL as its primary relational database.
PostgreSQL runs in a Docker-based development environment.
- User data
- Authentication information
- Roles
- Tasks
- Relationships
- Persistent application data
The project includes automated SQL migration management for maintaining database schema changes.
Migration-based development provides:
- Version-controlled schema changes
- Reproducible database setup
- Safer production deployments
- Organized database evolution
Example:
migrations/
├── 001_create_users.sql
├── 002_create_tasks.sql
├── 003_add_auth_fields.sql
└── 004_update_task_schema.sql
The project separates responsibilities into different layers.
┌─────────────────┐
│ Client │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Controllers │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Services │
│ Business Logic │
└────────┬────────┘
│
┌──────────┴──────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Repository │ │ External APIs│
│ SQL Queries │ │ Cloudinary │
└───────┬──────┘ └──────────────┘
│
▼
┌──────────────┐
│ PostgreSQL │
└──────────────┘
Redis
│
┌─────────┴─────────┐
│ │
Caching Rate Limit
│
BullMQ
│
Workers
project/
│
├── source/
│ ├── controllers/
│ ├── routes/
│ ├── middlewares/
│ ├── validators/
│ ├── config/
│ └── app.ts
│
├── repository/
│ ├── user.repository.ts
│ ├── task.repository.ts
│ └── ...
│
├── services/
│ ├── auth/
│ ├── cloudinary/
│ ├── redis/
│ ├── queue/
│ └── ...
│
├── constants/
│ └── index.ts
│
├── migrations/
│ ├── 001_*.sql
│ ├── 002_*.sql
│ └── ...
│
├── workers/
│ └── ...
│
├── package.json
├── tsconfig.json
├── docker-compose.yml
└── README.md
Controllers are responsible for handling HTTP requests and responses.
Request
↓
Controller
↓
Service
↓
Response
They should remain lightweight and delegate business logic to the service layer.
The service layer contains the application's business logic.
Examples:
- Authentication logic
- Task management
- Cloudinary operations
- Redis operations
- Background job creation
This keeps business rules separate from HTTP-specific code.
The repository layer handles database operations.
Service
│
▼
Repository
│
▼
PostgreSQL
Responsibilities include:
- SQL queries
- Database interaction
- Data retrieval
- Data persistence
This separation makes database logic easier to maintain and test.
The project uses a custom AppError class for consistent application errors.
Instead of handling errors differently in every controller, errors are passed to centralized middleware.
Controller
│
▼
Service
│
└── AppError
│
▼
Error Middleware
│
▼
HTTP Response
- Consistent error responses
- Cleaner controllers
- Easier debugging
- Centralized error management
- Better maintainability
Redis is used to implement distributed rate limiting.
Rate limiting protects APIs from:
- Excessive requests
- Abuse
- Brute-force attempts
- Unnecessary server load
Example:
Client
│
│ Request
▼
Rate Limiter
│
▼
Redis
│
├── Within Limit ──► API
│
└── Limit Exceeded ──► 429 Too Many Requests
Using Redis allows rate-limit state to be shared across multiple backend instances.
Cloudinary is used for file and image management.
The application integrates Cloudinary with Multer middleware for handling uploaded files.
Client
│
│ Multipart Upload
▼
Multer
│
▼
Backend
│
▼
Cloudinary
│
▼
Image URL
│
▼
PostgreSQL
For deletion, the operation can be processed asynchronously using BullMQ.
The project uses Pino Logger for structured application logging.
Logging helps with:
- Debugging
- Monitoring
- Error investigation
- Production troubleshooting
- Request tracking
Example:
INFO Server started
INFO Database connected
INFO Redis connected
INFO User authenticated
WARN Rate limit approaching
ERROR Cloudinary operation failed
User
│
│ Login
▼
Auth Controller
│
▼
Auth Service
│
▼
Verify Credentials
│
▼
Generate JWT
│
▼
Client
For protected requests:
Client
│
│ Authorization: Bearer <token>
▼
Authentication Middleware
│
▼
Verify JWT
│
▼
Attach User
│
▼
Controller
The application also supports Google OAuth authentication.
User
│
▼
Google
│
▼
OAuth Callback
│
▼
Backend
│
▼
Find/Create User
│
▼
Generate Authentication Token
│
▼
Client
This provides users with an alternative authentication method while keeping identity management centralized.
The system supports different permissions based on user roles.
User
│
┌──────┴──────┐
│ │
User Role Admin Role
│ │
▼ ▼
User Features Admin Features
Example:
| Feature | User | Admin |
|---|---|---|
| Register/Login | ✅ | ✅ |
| Manage Own Tasks | ✅ | ✅ |
| View Tasks | ✅ | ✅ |
| Administrative Oversight | ❌ | ✅ |
| User Management | ❌ | ✅ |
The backend follows RESTful API design principles.
POST /api/auth/register
POST /api/auth/login
GET /api/auth/me
POST /api/tasks
GET /api/tasks
GET /api/tasks/:id
PATCH /api/tasks/:id
DELETE /api/tasks/:id| Method | Purpose |
|---|---|
GET |
Retrieve resources |
POST |
Create resources |
PATCH |
Partially update resources |
DELETE |
Delete resources |
| Technology | Purpose |
|---|---|
| Node.js | Backend runtime |
| TypeScript | Type-safe development |
| PostgreSQL | Primary database |
| Redis | Caching & rate limiting |
| BullMQ | Background job processing |
| Cloudinary | Image/file storage |
| Multer | Multipart file handling |
| Pino | Structured logging |
| JWT | Authentication |
| Google OAuth | Social authentication |
| Docker | PostgreSQL development environment |
This capstone focuses on concepts commonly used in real-world backend systems.
- Layered architecture
- Separation of concerns
- Repository pattern
- Service layer
- Centralized error handling
- PostgreSQL
- SQL queries
- Database migrations
- Transactions
- Data relationships
- Redis caching
- Cache-aside pattern
- Rate limiting
- Background processing
- JWT
- Google OAuth
- Role-based authorization
- Protected routes
- Docker
- Redis
- Background workers
- External cloud storage
- Structured logging
- Centralized error handling
- Request monitoring
A typical request can flow through multiple layers:
Client
│
▼
Route
│
▼
Middleware
│
├── Authentication
├── Authorization
├── Validation
└── Rate Limiting
│
▼
Controller
│
▼
Service
│
├───────────────┐
▼ ▼
Repository Redis
│ │
▼ │
PostgreSQL │
│
▼
Response
For asynchronous work:
Service
│
▼
BullMQ Queue
│
▼
Redis
│
▼
Worker
│
▼
External Service
The backend uses multiple techniques to improve performance and scalability.
Frequently accessed data is cached to reduce database load.
Protects backend resources from excessive traffic.
Expensive operations are moved away from the request-response cycle.
Database access remains organized and reusable.
Makes production debugging and monitoring easier.
git clone <https://github.com/yeasin-riyad/nodejs-capstone-project.git>
cd <nodejs-capstone-project>npm installdocker compose up -dCreate a .env file:
NODE_ENV=development
PORT=5000
DATABASE_URL=your_postgresql_connection_string
JWT_SECRET=your_jwt_secret
REDIS_URL=redis://localhost:6379
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secretnpm run migratenpm run devThe project can be extended with automated tests for:
- Authentication
- Authorization
- Task CRUD
- Repository methods
- Service logic
- Redis caching
- Rate limiting
- Background jobs
- API endpoints
Recommended testing strategy:
Unit Tests
│
▼
Integration Tests
│
▼
API Tests
│
▼
End-to-End Tests
Building this capstone helped strengthen my understanding of production backend development.
- Node.js architecture
- Express.js
- TypeScript
- REST API design
- Middleware
- Error handling
- PostgreSQL
- SQL
- Repository pattern
- Database migrations
- Relational data modeling
- JWT
- Google OAuth
- Role-based authorization
- Protected routes
- Redis
- Cache-aside pattern
- Rate limiting
- Background processing
- Docker
- BullMQ
- Cloudinary
- Pino logging
- Asynchronous architecture
A production backend is much more than CRUD APIs.
The most important lessons from this project are:
- Separate business logic from HTTP logic.
- Use repositories to keep database access organized.
- Use Redis when caching can reduce database load.
- Move expensive operations to background workers.
- Use centralized error handling for consistent APIs.
- Protect APIs with authentication, authorization, and rate limiting.
- Use structured logging to make production debugging easier.
- Design the system so individual components can evolve independently.
Node.js
│
▼
Express.js
│
▼
TypeScript
│
▼
REST API
│
▼
PostgreSQL
│
▼
Authentication
│
▼
Redis
│
▼
Rate Limiting
│
▼
Cloudinary
│
▼
BullMQ
│
▼
Background Workers
│
▼
Production-Ready Backend 🚀
Backend Developer | Full-Stack Enthusiast | Problem Solver
Interested in building scalable backend systems, distributed architectures, and production-ready applications.
If you find this project useful or it helps you learn backend development, consider giving the repository a ⭐.
Happy Coding! 🚀