🔗 URL Shortener

A modern, full-stack URL shortening service with comprehensive analytics and user management.

📋 Table of Contents

✨ Features
🛠️ Tech Stack
🏗️ Architecture
🚀 Quick Start
📱 Usage Guide
🔒 Security
📊 Performance
🌐 Deployment
🤝 Contributing
📄 License

✨ Features

🎯 Core Functionality

Instant URL Shortening: Create short, memorable links in seconds
Custom Aliases: Choose your own custom short URLs
Bulk URL Management: Handle multiple URLs efficiently

User Management

Secure Authentication: JWT-based login with refresh tokens
User Dashboard: Centralized management of all shortened URLs
Session Management: Secure logout and token refresh

Analytics & Tracking

Click Analytics: Monitor traffic and engagement metrics
Referrer Tracking: Track where your clicks are coming from
Time-based Analytics: Track clicks over time periods

Developer Features

RESTful API: Complete API for integration
Rate Limiting: Prevent abuse with configurable limits
API Documentation: Comprehensive API docs with examples
Webhook Support: Real-time notifications for events

Tech Stack

Frontend

Technology	Version	Purpose
React	19.1.1	UI Framework
Vite	7.1.7	Build Tool & Dev Server
Tailwind CSS	4.1.14	Styling Framework
React Router	7.9.4	Client-side Routing
Axios	1.12.2	HTTP Client
React Hot Toast	2.6.0	Notifications
React Icons	5.5.0	Icon Library

Backend

Technology	Version	Purpose
Node.js	Latest	Runtime Environment
Express.js	5.1.0	Web Framework
MongoDB	Latest	Database
Mongoose	8.19.0	ODM
JWT	9.0.2	Authentication
bcryptjs	3.0.2	Password Hashing
Helmet	8.1.0	Security Headers
Morgan	1.10.1	HTTP Logging

DevOps & Tools

Tool	Purpose
Vercel	Frontend Deployment
Render	Backend Deployment
GitHub Actions	CI/CD Pipeline
ESLint	Code Quality
Nodemon	Development Hot Reload

🏗️ Architecture

graph TB
    subgraph "Client Layer"
        A[React Frontend]
        B[Mobile App]
        C[Third-party Apps]
    end

    subgraph "API Gateway"
        D[Express.js Server]
        E[Rate Limiting]
        F[CORS & Security]
    end

    subgraph "Business Logic"
        G[Auth Controller]
        H[URL Controller]
        I[Analytics Controller]
    end

    subgraph "Data Layer"
        J[MongoDB Database]
        K[User Collection]
        L[URL Collection]
        M[Analytics Collection]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    G --> J
    H --> J
    I --> J
    J --> K
    J --> L
    J --> M

Project Structure

URL Shortener/
├── 📁 frontend/                 # React frontend application
│   ├── 📁 src/
│   │   ├── 📁 components/       # Reusable UI components
│   │   ├── 📁 pages/            # Page components
│   │   ├── 📁 hooks/            # Custom React hooks
│   │   ├── 📁 utils/            # Utility functions
│   │   └── 📄 api.js            # API client configuration
│   ├── 📄 vite.config.mjs       # Vite configuration
│   └── 📄 vercel.json           # Deployment configuration
│
├── 📁 backend/                  # Node.js backend API
│   ├── 📁 src/
│   │   ├── 📁 config/           # Configuration files
│   │   ├── 📁 controllers/      # Request handlers
│   │   ├── 📁 middlewares/      # Express middlewares
│   │   ├── 📁 models/           # Database models
│   │   ├── 📁 routes/           # API routes
│   │   ├── 📁 utils/            # Utility functions
│   │   └── 📁 logs/             # Application logs
│   └── 📄 .env                  # Environment variables
│
└── 📁 docs/                     # Documentation
    ├── 📄 API.md               # API documentation
    ├── 📄 DEPLOYMENT.md        # Deployment guide
    └── 📄 CONTRIBUTING.md      # Contribution guidelines

Quick Start

Prerequisites

Node.js (v18 or higher)
MongoDB (v6 or higher)
npm or yarn
Git

Installation

Clone the repository

git clone https://github.com/yourusername/url-shortener.git
cd url-shortener

Set up the backend

cd backend
npm install

# Create environment file
cp .env.example .env
# Edit .env with your configuration

# Start development server
npm run backend

Set up the frontend

cd ../frontend
npm install

# Start development server
npm run dev

Access the application
- Frontend: http://localhost:5173
- Backend API: http://localhost:5000
- API Docs: http://localhost:5000/api-docs

Environment Variables

Create a .env file in the backend directory:

# Server Configuration
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/url-shortener

# Authentication
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRE=7d
JWT_REFRESH_SECRET=your-refresh-token-secret
JWT_REFRESH_EXPIRE=30d

# Security
BCRYPT_ROUNDS=12
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:5173

Usage Guide

For End Users

Create Account: Register with email and password
** Shorten URLs**: Paste long URLs to get short links
Customize: Create custom aliases for your links
Track Performance: Monitor clicks and analytics

API Usage Example

// Shorten a URL
const response = await fetch("/api/v1/urls", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_JWT_TOKEN",
  },
  body: JSON.stringify({
    originalUrl: "https://example.com/very-long-url",
    customShortId: "my-custom-link", // Optional
  }),
});

const data = await response.json();
console.log(data.shortUrl); // https://yoursite.com/my-custom-link

Security

Authentication & Authorization

✅ JWT Tokens: Secure token-based authentication
✅ Refresh Tokens: Automatic token renewal
✅ Password Hashing: bcrypt with salt rounds
✅ Session Management: Secure logout and cleanup

API Security

Rate Limiting: Prevent abuse and DDoS attacks
CORS Protection: Configured for specific origins
Helmet.js: Security headers implementation
Input Validation: Comprehensive request validation

Data Protection

HTTPS Only: All communications encrypted
Environment Variables: Sensitive data protection
Cookie Security: HttpOnly and Secure flags
Data Sanitization: XSS prevention

Performance

Backend Optimizations

Connection Pooling: Efficient database connections

Frontend Optimizations

Code Splitting: Lazy loading of components

Monitoring

Performance Metrics: Response time tracking
Error Monitoring: Comprehensive error logging
Usage Analytics: User behavior tracking
Health Checks: Automated system monitoring

Deployment

Frontend (Vercel)

# Install Vercel CLI
npm i -g vercel

# Deploy
cd frontend
vercel --prod

Backend (Render/Railway)

# Connect your repository
# Set environment variables
# Deploy automatically on push

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

Environment Setup

Production Database: MongoDB Atlas

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

ESLint: Follow the configured linting rules
Prettier: Consistent code formatting

Documentation: Update docs for API changes

Author

Amritanshu Goutam

Made with ❤️ and JavaScript

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
Future_Scopes		Future_Scopes
backend		backend
frontend		frontend
.gitignore		.gitignore
DEPLOYMENT_FIX.md		DEPLOYMENT_FIX.md
README.md		README.md

bhutuklearning/Basic-URL-Shortener

Folders and files

Latest commit

History

Repository files navigation