chore: add READMEs for clarity
This commit is contained in:
166
README.md
166
README.md
@@ -1,130 +1,110 @@
|
||||
# minxa.lol URL Shortener
|
||||
# minxa.lol – URL Shortener
|
||||
|
||||
minxa.lol is a lightweight and efficient URL shortening service built with **FastAPI**, **SQLAlchemy**, and **Hashids**. It converts long URLs into short, shareable codes and provides redirection to the original URLs.
|
||||
<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
|
||||
## ✨ Features
|
||||
|
||||
* 🔗 Shorten URLs into unique shortcodes
|
||||
* 🚀 Redirect to original URLs using the shortcode
|
||||
* ✅ Validates shortcode format
|
||||
* 🛠 Built with modern async Python stack
|
||||
* 🧂 Configurable encoding via `hashids`
|
||||
* 🔗 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
|
||||
## 🧰 Tech Stack
|
||||
|
||||
* FastAPI
|
||||
* SQLAlchemy (async + sync)
|
||||
* PostgreSQL
|
||||
* Hashids
|
||||
* Alembic (for migrations)
|
||||
* Pydantic / Pydantic Settings
|
||||
* Uvicorn (ASGI server)
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
## 🚀 How to Run (Docker)
|
||||
|
||||
### 1. Clone the repository
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/minxa.git
|
||||
cd minxa
|
||||
git clone https://github.com/yourusername/minxa.lol.git
|
||||
cd minxa.lol
|
||||
```
|
||||
|
||||
### 2. Create and configure your environment file
|
||||
### 2. Generate Environment Files
|
||||
|
||||
Copy the example file and update it with your local settings:
|
||||
Use the helper script to generate `.env` files for both the frontend and backend:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
python generate_configs.py
|
||||
```
|
||||
|
||||
Required variables in `.env`:
|
||||
This will auto-populate required environment variables based on example templates.
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/minxa
|
||||
ENVIRONMENT=dev
|
||||
HASHIDS_SALT=your-secret-salt
|
||||
ENCODER_ALPHABET=abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
|
||||
```
|
||||
|
||||
### 3. Install dependencies
|
||||
### 3. Start the Project with Docker Compose
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
docker compose -f docker-compose.generated.yml up --build -d
|
||||
```
|
||||
|
||||
### 4. Run the application
|
||||
Docker will spin up both frontend and backend containers with the correct configuration.
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --reload
|
||||
### 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
## 📄 License
|
||||
|
||||
### `POST /`
|
||||
|
||||
Create a new shortened URL.
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"shortcode": "abc123",
|
||||
"url": "https://example.com"
|
||||
}
|
||||
```
|
||||
Licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
|
||||
|
||||
---
|
||||
|
||||
### `GET /{shortcode}`
|
||||
## 🤝 Contributing
|
||||
|
||||
Redirects to the original URL associated with the given shortcode.
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
curl -v http://localhost:8000/abc123
|
||||
```
|
||||
|
||||
Returns a `302` redirect to the original URL.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
app/
|
||||
├── main.py # FastAPI entry point
|
||||
├── config.py # Environment and settings
|
||||
├── database.py # Database setup
|
||||
├── models/ # SQLAlchemy models
|
||||
├── routes/ # API endpoints
|
||||
├── services/ # URL logic
|
||||
├── schemas/ # Pydantic schemas
|
||||
├── utils/ # Encoder logic using hashids
|
||||
├── exceptions.py # Custom exceptions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Notes
|
||||
|
||||
* Database tables auto-create in development mode
|
||||
* Encoder uses Hashids for deterministic, unique shortcodes
|
||||
* Uses `pydantic` for validation and FastAPI's dependency injection
|
||||
* Alembic is available for database migrations
|
||||
Pull requests are welcome. For major changes, open an issue first to discuss improvements or features.
|
||||
|
||||
Reference in New Issue
Block a user