README.md

---
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

<div align="center">

![Dynamic QR Logo](https://img.shields.io/badge/Dynamic--QR-green?style=for-the-badge&logo=qr-code&logoColor=white)

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com)
[![HuggingFace](https://img.shields.io/badge/🤗%20HuggingFace-Spaces-yellow.svg)](https://huggingface.co/spaces/parthmax/dynamic-qr)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

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

[🚀 Live Demo](https://huggingface.co/spaces/parthmax/dynamic-qr) • [📖 Documentation](#documentation) • [🛠️ Installation](#installation) • [📊 API Reference](#api-reference)

</div>

---

## 🌟 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](https://huggingface.co/spaces/parthmax/dynamic-qr)

### Option 2: Local Installation

#### 1. Clone the Repository
```bash
git clone https://github.com/parthmax2/dynamic-qr.git
cd dynamic-qr
````

#### 2. Setup Virtual Environment

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

#### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

#### 4. Run the Server

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

👉 Visit [http://127.0.0.1:8000](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

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

#### Redirect Scan

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

#### Get QR Image

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

#### Get QR Metadata

```bash
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

```json
{
  "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](LICENSE) file for details.

---

## 👤 Author

**Saksham Pathak** ([@parthmax2](https://github.com/parthmax2))
Generative AI Engineer | AI Apps & Developer Tools

---

<div align="center">

**[⭐ Star this repo](https://github.com/parthmax2/dynamic-qr)** if you find it useful!

Made with ❤️ by [parthmax](https://github.com/parthmax2)

</div>
```