minxa.lol – URL Shortener
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
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:
python generate_configs.py
This will auto-populate required environment variables based on example templates.
3. Start the Project with Docker Compose
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
- Backend API: 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 file for details.
🤝 Contributing
Pull requests are welcome. For major changes, open an issue first to discuss improvements or features.