VigilAI: Smart Surveillance Event Detection & Analysis System

Author: Prachi Maruti Patil — Vidyalankar Institute of Technology

A production-ready, multi-service AI-powered video surveillance system featuring YOLOv8 object detection, rule-based event analysis, on-demand clip generation, and an Advanced Database Management System (ADBMS) analytics dashboard.

---

🔗 Live Deployments

Service	URL	Status
🌐 Frontend (React)	https://vigil-ai-five.vercel.app	Live
⚙️ Backend (Node.js)	https://vigilai-ytg4.onrender.com	Live
🐍 Python Engine (Flask + YOLOv8)	https://vigilai-1-njnz.onrender.com	Live

---

📑 Table of Contents

1. System Architecture
2. ADBMS Concepts & Features
3. Event Types & Detection Rules
4. Quick Start — Docker
5. Quick Start — Local Dev
6. Project Structure
7. API Reference
8. Key Design Rules
9. Troubleshooting

---

🏗 System Architecture

Browser :3000 → nginx (frontend) → /api proxy → backend :4000
                                                      │
                                         ┌────────────┼─────────────┐
                                         ▼            ▼             ▼
                                     MongoDB      Python        shared
                                     :27017       :5000         volumes
                                                (Flask+YOLO)

Service Ports

Service	Port	Description
frontend	3000	React app served via nginx
backend	4000	Node.js / Express REST API
python-engine	5000	Flask + YOLOv8 + OpenCV
mongodb	27017	MongoDB 7.0 database

---

🗄 ADBMS Concepts & Features

This system incorporates several Advanced Database Management System (ADBMS) concepts to ensure efficient querying, high availability, and optimal performance at scale.

1. Indexing & Query Optimization

• Compound Indexes on event_type, video_id, and timestamp allow fast filtering across large event collections without full-table scans.
• The /api/adbms/index-comparison endpoint lets you compare query execution plans with and without indexes in real time, demonstrating measurable speedup.
• Filter parameters (min_duration, min_confidence, zone) are designed to leverage these indexes for sub-millisecond lookups.

2. Caching Layer

• NodeCache is used as an in-memory caching layer in the Node.js backend.
• Frequently accessed aggregation results (event counts, summaries, stats) are cached to avoid redundant MongoDB aggregation pipelines.
• The /api/adbms/cache-stats and /api/adbms/cache-test endpoints expose live miss → hit demonstrations, illustrating cache effectiveness.

3. Replication & Fault Tolerance

• The system is designed with MongoDB replica set concepts in mind.
• The /api/adbms/replication-test endpoint simulates primary failure and restore scenarios (fail_primary / restore), showcasing how the system maintains availability during node failure.
• /api/adbms/server-selection demonstrates read/write routing — writes go to the primary, reads can be distributed to secondaries.

4. Bulk Write Operations (Upsert Pattern)

• All events from the Python engine are committed via POST /api/events/bulk, which uses MongoDB's bulkWrite with upsert semantics.
• Event deduplication is guaranteed by a deterministic event_id = MD5(video_id:type:track:frame) hash, preventing duplicate records even on reprocessing.

5. Query Logging & Observability

• Every significant database query is logged to a QueryLog collection, recording execution time, query type, and result size.
• /api/adbms/query-logs surfaces these logs with aggregate statistics, enabling database performance monitoring over time.

6. Sequential vs. Parallel Processing

• The system supports both sequential and parallel video processing pipelines.
• /api/adbms/processing-comparison compares throughput between the two strategies, demonstrating how concurrency impacts database write patterns and overall performance.

---

🚨 Event Types & Detection Rules

Event	Trigger Condition	Priority
zone_entry	Person transitions into a defined zone polygon	3
zone_loitering	Person remains inside a zone for > 8 seconds	8
loitering	Person moves < 80 px over > 10 seconds	6
abandoned_object	Bag/object moves < 30 px over > 15 seconds	10
vehicle_stop	Vehicle speed < 2 px/frame for > 8 seconds	5
crowd_formation	3+ persons detected in a zone for > 1 second	9

---

🐳 Quick Start — Docker

Prerequisites

• Docker >= 24
• Docker Compose >= 2.20
• 8 GB RAM recommended (for YOLOv8 large model)

Run the Full Stack

docker compose up --build

First build downloads YOLOv8 weights (~87 MB) — allow 3–5 minutes.

Open http://localhost:3000 once all services are healthy.

Stop & Teardown

# Stop all containers
docker compose down

# Full teardown including volumes (resets all data)
docker compose down -v

---

💻 Quick Start — Local Dev

# 1. Start MongoDB
docker run -d -p 27017:27017 mongo:7.0

# 2. Start Python Engine (Flask + YOLOv8)
cd python-engine
pip install -r requirements.txt
python3 app.py                        # Runs on :5000

# 3. Start Backend (Node.js)
cd backend
npm install
npm run dev                           # Runs on :4000

# 4. Start Frontend (React)
cd frontend
npm install
npm start                             # Runs on :3000

---

📁 Project Structure

surveillance-system/
├── docker-compose.yml
├── README.md
│
├── backend/                          # Node.js / Express API
│   ├── Dockerfile
│   ├── .env
│   ├── server.js
│   ├── package.json
│   ├── models/
│   │   ├── Event.js
│   │   ├── Video.js
│   │   └── QueryLog.js
│   ├── routes/
│   │   ├── videos.js
│   │   ├── events.js
│   │   ├── clips.js
│   │   └── adbms.js
│   └── public/
│       ├── uploads/
│       └── clips/
│
├── python-engine/                    # Flask + YOLOv8 Processing
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── app.py                        # Flask HTTP service
│   ├── pipeline.py                   # Processing orchestrator
│   ├── rule_engine.py                # 6 event detection rules
│   ├── tracker.py                    # TrackStore + DetectionFilter
│   ├── detector.py                   # YOLOv8 + MockDetector
│   ├── models.py                     # Shared dataclasses
│   ├── backend_client.py
│   └── generate_clip.py              # On-demand clip renderer
│
└── frontend/                         # React UI
    ├── Dockerfile
    ├── nginx.conf
    ├── package.json
    └── src/
        ├── App.js
        ├── index.css
        ├── services/api.js
        └── pages/
            ├── UploadPage.js
            ├── EventsPage.js
            ├── ClipViewer.js
            └── AdbmsPage.js          # ADBMS analytics dashboard

---

📡 API Reference

Videos

Method	Endpoint	Description
POST	/api/videos/upload	Upload single video (multipart: video, zones, processing_mode)
POST	/api/videos/upload-multiple	Upload multiple videos (multipart: videos[], zones, processing_mode)
POST	/api/videos/:id/process	Start sequential processing for a video
POST	/api/videos/process-parallel	Concurrent processing ({ video_ids: [] })
GET	/api/videos	List all videos
GET	/api/videos/:id	Get single video + event count
DELETE	/api/videos/:id	Delete video and all associated events

Events

Method	Endpoint	Description
POST	/api/events/bulk	Upsert event array (called from Python engine)
GET	/api/events	List events with filters: video_id, event_type, min_duration, min_confidence, zone
GET	/api/events/:id	Get single event
GET	/api/events/stats/summary	Aggregated event counts and summaries

Clips

Method	Endpoint	Description
GET	/api/events/:id/clip	Generate or return a cached video clip
DELETE	/api/events/:id/clip	Delete a generated clip

ADBMS Analytics

Method	Endpoint	Description
GET	/api/adbms/index-comparison	Index vs. no-index query benchmark (?event_type=loitering)
GET	/api/adbms/query-logs	All query logs + aggregate stats
GET	/api/adbms/cache-stats	NodeCache hit/miss counters
GET	/api/adbms/cache-test	Live cache miss → hit demonstration
GET	/api/adbms/server-selection	Read/write routing demo (?type=read|write)
POST	/api/adbms/replication-test	Simulate replication events ({ action: "fail_primary" | "restore" })
GET	/api/adbms/processing-comparison	Sequential vs. parallel processing stats

Python Engine (Internal)

Method	Endpoint	Description
GET	/health	Liveness probe
GET	/status/:video_id	Job status for a video
POST	/process	Start processing ({ video_id, video_path, zones, backend_url })
POST	/generate-clip	Render a clip ({ event, video_path, clip_dir, clip_fname, buffer })

---

📐 Key Design Rules

Rule	Implementation
No duplicate events	event_id = MD5(video_id:type:track:frame) + MongoDB upsert
No clips generated in Python	generate_clip.py is only called when Node.js POSTs to /generate-clip
Bulk inserts only	POST /api/events/bulk → MongoDB bulkWrite upsert
Consistent clip naming	<event_id>_<clip_uuid>.mp4
Shared file volumes	shared_uploads (read-only for Python) + shared_clips (read-write for both)

---

🛠 Troubleshooting

# View logs for all services
docker compose logs -f

# Python engine is slow to start (downloading YOLOv8 weights)
docker compose logs python-engine

# Check MongoDB event count
docker compose exec mongodb mongosh surveillance \
  --eval "db.events.countDocuments()"

# List all generated clips
docker compose exec backend ls /app/public/clips

# Manual pipeline test (local, no backend required)
cd python-engine
python3 pipeline.py /path/to/video.mp4 \
  --video_id test-123 \
  --no_backend \
  --zones '[{"name":"A","polygon":[[0,0],[300,0],[300,300],[0,300]]}]'

---

🧑‍💻 Author

Prachi Maruti Patil
Vidyalankar Institute of Technology

---

Built with YOLOv8 · Flask · Node.js · React · MongoDB · Docker