README.md

metadata

title: Dynamic-QR
emoji: 🔗
colorFrom: blue
colorTo: green
sdk: docker
sdk_version: '1.0'
app_file: Dockerfile
pinned: false

Dynamic-QR: QR Code Management System

A powerful, FastAPI-based system for generating, updating, and tracking dynamic QR codes with enterprise-ready APIs.

🚀 Live Demo • 📖 Documentation • 🛠️ Installation • 📊 API Reference

---

🌟 Overview

Dynamic-QR provides a centralized system for creating and managing QR codes that can be updated anytime without re-printing.
It includes scan tracking, redirection logic, and a simple web dashboard + API interface for enterprise use cases.

---

✨ Key Features

🔗 Dynamic QR Management

• Create unique QR codes with short IDs
• Update QR destination anytime without changing the QR image
• Delete or deactivate codes when needed

📊 Analytics & Tracking

• Track scan counts in real time
• Log last scan timestamp
• Manage activity status (active/inactive)

🖥️ Dashboard & APIs

• Jinja2-powered dashboard to view all QR codes
• REST APIs for integration with other systems
• QR image generation endpoint for direct embedding

🛡️ Enterprise Ready

• CORS enabled
• Health check endpoint
• Extensible for database or authentication integration

---

🏗️ System Architecture

┌───────────────────┐     ┌────────────────────┐
│  Web Dashboard    │◄───►│   FastAPI Backend  │
│  (Jinja2)         │     │   (app.py)         │
└───────────────────┘     └─────────┬──────────┘
│
▼
┌───────────────────┐     ┌────────────────────┐
│  QR Generator     │     │   In-Memory Store  │
│  (qrcode lib)     │     │   (Dict, can use DB)│
└───────────────────┘     └────────────────────┘

---

🚀 Quick Start

Option 1: Try Online (Recommended)

Visit the live demo: 🤗 HuggingFace Spaces

Option 2: Local Installation

1. Clone the Repository

git clone https://github.com/parthmax2/dynamic-qr.git
cd dynamic-qr

2. Setup Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

3. Install Dependencies

pip install -r requirements.txt

4. Run the Server

uvicorn app:app --reload --host 0.0.0.0 --port 8000

👉 Visit http://127.0.0.1:8000

---

🎯 Usage

Web Dashboard

1. Open / to view all QR codes
2. Create a new QR by entering title + redirect URL
3. Update existing QR code targets anytime
4. Download the QR image and share

API Examples

Create QR

curl -X POST "http://localhost:8000/create" \
  -F "title=My GitHub" \
  -F "redirect_url=https://github.com/parthmax2"

Redirect Scan

curl -i "http://localhost:8000/r/{qr_id}"

Get QR Image

curl -o qr.png "http://localhost:8000/qr/{qr_id}"

Get QR Metadata

curl "http://localhost:8000/api/qr/{qr_id}"

---

📚 API Reference

Core Endpoints

Method	Endpoint	Description
GET	/	Dashboard UI
POST	/create	Create new QR
POST	/update/{qr_id}	Update QR code
GET	/r/{qr_id}	Redirect endpoint
GET	/qr/{qr_id}	Get QR PNG image
DELETE	/delete/{qr_id}	Delete QR code
GET	/api/qr/{qr_id}	Get QR metadata JSON
GET	/health	Health check

Example QR Metadata Response

{
  "id": "abc12345",
  "title": "My GitHub",
  "redirect_url": "https://github.com/parthmax2",
  "scan_count": 12,
  "created_at": "2025-08-31T10:45:00",
  "last_scanned": "2025-08-31T11:20:00",
  "is_active": true
}

---

⚙️ Configuration

Environment Variables

Variable	Description	Default
BASE_URL	Base URL used for QR redirection	https://huggingface.co/spaces/parthmax/dynamic-qr

⚠️ In production, configure BASE_URL to match your deployment domain.

---

🛠️ Development

Project Structure

dynamic-qr/
├── app.py                # Main FastAPI application
├── templates/            # Jinja2 templates (UI)
│   └── index.html
├── static/               # Static assets (CSS, JS)
├── requirements.txt      # Python dependencies
└── README.md             # Documentation

---

📊 Roadmap

• ✅ Dynamic QR CRUD
• ✅ Scan tracking
• 🔄 Persistent DB integration (SQLite/Postgres)
• 🔄 User authentication
• 🔄 Analytics dashboard with charts
• 🔄 Bulk QR generation & export

---

🔒 Security

• Input validation for URLs
• Configurable active/inactive state
• Ready for JWT auth integration
• Safe QR redirection logic

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

👤 Author

Saksham Pathak (@parthmax2) Generative AI Engineer | AI Apps & Developer Tools

---

⭐ Star this repo if you find it useful!

Made with ❤️ by parthmax

```