https://github.com/recursivezero/tiny
URL Shortner project
https://github.com/recursivezero/tiny
Last synced: 4 months ago
JSON representation
URL Shortner project
- Host: GitHub
- URL: https://github.com/recursivezero/tiny
- Owner: recursivezero
- License: mit
- Created: 2025-12-17T12:48:45.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T19:51:43.000Z (4 months ago)
- Last Synced: 2026-02-13T20:34:11.022Z (4 months ago)
- Language: HTML
- Size: 7.76 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
README
# Tiny URL Generator
> A modern, Bitly-style tiny URL web application built with FastAPI, optional MongoDB, and a sleek web UI.
![MongoDB]()
---
## Overview
Tiny URL is a sleek, fast, and modern URL shortening platform built using FastAPI with optional MongoDB persistence.
It converts long URLs into short, shareable links — just like Bitly.
The project supports:
- Web UI (FastAPI + Jinja templates)
- REST API (FastAPI)
- Offline Mode (No MongoDB required)
This project is designed with:
- Clean startup lifecycle (no racing configs)
- Optional database dependency
- Graceful degradation when MongoDB is unavailable
- In-memory cache fallback
- QR code generation with auto folder creation
---
## Features
### User Features
- Convert long URLs into short, unique codes
- Default checkbox QR code generation
- Clean Bitly-style result card
- Copy & share buttons
- Download URL button
- URL validation and sanitization
- Fully responsive UI
- Recent URLs page (when DB is available)
- Visit count tracking (when DB is available)
- QR image auto-generation with logo
- Cache-accelerated redirects
### API & Developer Features
- REST API for URL shortening
- API version endpoint
- Swagger / OpenAPI documentation
- API landing page
- Cache layer for fast redirects
- Graceful offline mode (no DB required)
- Clean startup lifecycle using FastAPI lifespan
- Optional MongoDB dependency
---
## Short Code Generation Algorithm
The app uses a Random Alphanumeric Short Code Generator.
### Algorithm Details
- Uses `string.ascii_letters + string.digits`
- Randomly picks characters
- Generates a 6-character short ID
- Checks MongoDB for collisions (if DB is enabled)
- Automatically regenerates on collision
### Example
```python
import random, string
def generate_code(length=6):
chars = string.ascii_letters + string.digits
return ''.join(random.choice(chars) for _ in range(length))
```
---
## Tech Stack
| Layer | Technology |
| ----------- | ----------------------- |
| UI Backend | FastAPI |
| API Backend | FastAPI |
| Database | MongoDB (Optional) |
| Cache | In-Memory (Python dict) |
| Frontend | HTML, CSS, Vanilla JS |
| QR Code | qrcode + Pillow |
| API Server | Uvicorn |
| Validation | Pydantic v2 |
| Env Mgmt | python-dotenv |
| Tooling | Poetry |
---
[Project Tree](./docs/tree.md)
## ⚙️ How to Run the Project Locally
`Virtual Environment Configuration`
```bash
poetry config virtualenvs.path /your/desired/path
```
## Environment Configuration
Ensure below files are configured (create if not exist) properly to run the project;
Supported env files:
- .env.development
- .env.local
- .env (production)
```text
ENV=development
DOMAIN=http://127.0.0.1:8000
MONGO_URI=mongodb://:@localhost:27017/tiny_url?authSource=tiny_url
DATABASE_NAME=tiny_url
```
## Install Dependencies
```bash
poetry lock --no-cache --regenerate
poetry install --all-extras --with dev
```
Or manually
```bash
poetry install
```
## How to Run
```bash
poetry run tiny dev
```
Access:
## Run FastAPI Server
```bash
poetry run tiny api
```
Access:
## Offline Mode (No Database)
TinyURL supports graceful offline mode.
### What works
- App starts normally
- UI loads
- Short URLs are generated
- QR codes are generated
- Redirects work from in-memory cache
### What is disabled
- Recent URLs page
- Persistent redirects after restart
- Visit count tracking
Offline Mode activates automatically when:
- MongoDB is down
- OR pymongo is not installed
- OR MONGO_URI is missing/invalid
Log message:
```
⚠️ MongoDB connection failed. Running in NO-DB mode.
```
---
## Switching Modes
### Without MongoDB
```sh
sudo systemctl stop mongod
poetry run tiny dev
```
or
```sh
poetry run pip uninstall pymongo
poetry run tiny dev
```
---
## Troubleshooting
sometimes there might be chances that virtual environment get corrupted then delete the old virtual environment and start afresh.
```sh
poetry env info
# this will provide virtual environment name
poetry env remove
```
### Mongo auth error
Encode special chars:
@ ? %40
Example:
```
MONGO_URI=mongodb://user%40gmail.com:Pass%40123@localhost:27017/tiny_url?authSource=tiny_url
```
---
## WSL Notes
```sh
sudo systemctl start mongod
poetry run tiny dev
```
## Build & Packaging
## Build Package
```bash
poetry clean
poetry build
```
Artifacts in `dist/`
- tiny-x.y.0-py3-none-any.whl
- tiny-x.y.0.tar.gz
## Test Locally
```bash
python -m venv .venv-dist
source .venv-dist/bin/activate
# Windows
.venv-dist\Scripts\activate
```
### Install package
```bash
pip install dist/*.whl
pip install --upgrade dist/*.whl
```
## License
📜Docs
[run_with_curl](docs/run_with_curl)
Screenshots:
Home Page:
tiny API Page:
No DB Mode:
📜License
[MIT](LICENSE)