🔗 LinkShortener

A powerful, secure, and feature-rich link shortening service built for personal and professional use.

🚀 Quick Start • ✨ Features • 📱 Demo • 🔌 API • 🛠️ Deployment

✨ Features

🎯 Core Functionality

🔗 Link Shortening: Create custom or auto-generated short URLs
📊 Advanced Analytics: Detailed click tracking with geographic data, device info, and user behavior
🎛️ Admin Dashboard: Beautiful, responsive web interface for link management
🔄 Dynamic Updates: Change target URLs without breaking existing short links
📱 QR Code Generation: Built-in QR codes for easy mobile sharing
🔔 Push Notifications: Optional real-time click notifications via ntfy.sh

🛡️ Enterprise-Grade Security

🔐 JWT Authentication: Secure session management
🛡️ CSRF Protection: Cross-site request forgery prevention
⚡ Rate Limiting: Multi-tier protection against abuse
🧹 Input Sanitization: MongoDB injection prevention
🤖 Bot Detection: Automatic filtering of non-human traffic
📝 Audit Logging: Comprehensive request logging with Pino

🔌 Developer Experience

🚀 REST API: Complete CRUD operations with API key authentication
📖 Comprehensive Documentation: Detailed API docs with examples
⚡ Production Ready: HTTPS redirects, security headers, optimized for deployment
🔧 Environment Configuration: Flexible setup with environment variables
📱 Responsive Design: Bootstrap-based UI that works on all devices

🚀 Quick Start

Prerequisites

Node.js (v16+ recommended)
MongoDB (Atlas or self-hosted)

Installation

# Clone the repository
git clone https://github.com/dhivijit/LinkShortner.git
cd LinkShortner

# Install dependencies
npm install

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

# Generate admin password hash
node -e "console.log(require('bcrypt').hashSync('your-admin-password', 12))"

# Start the application
npm start          # Production
npm run dev        # Development (with auto-reload)

🔧 Environment Configuration

Create a .env file with the following variables:

# Required
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/linkshortener
ADMIN_PASSWORD_HASH=your-bcrypt-hashed-password
API_KEY=your-secret-api-key
JWT_SECRET=your-jwt-secret-key
CSRF_SECRET=your-csrf-secret
COOKIE_PARSER_SECRET=your-cookie-secret

# Optional
PORT=3000
DOMAIN_URL=yourdomain.com
NTFY_TOPIC=your-ntfy-topic          # For push notifications
LOG_LEVEL=info                      # debug, info, warn, error
NODE_ENV=production                 # development, production

📱 Demo

Admin Dashboard

Beautiful, responsive admin interface with real-time statistics and comprehensive link management

Click Analytics

Detailed tracking with geographic data, device information, and visit patterns

🎛️ Admin Interface

Access the Dashboard

Navigate to /admin/login
Enter your admin password
Manage links from the intuitive dashboard

Dashboard Features

📊 Real-time Statistics: Total links, visits, and active links
🔗 Link Management: Create, edit, delete, and track links
📈 Click Analytics: Detailed visitor insights and geographic data
⚙️ Settings Control: Toggle tracking and notifications per link
📱 QR Codes: Generate QR codes for any short link
📋 Quick Actions: Copy links, view stats, manage settings

🔌 API Documentation

Authentication

All API endpoints require authentication using your API key in the Authorization header:

Authorization: your-api-key-here

Quick API Examples

Create a short link:

curl -X POST http://localhost:3000/api/links \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://example.com", "shortened": "example"}'

Get all links:

curl -X GET http://localhost:3000/api/links \
  -H "Authorization: your-api-key"

Update a link:

curl -X PUT http://localhost:3000/api/links/example \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://new-example.com"}'

📖 Complete API Documentation: See API_DOCUMENTATION.md for detailed endpoints, examples, and error handling.

🏗️ Architecture

Tech Stack

Backend: Node.js + Express.js
Database: MongoDB with Mongoose ODM
Authentication: JWT + bcrypt password hashing
Frontend: EJS templates + Bootstrap 4
Security: Express Rate Limit, CSRF protection, input sanitization
Logging: Pino for structured, high-performance logging
Analytics: Custom tracking with geographic IP resolution

Data Models

Link Schema

{
  shortened: String (unique),     // Short code
  targetUrl: String,              // Destination URL
  visitCount: Number,             // Total clicks
  trackingEnabled: Boolean,       // Analytics toggle
  notificationEnabled: Boolean,   // Push notification toggle
  createdAt: Date                 // Creation timestamp
}

Tracking Schema (per link)

{
  shortened: String,              // Reference to link
  targetUrl: String,              // Current target
  visits: [{                      // Array of visit records
    visitNumber: Number,
    timestamp: Date,
    ipAddress: String,
    geographic: { country, region, city, coordinates },
    userAgent: { browser, os, device, engine },
    isBot: Boolean,
    referrer: String,
    acceptLanguage: String
  }]
}

🛡️ Security Features

Multi-Layer Protection

🔐 JWT Authentication: Secure session management with HTTP-only cookies
🛡️ CSRF Protection: Prevents cross-site request forgery attacks
⚡ Rate Limiting:
- Global: 100 requests/15min per IP
- API: 50 requests/15min per API key
- Auth: 5 attempts/15min per IP
🧹 Input Sanitization: MongoDB injection prevention
📝 Request Validation: Payload size limits and content validation
🔒 Production Security: HTTPS enforcement, secure headers

Best Practices Implemented

Encrypted password storage with bcrypt
Secure cookie configuration
Environment variable configuration
Comprehensive error handling
Structured logging for security monitoring

🛠️ Deployment

Vercel (Recommended)

Fork this repository
Connect to Vercel
Set environment variables in Vercel dashboard
Deploy automatically

Traditional VPS

Clone repository on server
Set up environment variables
Use PM2 or similar for process management
Configure reverse proxy (nginx/Apache)
Set up SSL certificate

Environment Checklist

✅ Set all required environment variables
✅ Configure MongoDB connection
✅ Generate secure secrets (API keys, JWT secret)
✅ Set up HTTPS in production
✅ Configure domain URL
✅ (Optional) Set up ntfy.sh for notifications

📊 Analytics & Tracking

What We Track

🗺️ Geographic Data: Country, region, city, coordinates
💻 Device Information: Browser, OS, device type
🔄 User Behavior: Referrer, language preferences, visit patterns
🕒 Temporal Data: Visit timestamps, return visitor analysis
🤖 Bot Detection: Automatic filtering of non-human traffic

Tracking Features

⚙️ Tracking Toggle: Enable/disable tracking per link
🔔 Notification Control: Enable/disable click notifications per link

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Report Bugs: Open an issue with details
💡 Feature Requests: Suggest new functionality
🔧 Code Contributions: Fork, branch, code, test, PR
📖 Documentation: Improve docs and examples
🧪 Testing: Add tests and improve coverage

Development Setup

# Clone and setup
npm install
npm run dev

📄 License

This project is licensed under the ISC License.

🆘 Support

📚 Documentation: Check API_DOCUMENTATION.md
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: Create an issue for direct contact

⭐ Star this repository if you find it useful! ⭐

Made with ❤️ by dhivijit

🏠 Home • 📖 Docs • 🐛 Issues • 🚀 Releases

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
docs		docs
public		public
views		views
.env.example		.env.example
.gitignore		.gitignore
404.html		404.html
README.md		README.md
adminDash.html		adminDash.html
dhivijit.svg		dhivijit.svg
login.html		login.html
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js
vercel.json		vercel.json

dhivijit/LinkShortner

Folders and files

Latest commit

History

Repository files navigation