111 lines
2.8 KiB
Markdown
111 lines
2.8 KiB
Markdown
# 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.
|