From 449af6c242ceafe828eef04b4d2295db5ff7bffb Mon Sep 17 00:00:00 2001
From: Qessia <52119664+Qessia@users.noreply.github.com>
Date: Mon, 29 Jun 2026 11:38:11 +0000
Subject: [PATCH] docs: clarify project structure and data flow in README

Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 9a657f4..17de0e3 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,39 @@ This project is about videosources emergency detection made with ZeroMQ infrastr
 - OpenCV
 - Multiprocessing & Threading
 
+## Project structure
+```
+videoanalytics/
+├── run.py            # Entry point: spawns broker, workers, cameras and GUI processes
+├── broker.py         # ZeroMQ router: subscribes to cameras, fans frames out to workers
+├── cameras/
+│   └── cam.py        # Reads videosources and publishes encoded frames over ZeroMQ
+├── workers/
+│   └── worker.py     # Runs YOLO detection + PSNR per frame, pushes results to the GUI
+├── gui.py            # Pulls results, draws detections/warnings on a grid canvas
+├── config.py         # Loads config.json into a global `config` dict
+├── config.json       # Sources, workers, models, GUI address and PSNR threshold
+├── psnr.py           # CLI tool to generate meanframes for PSNR ("normal" reference)
+├── colors.py         # Standalone helper to inspect a video's color distribution
+├── requirements.txt  # Python dependencies
+├── models/           # YOLO model weights (download separately, see Preparations)
+├── videos/           # Test videos and their meanframes (download separately)
+└── media/            # Demo assets used in this README
+```
+
+### Data flow
+```
+cameras/cam.py  ──(PUB frames)──▶  broker.py  ──(PUSH frame)──▶  workers/worker.py
+                                                                      │
+                                                  (PUSH detections + PSNR)
+                                                                      ▼
+                                                                   gui.py
+```
+- **cameras/cam.py** runs one process per source, encodes frames as JPEG and publishes them.
+- **broker.py** routes each frame to the worker matching its source id.
+- **workers/worker.py** runs the fire and forklift YOLO models plus a PSNR check against the source meanframe, then forwards the annotated data.
+- **gui.py** renders every source in a grid, overlaying detections and `WARNING!`/`FIRE!` alerts.
+
 ## Prerequisites
 
 - Torch with CUDA