Merge pull request #5 from recursivezero/features/RTY-260001

feat: add FastAPI backend and API documentation

Author: recursivezero

.env.local

@@ -1 +1,6 @@
-MONGO_URI=mongodb://admin:1234@127.0.0.1:27017/?retryWrites=true&w=majority
+DOMAIN="https://rzro.link"
+PORT=8001
+API_VERSION="/api/v1"
+
+MONGO_URI="mongodb://localhost:27017/?retryWrites=true&w=majority&appName=tiny"
+DATABASE_NAME="tiny"

.poetryignore

@@ -0,0 +1,41 @@
+# Ignore Python cache and venv
+
+**pycache**/
+_.py[cod]
+_.so
+\*.egg-info/
+.venv/
+venv/
+env/
+
+## Ignore build output
+
+build/
+dist/
+_.egg
+_.whl
+
+## Ignore IDE/editor settings
+
+.vscode/
+.idea/
+_.swp
+_.bak
+
+## Ignore local config and test logs
+
+.env
+.env.\*
+\*.log
+
+## Ignore test data/output
+
+tests/
+_.test._
+debug*\*.py
+trace*\*.py
+
+## Ignore OS files
+
+.DS_Store
+Thumbs.db

README.md

@@ -1,6 +1,6 @@
-# 🔗 Short URL Generator
+# 🔗 tiny URL Generator
 
-> A modern, Bitly-style URL shortening web application built with Flask & MongoDB\_
+> A modern, Bitly-style tiny URL web application built with Flask, FastAPI & MongoDB
 
 ![Python](https://img.shields.io/badge/Python-3.10-blue.svg)
 ![Flask](https://img.shields.io/badge/Flask-Web%20Framework-black.svg)
@@ -12,21 +12,13 @@
 
 ## 📌 Overview
 
-**Short URL Generator** is a sleek, fast and modern URL shortening platform built using Flask and MongoDB.  
+**tiny URL** is a sleek, fast, and modern URL shortening platform built using **Flask**, **FastAPI**, and **MongoDB**.  
 It converts long URLs into short, shareable links — just like Bitly.
 
-It supports:
+The project supports both:
 
-- URL shortening
-- QR Code generation (Short URL or Original URL)
-- Visit counting
-- MongoDB database
-- JSON import/export (Admin Panel)
-- Input validation + sanitization
-- Light/Dark Mode with memory
-- Glassmorphism UI
-- Copy-to-clipboard button
-- Delete confirmation popup
+- 🌐 **Flask Web UI** (end users)
+- 🚀 **FastAPI REST API** (developers / integrations)
 
 ---
 
@@ -35,26 +27,27 @@ It supports:
 ### 🔹 User Features
 
 - Convert long URLs into short, unique codes
-- default checkbox QR code generation
+- Default checkbox QR code generation
 - Clean Bitly-style result card
-- Download URl button
-- share URL
+- Download URL button
+- Share URL
 - Copy button with animation
 - Smooth URL validation and sanitization
 - Auto Dark/Light Mode (saves preference)
 - Mobile-friendly QR Codes
 - Fully responsive design
-- Recent Table
+- Recent URLs page
+- Glassmorphism UI
+
+---
 
-### 🔹 Admin Panel Features
+### 🔹 API & Developer Features
 
-- View all shortened URLs
-- Delete URLs (with confirmation popup)
-- Import URLs using JSON file
-- Export database to JSON
-- Shows JSON format guide
-- Strict JSON validation
-- Recent Table
+- REST API for URL shortening
+- API version endpoint
+- Swagger / OpenAPI documentation
+- API landing page
+- CLI to run UI or API independently
 
 ---
 
@@ -82,56 +75,55 @@ def generate_code(length=6):
 
 🗃️ Tech Stack
 
-| Layer        | Technology                               |
-| ------------ | ---------------------------------------- |
-| Backend      | Flask (Python)                           |
-| Database     | MongoDB                                  |
-| Frontend     | HTML, CSS (Glassmorphism), Vanilla JS    |
-| QR Generator | `qrserver.com` API                       |
-| Hosting      | Local / PythonAnywhere / Render / Heroku |
-| Component    | Technology                               |
-| UI Style     | Glassmorphism, Gradient UI               |
-| Data Format  | JSON                                     |
+| Layer       | Technology                 |
+| ----------- | -------------------------- |
+| UI Backend  | Flask                      |
+| API Backend | FastAPI                    |
+| Database    | MongoDB                    |
+| Frontend    | HTML, CSS, Vanilla JS      |
+| UI Style    | Glassmorphism, Gradient UI |
+| API Server  | Uvicorn                    |
+| Validation  | Pydantic v2                |
+| CLI         | Click                      |
+| Data        | JSON                       |
 
 📁 Project Folder Structure
 
 ```text
+Directory structure:
+tiny/
 ├── CHANGELOG.md
 ├── LICENSE
 ├── README.md
 ├── app/
-│   ├── __init__.py
-│   ├── admin.py
-│   ├── api/
-│   │   ├── __init__.py
-│   │   └── fast_api.py
+│   ├──__init__.py
 │   ├── app.py
-│   ├── assets/
-│   │   └── images/
 │   ├── cli.py
+│   ├── api/
+│   │   └── fast_api.py
+|   ├──assets/images
 │   ├── db/
-│   │   ├── __init__.py
-│   │   └── data.py
-│   ├── qr.py
+|   |    └──__init__.py
+|   |     └──data.py
+│   ├── utils/
+|   |     └──__init__.py
+|   |     └──_version.py
+|   |     └── helper.py
+|   |     └── lint.py
 │   ├── static/
-│   │   ├── images/
-│   │   │   ├── logo.png
-│   │   └── style.css
-│   ├── templates/
-│   │   ├── admin.html
-│   │   ├── coming-soon.html
-│   │   ├── index.html
-│   │   └── recent.html
-│   └── utils/
-│       ├── __init__.py
-│       ├── helper.py
-│       └── lint.py
-├── mypy.ini
-├── package.json
-├── poetry.lock
+|   |     └── images
+|   |      └── qr
+│   └── templates/
+|           └── index.html
+|           └── recent.html
+|           └── admin.html
 ├── pyproject.toml
-├── requirements.txt
-└── tiny.code-workspace
+|    └── poetry.lock
+├──README.md
+|    └── CHANGELOG.md
+|    └── requirements.txt
+├── tiny.code-workspace
+└── .gitignore
 
 ```
 
@@ -167,67 +159,80 @@ open [http://localhost:8000](http://127.0.0.1:8000)
 
 🔗 How the App Works
 ▶️ User Flow
+1.User enters a long URL
+
+2.System sanitizes + validates input
 
-User enters a long URL
+3.Generates a unique short code
 
-System sanitizes + validates input
+4.Saves it in MongoDB
 
-Generates a unique short code
+5.Displays short URL + QR code
 
-Saves it in MongoDB
+5.Clicking the short URL:
 
-Displays short URL + QR code
+- Increases visit count
 
-When someone clicks the short link →
+- Redirects to original URL
 
-Visit count increases
+## 🔌 REST API (FastAPI)
 
-User redirected to original URL <http://127.0.0.1:5000/abc123> Someone clicks it → visit count increases → redirected to original URL
+Tiny provides a FastAPI-based REST API for programmatic URL shortening.
 
-🧩 Short Code Generation Algorithm
+▶ Run API Server
+
+```sh
+poetry run tiny api
+```
 
-Uses characters: a–z, A–Z, 0–9
+📍 API Base URL
 
-Random 6-character string
+open [http://localhost:8001](http://127.0.0.1:8001)
 
-Ensures uniqueness by checking database
+🌙 tiny API Landing Page
 
-If code exists → generate again
+open [http://localhost:8001](http://127.0.0.1:8001)
 
-Saves final unique code
+📘 Swagger Docs
 
-🗄️ Database Schema (SQLAlchemy Model)
+open [http://localhost:8001/docs](http://127.0.0.1:8001/docs)
 
-| Field        | Type      | Description        |
-| ------------ | --------- | ------------------ |
-| id           | Integer   | Primary Key        |
-| short_code   | String    | Unique short ID    |
-| original_url | String    | Long URL           |
-| created_at   | DateTime  | Timestamp          |
-| visit_count  | Integer   | Click count        |
-| meta         | JSON Text | Title, notes, tags |
+➤ Shorten URL
 
-📦 JSON Import Format (Admin)
+POST `/api/shorten`
 
-Example JSON file for bulk import:
+Request:
 
-[
+```json
 {
-"short_code": "abc123",
-"original_url": "https://example.com",
-"created_at": "2025-11-18T23:59:00Z",
-"visit_count": 42,
-"meta": {
-"title": "Example Page",
-"notes": "Optional notes",
-"tags": ["test", "demo"]
+  "url": "https://example.com"
 }
+```
+
+Response:
+
+```json
+{
+  "input_url": "https://examplecom",
+  "output_url": "http://127.0.0.1:8001/AbX92p",
+  "created_on": "2026-01-03T13:25:10+00:00"
 }
-]
+```
+
+➤ API Version
 
-📤 Export Format
+GET `/api/version`
+
+Response:
+
+```json
+{
+  "version": "0.0.1"
+}
+```
 
-Admin can download all URLs in the same JSON format.
+📜Docs
+[run_with_curl](run_with_curl)
 
 Screenshots:
 Home Page:
@@ -236,9 +241,9 @@ Home Page:
 ![home page](app/assets/images/valid.png)
 ![home layout](app/assets/images/short_url.png)
 ![recent](app/assets/images/recent.png)
-Admin Page:
-![admin](app/assets/images/admin.png)
-![Jsonformat](app/assets/images/admin2.png)
+tiny API Page:
+![API](app/assets/images/API_page.png)
+![API1](app/assets/images/api_page2.png)
 
 📜License
 [License](LICENSE)

app/__init__.py

@@ -0,0 +1,3 @@
+from app.utils._version import get_version
+
+__version__ = get_version()

app/api/__init__.py

@@ -0,0 +1,3 @@
+from app.utils._version import get_version
+
+__version__ = get_version()