Store Intelligence Backend

Overview

Store Intelligence Backend is a FastAPI-based analytics platform for processing retail store events and generating actionable business insights.

The system supports:

• Event ingestion
• Store metrics computation
• Funnel analytics
• Heatmap analytics
• Anomaly detection
• Health monitoring
• Docker deployment

The project also includes a computer vision pipeline that processes CCTV footage, tracks visitors, and generates structured store events.

---

Architecture

CCTV Videos
      |
      v
YOLOv8 Detection
      |
      v
Multi-Object Tracking
      |
      v
Event Generation
      |
      v
FastAPI Ingestion API
      |
      v
SQLite Database
      |
      +--------------------+
      |                    |
      v                    v
Analytics APIs      Monitoring APIs

---

Architecture Diagram

The complete system architecture is available in:

docs/architecture.png

---

Tech Stack

Backend

• FastAPI
• SQLAlchemy
• SQLite
• Pydantic

Computer Vision

• YOLOv8
• OpenCV
• Supervision

Deployment

• Docker
• Docker Compose

---

Project Structure

project/
│
├── app/
│   ├── main.py
│   ├── ingestion.py
│   ├── metrics.py
│   ├── funnel.py
│   ├── heatmap.py
│   ├── anomalies.py
│   ├── health.py
│   ├── database.py
│   └── models.py
│
├── pipeline/
│   ├── detect.py
│   ├── detect_visual.py
│   ├── track_cam3.py
│   ├── generate_events_cam1.py
│   └── push_events.py
│
├── output/
│
├── docs/
│
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

---

Running Locally

Create Virtual Environment

python -m venv venv

Activate

Windows PowerShell:

.\venv\Scripts\Activate.ps1

Install Dependencies

pip install -r requirements.txt

Start API

uvicorn app.main:app --reload

Open:

http://127.0.0.1:8000/docs

---

Running With Docker

Build and start:

docker compose up --build

Open:

http://127.0.0.1:8000/docs

---

Running the Detection Pipeline

The detection pipeline converts CCTV footage into structured behavioural events.

1. Run Person Detection

python pipeline/detect.py

2. Generate Detection Video with Bounding Boxes

python pipeline/detect_visual.py

3. Run Tracking

python pipeline/track_cam3.py

4. Generate Events from CCTV

python pipeline/generate_events_cam1.py

Generated events are saved at:

output/events.jsonl

5. Push Generated Events to API

First start the API:

docker compose up --build

Then in another terminal run:

python pipeline/push_events.py

This sends events from:

output/events.jsonl

to:

POST /events/ingest

---

API Endpoints

Health

GET /health

Returns service health status and database connectivity.

---

Event Ingestion

POST /events/ingest

Stores incoming store events.

---

Metrics

GET /stores/{store_id}/metrics

Returns:

• Total events
• Unique visitors
• Entries
• Exits
• Conversion rate
• Queue depth
• Average dwell time
• Abandonment rate

---

Funnel Analytics

GET /stores/{store_id}/funnel

Returns visitor funnel metrics.

---

Heatmap Analytics

GET /stores/{store_id}/heatmap

Returns zone popularity information.

---

Anomaly Detection

GET /stores/{store_id}/anomalies

Returns operational anomalies.

---

Sample Results

Processed Store:

STORE_001

Generated Analytics:

• Total Events: 64
• Unique Visitors: 20
• Entries: 20
• Exits: 18
• Heatmap Analytics across multiple store zones
• Automatic anomaly detection
• Visitor dwell-time computation

---

Assessment Deliverables

This submission includes:

• FastAPI backend services
• Event ingestion pipeline
• Store analytics APIs
• Funnel analytics
• Heatmap analytics
• Anomaly detection
• Health monitoring APIs
• SQLite persistence layer
• Dockerized deployment
• Computer vision event generation pipeline
• System design documentation
• Architecture diagram

---

Testing

The project includes automated unit tests for core analytics and monitoring functionality.

Run Tests

pytest

Current Test Status

5 tests passing

Test Coverage

The test suite validates:

• Store metrics computation
• Unique visitor counting
• Staff exclusion logic
• Average dwell time calculations
• Queue depth extraction
• Conversion drop detection
• Billing queue spike detection
• Health monitoring endpoint

Example Output

=================== test session starts ===================

collected 5 items

tests/test_anomalies.py ..       [40%]
tests/test_health.py .           [60%]
tests/test_metrics.py ..         [100%]

==================== 5 passed ====================

The tests use isolated in-memory SQLite databases to ensure deterministic and repeatable execution without affecting production data.

Future Improvements

• Multi-camera identity matching
• Queue estimation
• Real-time event streaming
• Interactive dashboard
• Advanced conversion analytics
• Product-level shopper journey analysis

---

Author

Soumya Verma

B.Tech Final Year

Madan Mohan Malaviya University of Technology

Store Intelligence Assessment Submission