A fully-featured URL shortening API built with NestJS, PostgreSQL, and JWT authentication.
The URL Shortener API is a full-fledged backend system designed to shorten URLs, track visits, and retrieve analytics. The system ensures scalability, security, and performance while strictly following DRY, SOLID, and clean architecture principles.
This project is fully Dockerized and uses PostgreSQL as the database, with raw SQL queries for optimized performance.
- Full RESTful APIs with raw SQL queries for maximum efficiency.
- JWT Authentication (Signup & Signin).
- Shorten URLs with user authentication.
- Redirect via Short URL.
- Track Visits (IP, User-Agent, Timestamp).
- Retrieve Statistics (Visit count for each shortened URL).
- Database Migrations & Seeding.
- Optimized DB indexes & queries.
- Swagger API Documentation for testing.
- Docker & Docker Compose for easy deployment.
| Tech | Description |
|---|---|
| NestJS | TypeScript-based backend framework |
| PostgreSQL | Database for storing URLs and tracking visits |
| TypeScript | Static typing for maintainability |
| JWT (JSON Web Tokens) | Secure authentication |
| Docker & Docker Compose | Containerized development & deployment |
| DB RAW QUERY | Database migrations (raw SQL queries used for performance) |
| Bcrypt | Secure password hashing |
| Swagger | API Documentation |
| Postman | API testing & debugging |
src/
│── auth/ # Authentication module
│ ├── controllers/ # Auth Controllers
│ ├── services/ # Auth Services
│ ├── dto/ # Data Transfer Objects (Request/Response)
│── urls/ # URL Shortening module
│ ├── controllers/ # URL Controllers
│ ├── services/ # URL Services
│ ├── dto/ # Data Transfer Objects (Request/Response)
│── database/ # Database Service & Migrations
│── common/ # Shared utilities & helpers
│── config/ # App configuration
│── main.ts # App entry point
│── app.module.ts # Main module
- Node.js (>=16.x)
- Docker & Docker Compose
- PostgreSQL (if not using Docker)
git clone https://github.com/hassangomaa/url-shortener.git
cd url-shortener
# Start services
docker-compose up --build -d
# Run database migrations
docker exec -it url_shortener_app npx ts-node ./src/database/migrate.ts# Install dependencies
npm install
# Setup environment variables
cp .env.example .env
# Start the app
npm run start:dev- Signup (
POST /auth/sign-up) - Signin (
POST /auth/sign-in) - JWT-based authentication is required for protected routes.
| Method | Endpoint | Description |
|---|---|---|
POST |
/auth/sign-up |
Register new user |
POST |
/auth/sign-in |
Authenticate user and receive tokens |
| Method | Endpoint | Description |
|---|---|---|
POST |
/shorten |
Shortens a long URL (Auth required) |
GET |
/:shortUrl |
Redirects to original URL |
GET |
/stats/:shortUrl |
Fetches visit statistics for a short URL (Auth required) |
- A user shortens a URL using
POST /shorten. - A unique short code is generated and stored in the database.
- When a user visits the short URL (
GET /:shortUrl):- The original URL is retrieved from the database.
- A visit record is logged (including IP, timestamp, and user-agent).
- The owner can fetch visit statistics using
GET /stats/:shortUrl.
-
Run Migrations
npx ts-node ./src/database/migrate.ts
-
Database Tables:
users: Stores registered users.urls: Stores original & shortened URLs.visits: Logs visits for analytics.
The project is fully Dockerized with the following services:
- App Container (Runs NestJS)
- PostgreSQL Database (Stores URLs & visits)
docker-compose up --build -d{
"email": "user@example.com",
"password": "securePassword123"
}{
"accessToken": "jwt_token",
"refreshToken": "jwt_refresh_token",
"user": { "id": 1, "email": "user@example.com" }
}{
"originalUrl": "https://www.example.com/long-url-path"
}{
"shortUrl": "abc123",
"originalUrl": "https://www.example.com/long-url-path",
"createdAt": "2025-02-12T10:00:00Z"
}- GET
/abc123→ Redirects tohttps://www.example.com/long-url-path - A visit record is logged.
{
"shortUrl": "abc123"
}{
"shortUrl": "abc123",
"visitCount": 10
}This project demonstrates a scalable, maintainable, and efficient URL Shortener using NestJS, PostgreSQL, Docker, and JWT Authentication. The clean architecture, raw SQL queries, and best security practices ensure performance and reliability.
🔥 Developed by HASSAN GOMAA. 🚀