# minxa.lol – URL Shortener

<p align="center">
  <img src="logo.png" alt="minxa.lol logo" width="300" height="300" />
</p>

**minxa.lol** is a lightweight and modern URL shortening service built with **FastAPI** and **React**. It transforms long URLs into compact, unique shortcodes and offers instant redirection.

---

## ✨ Features

* 🔗 Shorten long URLs to human-friendly shortcodes
* 🚀 Redirects that are fast and reliable
* 🖥 Frontend with React, TypeScript, Tailwind CSS
* ⚙️ Environment-based configuration
* 🔐 Validation and error handling out of the box
* 🧩 Modular backend with Hashids encoding

---

## 🧰 Tech Stack

### Backend

* **FastAPI** – Async-first Python web framework
* **SQLAlchemy (async)** – ORM for PostgreSQL
* **Hashids** – Generates non-sequential codes
* **Alembic** – DB migrations
* **Uvicorn** – ASGI server

### Frontend

* **React** + **Vite** – Fast SPA setup
* **Redux Toolkit** – State management
* **Tailwind CSS** – Modern utility styling
* **TypeScript** – Typed components

---

## 🚀 How to Run (Docker)

### 1. Clone the Repository

```bash
git clone https://gitea.redturtle.foo/crayonix/minxa.lol.git
cd minxa.lol
```

### 2. Generate Environment Files

Use the helper script to generate `.env` files for both the frontend and backend:

```bash
python generate_configs.py
```

This will auto-populate required environment variables based on example templates.

### 3. Start the Project with Docker Compose

```bash
docker compose -f docker-compose.generated.yml up --build -d
```

Docker will spin up both frontend and backend containers with the correct configuration.

### 4. Access the App

* Frontend: [http://localhost:3000](http://localhost:3000)
* Backend API: [http://localhost:8000](http://localhost:8000)

Ensure Docker is installed and running on your machine before executing these steps.

---

## 📁 Project Structure

```
minxa.lol/
├── backend/
│   ├── db/            # DB connection
│   ├── models/        # SQLAlchemy models
│   ├── routes/        # FastAPI routers
│   ├── schemas/       # Pydantic schemas
│   ├── services/      # Business logic
│   └── utils/         # Encoding, helpers
│
├── frontend/
│   ├── src/
│   │   ├── api/       # API layer
│   │   ├── app/       # Redux store
│   │   ├── features/  # Feature slices
│   │   ├── pages/     # React pages
│   │   └── utils/     # Client utilities
│
└── generate_configs.py  # Env setup script
```

---

## 📄 License

Licensed under the FUTO Source Available License. See the [LICENSE](./LICENSE) file for details.

---

## 🤝 Contributing

Pull requests are welcome. For major changes, open an issue first to discuss improvements or features.