⚡ NexLink

A blazing-fast URL shortener with real-time analytics

Shorten. Track. Optimize.

---

Overview

NexLink is a production-ready URL shortener built with a modern Python backend and React frontend. It provides real-time click analytics, custom aliases, expiration dates, QR code generation, and a clean dashboard to monitor your links.

Built as a full-stack learning project to demonstrate REST API design, async Python, and React state management.

Features

• URL Shortening — Generate short links in milliseconds
• Custom Aliases — Choose your own slug (e.g. nex.link/my-project)
• Analytics Dashboard — Track clicks, referrers, geographic data, and devices
• QR Code Generation — Auto-generate QR codes for every link
• Link Expiration — Set TTL for temporary links
• Rate Limiting — Redis-backed rate limiting per IP
• API-first — Full REST API with OpenAPI docs at /docs

Tech Stack

Backend

• FastAPI — Async Python web framework
• SQLAlchemy — ORM with async support
• PostgreSQL — Primary database
• Redis — Caching & rate limiting
• Alembic — Database migrations

Frontend

• React 18 — UI library
• TanStack Query — Server state management
• Recharts — Analytics charts
• Tailwind CSS — Styling

DevOps

• Docker & Docker Compose
• GitHub Actions CI/CD

Project Structure

nexlink/
├── backend/
│   ├── app/
│   │   ├── api/          # Route handlers
│   │   ├── core/         # Config, security, dependencies
│   │   ├── models/       # SQLAlchemy models
│   │   ├── schemas/      # Pydantic schemas
│   │   └── services/     # Business logic
│   ├── alembic/          # DB migrations
│   └── tests/            # Pytest test suite
├── frontend/
│   ├── src/
│   │   ├── components/   # Reusable UI components
│   │   ├── pages/        # Page components
│   │   ├── hooks/        # Custom React hooks
│   │   └── lib/          # API client, utils
│   └── public/
├── docker-compose.yml
└── Makefile

Getting Started

Prerequisites: Docker & Docker Compose installed

# Clone the repo
git clone https://github.com/Alice699/nexlink.git
cd nexlink

# Copy environment variables
cp .env.example .env

# Start all services
docker compose up -d

# Run database migrations
docker compose exec backend alembic upgrade head

App will be running at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Local Development (without Docker)

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend (new terminal)
cd frontend
npm install
npm run dev

API Reference

Method	Endpoint	Description
POST	/api/v1/links	Create short link
GET	/api/v1/links	List all links
GET	/api/v1/links/{id}	Get link details
DELETE	/api/v1/links/{id}	Delete link
GET	/api/v1/links/{id}/analytics	Get click analytics
GET	/{slug}	Redirect to original URL

Running Tests

cd backend
pytest tests/ -v --cov=app --cov-report=term-missing

Roadmap

• User authentication & multi-user support
• Team workspaces
• Webhook support on click events
• Link password protection
• CSV export for analytics

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT © Robbian Saputra Gumay