Construction-Hazard-Detection: a full site-safety stack around YOLO, not a demo notebook
Enhances construction site safety using YOLO for object detection, identifying hazards like workers without helmets or safety vests, and proximity to machinery or vehicles. HDBSCAN clusters safety cone coordinates to create monitored zones. Post-processing algorithms improve detection accuracy.
At a glance
- What is it?
- This project pairs YOLO detection with HDBSCAN-derived cone zones across a production-shaped runtime of PostgreSQL, Redis, MediaMTX and FastAPI services, with an MCP server for agents. The supplied material cuts off before its quick start commands, and no model accuracy figures appear anywhere in it.
- Who is it for?
- Teams with existing site cameras, a GPU and the staff to run PostgreSQL, Redis and MediaMTX should treat this repository as a serious starting point for self-hosted safety monitoring, beginning with the HuggingFace model repo and the Roboflow dataset to validate detection quality on their own footage before deploying anything.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
Five hazard rules over eleven detection classes
The system watches live construction cameras for five named hazards: workers without hard hats, workers without safety vests, workers too close to machinery or vehicles, workers inside cone-derived controlled areas, and machinery or vehicles too close to utility poles. Underneath those rules sit eleven configured detection classes, per the architecture description, with post-processing algorithms credited in the repository description with improving detection accuracy. Alerting is multilingual to a degree that hints at the intended deployment region: Traditional and Simplified Chinese, English, French, Thai, Vietnamese, Indonesian and Japanese for labels and notifications, delivered through Firebase Cloud Messaging. The audience is site operators and safety officers who already have RTSP cameras mounted and want software to watch them, and the project treats that as an infrastructure problem rather than a scripting exercise.
Zones that come from clustering cones, not drawing boxes
The most interesting mechanism in the repository is how controlled areas are defined. Instead of an administrator drawing geofences on a floor plan, the system detects safety cones in the camera view and uses HDBSCAN, the density-based clustering algorithm from scikit-learn, to cluster cone coordinates into monitored zones, per the repository description. That choice has a real trade-off attached. Derived zones move as cones move, which matches how sites actually work, where hazard areas change daily; but the zones inherit every failure of the upstream detector, so a missed cone silently shrinks a protected area. The utility-pole proximity rule is similarly clever and similarly exposed: it depends on the camera seeing the pole. Nothing in the material quantifies either failure mode, so anyone deploying this should test zone derivation against their own footage as the first evaluation step.
A runtime shaped like production: PostgreSQL, Redis, MediaMTX, FastAPI
The recommended runtime reads like a small deployment, deliberately. PostgreSQL stores sites, users, stream configurations and violation records. Redis holds auth and session cache, notification token cache and compact live-coordination keys. MediaMTX handles RTSP ingest plus HLS and WebRTC playback. A supervisor, main.py, polls stream configuration and starts one stream process per active camera, while local YOLO workers share GPU inference across cameras through shared memory, which is the stated high-throughput path in src/yolo_worker.py. A standalone YOLO HTTP API remains available under examples/YOLO_server_api for testing or separate deployment. Version pins are visible in the badges: Python 3.14, Ultralytics 8.4.115, FastAPI 0.128.0, the MCP Python SDK 1.25.0 and redis-py 7.1.0, with Docker containers and TensorRT rebuild helpers in scripts/. The Python 3.14 requirement in particular will constrain which hosts can run it without containerisation.
Redis deliberately stays out of the video path
One architectural note in the README deserves a highlight because it signals the author has operated this thing. Redis is explicitly stated not to store live video frames; MediaMTX owns live playback, and Redis keeps only small coordination state, enumerated as authentication cache, FCM token cache, compact warning metadata, overlay demand keys and overlay ready keys. That discipline matters because the naive design, shoving frames through a broker, turns Redis into the bottleneck and the memory hog the moment camera counts rise. Keeping the message bus for control-plane facts and letting a dedicated media server carry the data plane is how grown-up streaming systems are built. The streaming_web service complements it with labels, playback URLs, metadata channels, media-session authentication and WebRTC ICE settings, so browser and app clients get live views without touching the inference path.
The repository map reveals the real scope
Browsing the top-level map shows how far this goes beyond a detection script. Under examples/ sit a web BFF handling sessions, CSRF, media capability and API gateway duties; a data-management server for users, groups, sites and stream configuration; an FCM notification server; a violation-records server exposing recorded violations and images; the streaming web service; the optional YOLO API; and an MCP server built on FastMCP exposing tools for AI agents, which is an unusual and current touch for an industrial monitoring system. Model development has its own wings: YOLO_train, YOLO_evaluation and YOLO_data_augmentation directories, plus a downloadable dataset on Roboflow and a model repository on HuggingFace. The Flutter mobile client lives in a separate repository, visionnaire-flutter, and this repository's frontend/web/ is explicitly an ignored, generated deployment artifact rather than source, a boundary documented in frontend/README.md. That separation is correct engineering hygiene, and it also means adopting the full system means adopting two repositories.
Model lifecycle in the open, quick start missing from the excerpt
For an adoption decision the gaps matter as much as the features. The supplied README cuts off at the start of its quick start, at the heading Prepare Python, so this review can quote no install or run commands; the pinned versions above and the repository's own documentation are the entry points. More importantly, nowhere in the material are model accuracy figures given: no mAP, no false-positive rate, no evaluation results, even though a Codecov badge shows code coverage and an evaluation directory exists. In a safety context, that is the number a buyer needs most, and its absence means the Roboflow dataset and HuggingFace repo are where due diligence starts. Maintenance history is a study in bursts: v4.1.0 shipped 2025-08-26, then v5.0.0 a full year later on 2026-08-23, with the last push on 2026-08-27. The licence is AGPL-3.0, so running it internally is one thing, but building a network-facing commercial service on modified code carries source-disclosure obligations. The alternative path is commercial EHS vision platforms, vendor-operated and sold per camera with contractual commitments, versus this self-hosted stack; or plain Ultralytics with custom glue, which is exactly the integration work this repository already represents.
Editorial conclusion
Teams with existing site cameras, a GPU and the staff to run PostgreSQL, Redis and MediaMTX should treat this repository as a serious starting point for self-hosted safety monitoring, beginning with the HuggingFace model repo and the Roboflow dataset to validate detection quality on their own footage before deploying anything. It is the wrong choice for organisations wanting a turnkey vendor-supported system with contractual accuracy commitments, since this is AGPL-3.0 self-hosted software, its material publishes no mAP or false-positive rates, and the quick start commands fall outside the supplied README excerpt. Verify three things first: detection accuracy on your cameras and lighting, the eleven-class label set against your site's actual hazards, and what AGPL-3.0 implies for your deployment model before connecting it to a web-facing service.
Community notes