Link-Shortener

Project Name

Link Shortener

Project Description

Link Shortener is a full-stack application that provides a high-performance URL shortening engine with custom vanity slugs and click telemetry analytics, alongside a customizable "Link-in-Bio" hub manager for creator profile pages.

Key capabilities:

• URL Shortening & Redirection: Generates unique 6-character short codes or accepts custom vanity slugs (e.g., /r/summer-sale). When visited, returns an immediate HTTP 302 redirect while asynchronously recording click telemetry.
• Click Telemetry & Analytics: Captures timestamp, HTTP referrer, device classification (Mobile, Desktop, Tablet), and SHA-256 hashed IP for unique visitor metrics.
• Link Library Studio: Management table featuring search, pagination, one-click copy, QR code generation with download, and deletion.
• Link-in-Bio Hub: Visual profile customizer with display name, bio, avatar, and 3 selectable themes (Minimal Light, Dark Slate, Gradient) with a live mobile mockup preview. Renders public mobile-responsive routes at /bio/:username.
• Auto-Shortened Bio Links: Custom link buttons added in the bio builder are automatically converted to tracked short links and synced with the analytics dashboard.
• Security: Pair-token authentication using short-lived JWT access tokens (15m) and long-lived refresh tokens (7d) in httpOnly cookies with token rotation, email verification simulation, and rate limiting.

Technology Stack Used

• Python 3.12: Core programming language.
• FastAPI: Asynchronous web framework for high-throughput 302 redirects, background telemetry tasks, and REST APIs.
• Pydantic v2: Request validation and data serialization.
• SQLite: Relational database engine for lightweight local storage without requiring external database servers.
• SQLAlchemy 2.0 (Async / aiosqlite): Asynchronous ORM for database operations and models.
• PyJWT: Generation and verification of short-lived access tokens and long-lived refresh tokens.
• Bcrypt: Password salting and hashing.
• user-agents: User-Agent string parser for device and browser classification.
• HTML5 & CSS: Responsive UI built with Plus Jakarta Sans and JetBrains Mono.
• Chart.js: Interactive time-series and device breakdown analytics charts.
• QRCode.js: Client-side QR code rendering and download.

How to Install Dependencies

1. Clone the repository and navigate to the project root:

   git clone https://github.com/KunalGupta25/Link-Shortener.git
   cd Link-Shortener
   

2. Create and activate a Python 3.12 virtual environment:

   • On Windows:

     py -3.12 -m venv .venv
     .\.venv\Scripts\Activate.ps1
     

   • On Linux / macOS:

     python3.12 -m venv .venv
     source .venv/bin/activate
     

3. Install the required dependencies:

   pip install -r requirements.txt
   

How to Configure Environment Variables

1. Copy the sample environment file to create .env:

   cp .env.example .env
   

2. Available environment variables in .env:

   • JWT_SECRET: Secret key used for signing JWT access and refresh tokens (e.g. super-secret-shortlink-biolink-hub-key-2025).
   • DATABASE_URL: Connection string for the SQLite database (defaults to sqlite+aiosqlite:///./combot.db).

The default values in .env.example work out-of-the-box for local execution.

How to Run the Project Locally

1. Ensure your virtual environment is activated.

2. Start the server using the runner script:

   python run.py
   

   Or run directly with Uvicorn:

   uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
   

3. Open the application in your browser:

   • Dashboard & Studio: http://127.0.0.1:8000
   • Swagger API Documentation: http://127.0.0.1:8000/docs
   • Public Bio Profiles: http://127.0.0.1:8000/bio/{username}

Database Setup, if Required

No manual database setup or external database server installation is required.
The application automatically creates the SQLite database file (combot.db) and all required tables (users, refresh_tokens, links, click_events, bio_profiles) upon application startup via SQLAlchemy metadata initialization.

Any Assumptions or Limitations

• Email Verification & Password Reset: Implemented in simulation mode. Verification codes (6 digits) and reset tokens are generated, saved, and displayed in banner callouts so evaluators can test full flows without setting up a third-party SMTP server.
• Single-Node Storage & Limiting: In-memory rate limiting and local SQLite storage are used for zero-friction local evaluation without external Redis or PostgreSQL dependencies.
• Production Enhancements: In a distributed multi-instance deployment, short-link lookups would be cached in Redis with an LRU policy, rate limits stored in Redis, and simulated emails replaced with actual SMTP dispatch via AWS SES or SendGrid.