ShawtyLink - The Modern SaaS URL Shortener

A powerful, self-hostable SaaS URL shortener with a premium Apple-inspired design. Built for speed, privacy, and scalability.

✨ Features (v2.2.1)

Core Features

• User System: Full SaaS architecture with Login, Register, and JWT Authentication.
• Robust Storage: Production-grade PostgreSQL with async SQLAlchemy.
• High-Speed Caching: Redis integration for zero-latency redirects.
• Premium UI/UX:
  • Cosmic Particle Background (WebGL/OGL) with parallax effect.
  • Glassmorphism architecture with dark/light mode support.
  • Fully responsive design for all devices.
  • New: Mobile Card View for better usability on small screens.
  • New: Global Toast Notifications for instant feedback.
  • New: Dynamic Domain Display (adapts to Localhost/Production).

User Dashboard

• Link Management: Full CRUD operations for your links.
• QR Code Generation: Instant QR codes for any shortened link.
• Real-time Analytics: Click tracking and statistics.
• Account Security: Self-service account deletion with password verification.

Admin Panel

• User Management: Create, edit, and delete users.
• Role Management: Assign admin/superuser roles.
• Global Analytics: Site-wide statistics dashboard.
• CSV Reports: Export user data and analytics.

---

Advanced Link Features (NEW in v2.2.0) 🎉

• Password Protection: Secure your links with password authentication.
• Unlock Page: Beautiful password entry page with show/hide toggle.
• Link Expiration: Set expiration dates for temporary links.
• Click Limits: Define maximum clicks before link deactivation.
• Custom Aliases: Choose your own short codes.

---

📝 Planned Features (Next)

• Analytics Dashboard: Detailed click analytics with graphs and geo-location data.
• Custom Domains: Support for your own branded short domains.
• QR Code Customization: Add logos and customize QR code design.
• Link Tags & Folders: Organize links with categories and folders.
• API Keys: Generate API keys for programmatic link creation.
• Webhooks: Real-time notifications for link events.
• Team Workspaces: Collaborate with team members on shared links.

---

🛠 Tech Stack

Frontend

• Framework: React 19 + Vite
• Styling: Tailwind CSS + Framer Motion
• Visuals: OGL (WebGL Particles)
• State: Context API

Backend

• Framework: FastAPI (Python 3.12+)
• Database: PostgreSQL (Async SQLAlchemy)
• Cache: Redis
• Auth: OAuth2 with Password + Bearer JWT

Infrastructure

• Containers: Docker & Docker Compose
• Server: Nginx (Alpine Linux)

---

🚀 Getting Started

Prerequisites

• Docker & Docker Compose
• Git

Installation

1. Clone the repository

   git clone https://github.com/awpetrik/ShawtyLink.git
   cd ShawtyLink

2. Configure Environment You MUST create a .env file to run the application. We have provided an example file.

   cp .env.example .env

   Open .env and fill in your secure credentials:

   # Database
   POSTGRES_USER=shawty
   POSTGRES_PASSWORD=your_secure_password
   POSTGRES_DB=shawtylink
   
   # Security
   SECRET_KEY=generate_a_very_long_random_secret_string
   ALGORITHM=HS256
   
   # Admin (Optional - for future use)
   INITIAL_ADMIN_EMAIL=admin@shawty.link
   INITIAL_ADMIN_PASSWORD=admin123

3. Run with Docker Spin up the entire stack (Frontend, Backend, Postgres, Redis, Nginx):

   docker-compose up -d --build

4. Access the Application

   • Frontend: http://localhost:1603
   • Backend API: http://localhost:8000/docs

5. Updates

To update your instance to the latest version safely (without losing data), please refer to our Deployment Guide.

---

📂 Project Structure

├── backend/
│   ├── app/
│   │   ├── routers/       # API Routes (Auth, URLs, Users)
│   │   ├── models.py      # Database Tables
│   │   ├── schemas.py     # Pydantic Models
│   │   └── database.py    # DB Connection
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/    # Reusable UI (Particles, Modals)
│   │   ├── pages/         # Dashboard, Links, Settings
│   │   └── views/         # Public Pages (Home, Login)
│   └── Dockerfile
├── docker-compose.yml     # Service Orchestration
└── .env                   # Environment Secrets (GitIgnored)

---

📝 Changelog

See CHANGELOG.md for a detailed history of changes.

---

Certified Lunatics — A Part of Rivaldi's Network