Visionvend - GitLite

KO | EN

gitlite — search

#awesome #golang #linux #machine-learning #mysql #framework #video #pdf #docker #vue

Visionvend

(★ 10)

No description available.

File Explorer

ZIP Download

- - app.cpython-313.pyc
- - db_manager.py
  - fallback_visionvend.db
  - schema.sql
- - alerts.py
  - inventory.py
  - prediction.py
- - aqua_30.jpg
  - mix_30.jpg
  - pepsodent_20.jpg
  - shampoo_18.jpg
  - shampoo_40.jpg
  - test_shelf.jpg
  - tissue_4.jpg
  - tissue_5.jpg
  - tissue_9.jpg
  - web_slot_1.png
- - detector.py
- .env
- .env.example
- app.py
- package.json
- requirements.txt
- - favicon.svg
  - icons.svg
- - App.css
  - App.jsx
  - index.css
  - main.jsx
- .gitignore
- eslint.config.js
- index.html
- package-lock.json
- package.json
- postcss.config.js
- README.md
- tailwind.config.js
- vite.config.js
package.json
README.md
SETUP_GUIDE.md
start.bat
test_shelf.jpg

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**AI-powered shelf monitoring and inventory automation, built on YOLOv8 computer vision.**

VisionVend turns a simple photo of a retail shelf into a live inventory count. Upload an image, let the detection engine identify and count products, and watch stock levels, low-stock alerts, and analytics update automatically on a real-time dashboard.

---

## Overview

VisionVend is a full-stack SaaS-style application made up of three pieces:

- **A YOLOv8 detection engine** that scans shelf images, draws bounding boxes around recognized products, and counts units per category.
- **A Flask REST API** that runs inference, persists stock levels, and raises low-stock/out-of-stock alerts.
- **A React (Vite) + Tailwind dashboard** for uploading shelf photos, browsing inventory, managing stock manually, and reviewing alert history.

The system is designed to run out of the box: if no trained model weights are present, it automatically falls back to a realistic demo detector, and if MySQL isn't available, it transparently switches to a local SQLite database. This means you can clone the repo and have a fully working demo running in minutes, with no ML pipeline or database setup required.

## Architecture

```mermaid
graph TD
    A[React Client Web App] -->|1. Upload Image / JSON Update| B[Flask Server API :5000]
    B -->|2. Runs YOLOv8 Inference| C{detector.py}
    C -->|If best.pt found| D[Real YOLOv8 Detection]
    C -->|If Roboflow API key set| R[Roboflow Hosted Inference]
    C -->|If weights missing / no PyTorch| E[Mock Demo Engine]
    B -->|3. Save Annotated Image| F[static/results/output.jpg]
    B -->|4. Push counts & check thresholds| G{db_manager.py}
    G -->|Connected| H[MySQL Database]
    G -->|Fallback| I[SQLite fallback_visionvend.db]
    B -->|5. Return annotated path & counts| A
```

## Features

- **Drag-and-drop product detection** — upload a PNG/JPG/JPEG/WEBP shelf photo and get an annotated image back with bounding boxes, per-product counts, and confidence scores.
- **Three detection modes** — real YOLOv8 inference from a local `best.pt` model, hosted inference via the Roboflow API, or a built-in mock engine for zero-setup demos.
- **Live inventory dashboard** — stock-by-category bar chart, distribution pie chart, and shelf fill-rate area chart, auto-refreshing every 12 seconds.
- **Inventory manager** — searchable, filterable stock table with inline quantity editing and stock-status badges (In Stock / Low Stock / Out of Stock).
- **Automated alerts engine** — stock updates automatically raise "Low Stock" or "Out of Stock" alerts (threshold of 10 units) and auto-resolve once restocked, viewable in an Active/Resolved alert log.
- **CSV report export** — download a detection run's product counts and confidence scores directly from the scanner page.
- **Resilient by design** — automatic SQLite fallback if MySQL isn't reachable, and a mock detection engine if no trained model or inference API is configured.

## Tech Stack

| Layer | Technology |
|---|---|
| Frontend | React 19, Vite, Tailwind CSS, React Router, Recharts, Axios, Lucide Icons |
| Backend | Flask 3, Flask-CORS, python-dotenv |
| Computer Vision | Ultralytics YOLOv8, OpenCV, Pillow, NumPy, optional Roboflow Hosted Inference |
| Database | MySQL (primary), SQLite (automatic fallback) |

## Project Structure

```
Visionvend/
├── backend/
│   ├── app.py                  # Flask app factory & entry point
│   ├── routes/
│   │   ├── prediction.py       # POST /predict – image upload & detection
│   │   ├── inventory.py        # GET /inventory, POST /inventory/update
│   │   └── alerts.py           # GET /alerts
│   ├── yolov8/
│   │   └── detector.py         # YOLOv8 / Roboflow / mock detection engine
│   ├── database/
│   │   ├── db_manager.py       # MySQL client with SQLite fallback
│   │   └── schema.sql          # MySQL schema (inventory, alerts)
│   ├── static/results/         # Annotated output images
│   ├── uploads/                # Uploaded source images
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/              # Landing, Dashboard, Detection, Inventory, Alerts
│   │   ├── components/         # Header, Sidebar, StatsCard, Toast
│   │   ├── layouts/             # LandingLayout, DashboardLayout
│   │   └── services/api.js     # Axios client for the Flask API
│   └── package.json
├── start.bat                   # Windows convenience launcher (backend + frontend)
└── SETUP_GUIDE.md
```

## Getting Started

### Prerequisites

- Python 3.8 – 3.11
- Node.js (LTS) and npm
- MySQL Server (optional — the app falls back to SQLite automatically if it's not running)

### 1. Clone the repository

```bash
git clone https://github.com/kanishkakumaravel07-max/Visionvend.git
cd Visionvend
```

### 2. Backend setup

```bash
cd backend
python -m venv venv

# Activate the virtual environment
venv\Scripts\activate.bat     # Windows (cmd)
.\venv\Scripts\Activate.ps1   # Windows (PowerShell)
source venv/bin/activate      # macOS / Linux

pip install -r requirements.txt
```

Create a `.env` file in `backend/` (use `.env.example` as a starting point):

```env
PORT=5000
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_NAME=visionvend
```

Optionally, enable hosted inference instead of a local model by adding:

```env
ROBOFLOW_API_KEY=your_roboflow_api_key
ROBOFLOW_PROJECT=visionvend
ROBOFLOW_VERSION=1
```

To run real local YOLOv8 inference, drop a trained `best.pt` file into `backend/yolov8/`. Without it (and without a Roboflow key), the API automatically serves results from the built-in mock detector.

Start the API:

```bash
python app.py
```

The backend runs at `http://localhost:5000`.

### 3. Frontend setup

```bash
cd frontend
npm install
npm run dev
```

The dashboard runs at `http://localhost:5173`.

### 4. (Windows) One-click start

From the project root, `start.bat` launches both the backend and frontend in separate terminal windows.

## API Reference

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Returns API status and whether it's running in `demo` or `production` mode |
| `POST` | `/predict` | Accepts a multipart `image` file, runs detection, updates inventory, returns annotated image path + product counts |
| `GET` | `/inventory` | Returns current stock levels for all tracked products |
| `POST` | `/inventory/update` | Manually sets stock for a product (`product_name`, `quantity`) |
| `GET` | `/alerts` | Returns the most recent low-stock / out-of-stock / resolved alerts |

## How Detection Mode Is Chosen

`detector.py` resolves which inference path to use, in order:

1. **Roboflow Hosted Inference** — used if `ROBOFLOW_API_KEY` is set.
2. **Local YOLOv8 model** — used if `backend/yolov8/best.pt` exists and `ultralytics` is installed.
3. **Mock Demo Engine** — used otherwise. It draws realistic bounding boxes for sample categories (Coca-Cola, Pepsi, Water Bottle, Chips Packet, Biscuit, Juice Carton) so the full app is demoable without any model or API key.

## Database Behavior

`db_manager.py` attempts to connect to MySQL using the credentials in `.env` on startup. If the connection fails for any reason, it transparently falls back to a local SQLite file at `backend/database/fallback_visionvend.db`, pre-populated with sample stock so the dashboard renders immediately. Once MySQL is reachable, the app uses it automatically on the next restart.

## License

No license file is currently included in this repository. Add one (MIT, Apache-2.0, etc.) if you intend to make this project open source.