Skip to content

Sherin-SEF-AI/GoldenHourEngine

BranchesTags

Repository files navigation

Golden Hour Engine

An autonomous emergency response orchestration platform for road accidents. The system detects accidents in real time through CCTV feeds, dispatches the nearest suitable ambulance, pre-alerts the optimal hospital, and clears a green traffic corridor -- all within the critical first 60 minutes known as the "golden hour."

Author: Sherin Joseph Roy

Table of Contents

Overview

Road accident fatalities remain disproportionately high in regions where emergency response coordination is fragmented. The Golden Hour Engine addresses this by providing a fully integrated, AI-driven pipeline that automates every stage of the emergency response process:

  1. Detect -- Edge-deployed computer vision models analyze CCTV feeds to identify accidents, classify severity, and estimate casualty counts in real time.
  2. Dispatch -- A scoring engine evaluates all available ambulances based on distance, ETA, equipment level (BLS/ALS/MICU), crew capability, and road conditions, then dispatches the best match.
  3. Prepare -- The optimal hospital is selected based on proximity, specialty match, trauma center level, and real-time bed/equipment availability. A pre-arrival notification is sent so the ER team can prepare before the patient arrives.
  4. Clear -- Traffic signals along the ambulance route are preempted to create a green-wave corridor, minimizing transit time.

The entire workflow is orchestrated using a saga-based state machine that manages the incident lifecycle from detection through hospital handoff.

Architecture

                          CCTV Feeds
                              |
                    +---------v---------+
                    |  Detection Layer  |
                    |  (CV/ML Pipeline) |
                    +---------+---------+
                              |
                    +---------v---------+
                    | Orchestration     |
                    | Engine (Saga)     |
                    +---------+---------+
                       /      |      \
            +---------+  +----+----+  +---------+
            | Dispatch |  |Hospital |  |Corridor |
            | Engine   |  |Selector |  |Manager  |
            +----+-----+  +----+---+  +----+----+
                 |              |            |
           Ambulance       Hospital     Traffic
           Fleet           Network      Signals

Core Components

Component Role
Orchestration Engine Saga-based coordinator managing incident lifecycle through state transitions
Detection Pipeline Multi-detector fusion engine (vehicle anomaly, crowd formation, traffic flow, audio, flash detection) with severity assessment
Dispatch Engine Weighted scoring algorithm for ambulance selection with real-time fleet tracking and dynamic rerouting
Hospital Selector Multi-criteria hospital matching with live capacity tracking and pre-arrival notification system
Corridor Manager Green-wave planner that preempts traffic signals along ambulance routes
Dashboard Real-time operations dashboard with map visualization, incident tracking, and fleet monitoring

System Layers

Layer 1: Accident Detection

The detection layer processes CCTV video feeds through a pipeline of specialized detectors:

  • Vehicle Anomaly Detector -- YOLO-based object detection for crashed/overturned vehicles
  • Crowd Formation Detector -- Identifies abnormal pedestrian clustering at accident scenes
  • Traffic Flow Anomaly Detector -- Detects sudden speed changes, lane blockages, and queue buildups
  • Audio Anomaly Detector -- Sound-based detection of collisions and emergency sirens
  • Flash Detector -- Identifies emergency vehicle lights and hazard indicators
  • Fusion Engine -- Combines signals from all detectors using weighted voting with temporal correlation

The pipeline feeds into a Severity Assessor that classifies incidents as LOW, MEDIUM, HIGH, or CRITICAL based on detected vehicle types, estimated casualty count, fire/smoke presence, and traffic impact.

Layer 2: Ambulance Dispatch

The dispatch engine uses a configurable weighted scoring model:

Factor Default Weight
Distance to incident 0.30
Estimated time of arrival 0.25
Equipment match (BLS/ALS/MICU) 0.20
Crew skill level 0.15
Fatigue penalty 0.05
Availability status 0.05

Features:

  • Real-time GPS telemetry ingestion from ambulance fleet
  • Route calculation via OSRM with road condition overlays
  • Dynamic rerouting when road conditions change
  • Automatic reassignment if a better ambulance becomes available (threshold-based)

Layer 3: Hospital Preparation

Hospital selection considers:

Factor Default Weight
Distance 0.25
Estimated time of arrival 0.25
Specialty match 0.20
Bed availability 0.15
Trauma center level 0.10
Historical outcome data 0.05

The system maintains a live capacity registry updated by hospitals and sends structured pre-arrival notifications including estimated arrival time, casualty count, severity, and detected injury types.

Layer 4: Corridor Clearance

The green-wave planner:

  • Identifies all traffic signals along the computed ambulance route
  • Calculates signal timing sequences to create continuous green passage
  • Sends preemption commands to traffic signal controllers via MQTT
  • Restores normal signal timing after the ambulance passes

Tech Stack

Backend

Technology Purpose
Python 3.11+ Core language
FastAPI REST API framework
SQLAlchemy 2.0 + asyncpg Async ORM with PostgreSQL
PostgreSQL 16 + PostGIS Geospatial database
Redis 7 Caching, pub/sub, session store
Celery Distributed task queue
MQTT (Mosquitto) IoT message broker for cameras and signals
OSRM Open-source routing engine
MinIO S3-compatible object storage for video/snapshots
Prometheus + Grafana Metrics and monitoring
Loki Log aggregation
Structlog Structured logging

Computer Vision / ML

Technology Purpose
PyTorch Deep learning framework
Ultralytics (YOLOv8) Object detection
ONNX Runtime Optimized model inference
OpenCV Video processing
XGBoost / scikit-learn Severity classification

Frontend

Technology Purpose
Next.js 14 React framework (App Router, standalone output)
TypeScript Type-safe frontend
MapLibre GL JS Interactive map visualization
Zustand Lightweight state management
TanStack Query Server state and data fetching
Recharts Data visualization and charts
Tailwind CSS Utility-first styling

Infrastructure

Technology Purpose
Docker + Docker Compose Containerization and orchestration
Traefik Reverse proxy and load balancer
Alembic Database schema migrations

Project Structure

GoldenHourEngine/
|-- src/                          # Python backend
|   |-- main.py                   # FastAPI application entry point
|   |-- api/                      # API layer
|   |   |-- routes/               # REST endpoint handlers
|   |   |   |-- incidents.py      # Incident CRUD and lifecycle
|   |   |   |-- ambulances.py     # Fleet management and telemetry
|   |   |   |-- hospitals.py      # Hospital registry and capacity
|   |   |   |-- cameras.py        # Camera management
|   |   |   |-- dispatch.py       # Dispatch commands
|   |   |   +-- dashboard.py      # Aggregated dashboard data
|   |   |-- schemas.py            # Pydantic request/response models
|   |   +-- websocket/            # WebSocket handlers
|   |       +-- handler.py        # Real-time connection management
|   |-- core/                     # Shared infrastructure
|   |   |-- database.py           # PostgreSQL + PostGIS async engine
|   |   |-- redis.py              # Redis client and pub/sub
|   |   |-- logging.py            # Structured logging
|   |   |-- metrics.py            # Prometheus instrumentation
|   |   |-- events.py             # Internal event bus
|   |   |-- exceptions.py         # Custom exception hierarchy
|   |   |-- geo.py                # Geospatial utilities
|   |   |-- health.py             # Health check system
|   |   +-- timing.py             # UTC timing utilities
|   |-- models/                   # SQLAlchemy ORM models
|   |   |-- incident.py           # Incident entity
|   |   |-- ambulance.py          # Ambulance and station entities
|   |   |-- hospital.py           # Hospital and notification entities
|   |   |-- camera.py             # Camera entity
|   |   |-- dispatch.py           # Dispatch command entity
|   |   |-- road_segment.py       # Road network entity
|   |   +-- traffic_signal.py     # Traffic signal entity
|   |-- services/                 # Business logic
|   |   |-- accident_detection/   # CV/ML detection pipeline
|   |   |   |-- detector_pipeline.py
|   |   |   |-- severity_assessor.py
|   |   |   +-- detectors/        # Individual detector modules
|   |   |       |-- vehicle_anomaly.py
|   |   |       |-- crowd_formation.py
|   |   |       |-- traffic_flow_anomaly.py
|   |   |       |-- audio_anomaly.py
|   |   |       |-- flash_detector.py
|   |   |       +-- fusion_engine.py
|   |   |-- camera_ingestion/     # Video stream processing
|   |   |   |-- stream_manager.py
|   |   |   +-- frame_preprocessor.py
|   |   |-- dispatch/             # Ambulance routing
|   |   |   |-- dispatch_engine.py
|   |   |   |-- fleet_registry.py
|   |   |   |-- road_intelligence.py
|   |   |   |-- telemetry_ingestion.py
|   |   |   +-- rerouter.py
|   |   |-- hospital/             # Hospital coordination
|   |   |   |-- hospital_selector.py
|   |   |   |-- hospital_registry.py
|   |   |   |-- capacity_updater.py
|   |   |   |-- notifier.py
|   |   |   +-- handoff_coordinator.py
|   |   |-- corridor/             # Traffic signal control
|   |   |   |-- corridor_manager.py
|   |   |   |-- green_wave_planner.py
|   |   |   +-- signal_registry.py
|   |   +-- orchestration/        # Saga-based workflow
|   |       |-- orchestration_engine.py
|   |       |-- state_machine.py
|   |       |-- saga_coordinator.py
|   |       +-- escalation_manager.py
|   +-- workers/                  # Celery async workers
|       |-- celery_app.py
|       +-- tasks.py
|-- dashboard/                    # Next.js frontend
|   |-- src/
|   |   |-- app/                  # App Router pages
|   |   |   |-- layout.tsx        # Root layout with WebSocket
|   |   |   |-- page.tsx          # Dashboard home
|   |   |   |-- incidents/        # Incident views
|   |   |   +-- api/config/       # Runtime config endpoint
|   |   |-- components/           # React components
|   |   |   |-- ui/               # Reusable UI primitives
|   |   |   |-- sidebar/          # Dashboard sidebar widgets
|   |   |   +-- map/              # MapLibre map component
|   |   |-- stores/               # Zustand state stores
|   |   |-- lib/                  # API client, WebSocket, utils
|   |   +-- types/                # TypeScript type definitions
|   |-- next.config.js
|   |-- tailwind.config.ts
|   +-- package.json
|-- config/
|   +-- settings.py               # Pydantic settings (13 modules)
|-- docker/
|   |-- Dockerfile.backend        # Multi-stage FastAPI build
|   |-- Dockerfile.dashboard      # Multi-stage Next.js build
|   |-- Dockerfile.worker         # Celery worker build
|   |-- mosquitto/                # MQTT broker config
|   +-- traefik/                  # Reverse proxy config
|-- migrations/                   # Alembic database migrations
|-- monitoring/                   # Prometheus, Grafana, Loki configs
|-- scripts/                      # Utility scripts (seeding, etc.)
|-- tests/                        # Test suite (unit, integration, e2e)
|-- docker-compose.yml            # Production compose
|-- docker-compose.dev.yml        # Development compose
|-- pyproject.toml                # Python project configuration
+-- .env.example                  # Environment variable template

API Reference

All endpoints are prefixed with /api/v1. Interactive documentation is available at /docs (Swagger UI) and /redoc (ReDoc) when the API is running.

Incidents

Method Endpoint Description
POST /incidents Report an incident manually
GET /incidents List incidents with filters (status, severity, date range, bounding box)
GET /incidents/active Get all active incidents
GET /incidents/stats Incident statistics
GET /incidents/{id} Get incident details
PATCH /incidents/{id}/status Transition incident status
POST /incidents/{id}/false-alarm Mark as false alarm
GET /incidents/{id}/timeline Get incident timeline events

Ambulances

Method Endpoint Description
GET /ambulances List ambulances with filters (status, type, location)
GET /ambulances/fleet-status Fleet summary (available, en route, on scene counts)
GET /ambulances/{id} Get ambulance details
POST /ambulances Register a new ambulance
PATCH /ambulances/{id} Update ambulance details
POST /ambulances/{id}/telemetry Submit GPS telemetry
GET /ambulances/{id}/location Get current location

Hospitals

Method Endpoint Description
GET /hospitals List hospitals with filters (type, trauma level, specialty)
GET /hospitals/nearby Find hospitals within a radius
GET /hospitals/{id} Get hospital details
POST /hospitals Register a new hospital
PATCH /hospitals/{id} Update hospital details
POST /hospitals/{id}/capacity Update bed/equipment capacity
GET /hospitals/{id}/capacity Get current capacity
POST /hospitals/notifications/{id}/acknowledge Acknowledge pre-arrival notification

Cameras

Method Endpoint Description
GET /cameras List cameras with filters
GET /cameras/status Camera status summary
GET /cameras/{id} Get camera details
POST /cameras Register a new camera
PATCH /cameras/{id} Update camera details
POST /cameras/{id}/attention Focus camera on a location

Dispatch

Method Endpoint Description
POST /dispatch/manual Manually trigger a dispatch
GET /dispatch List dispatch commands
GET /dispatch/{id} Get dispatch command details
POST /dispatch/{id}/acknowledge Acknowledge a dispatch

Dashboard

Method Endpoint Description
GET /dashboard/overview System-wide overview
GET /dashboard/map Map data (incidents, ambulances, hospitals)
GET /dashboard/analytics Response time and efficiency analytics

WebSocket Channels

Endpoint Description
/ws/incidents Live incident updates
/ws/ambulances Live ambulance location updates
/ws/dashboard Combined feed (incidents + fleet + hospitals + corridors)

Health Endpoints

Endpoint Description
/health Full component health report
/health/live Liveness probe
/health/ready Readiness probe (database + Redis)
/metrics Prometheus metrics

Dashboard

The operations dashboard provides a real-time view of the entire system:

  • Overview Panel -- Active incidents, fleet status, hospital capacity, system health
  • Interactive Map -- MapLibre GL JS map showing incident locations, ambulance positions (with heading), hospital markers, and active corridors
  • Incident List -- Filterable table of all incidents with severity badges and status tracking
  • Incident Detail -- Full incident timeline, assigned ambulance, target hospital, response metrics
  • Sidebar Widgets -- Active incident count, fleet availability breakdown, hospital capacity indicators
  • Real-time Updates -- WebSocket-driven live data without page refresh

Getting Started

Prerequisites

  • Docker Engine 24+ and Docker Compose v2
  • Git
  • 4 GB RAM minimum (8 GB recommended)

Quick Start

  1. Clone the repository:
git clone https://github.com/Sherin-SEF-AI/GoldenHourEngine.git
cd GoldenHourEngine
  1. Create the environment file:
cp .env.example .env
  1. Start the development stack:
docker compose -f docker-compose.dev.yml up -d

This starts all services:

Service Host Port Description
PostgreSQL + PostGIS 5435 Geospatial database
Redis 6382 Cache and message broker
Mosquitto 1885 MQTT broker
MinIO Console 9021 Object storage (API on 9020)
GHE API 8001 FastAPI backend
GHE Dashboard 3002 Next.js frontend
  1. Verify the API is running:
curl http://localhost:8001/health
  1. Run database migrations:
docker exec ghe-api-dev alembic upgrade head
  1. Seed sample data (optional):
docker exec ghe-api-dev python scripts/seed_data.py
  1. Open the dashboard:
http://localhost:3002
  1. Access the API documentation:
http://localhost:8001/docs

Default Credentials

Service Username Password
PostgreSQL ghe_user ghe_password
MinIO minioadmin minioadmin

Configuration

All configuration is managed through environment variables. See .env.example for the complete list with descriptions.

Configuration Modules

The backend uses Pydantic Settings organized into 13 modules:

Module Prefix Description
Application GHE_ App name, version, environment, CORS, logging
Database DB_ PostgreSQL connection, pool settings, timeouts
Redis REDIS_ Redis connection, pool size, SSL
MQTT MQTT_ Mosquitto broker connection, topic prefix, QoS
OSRM OSRM_ Routing engine endpoint and options
MinIO MINIO_ Object storage endpoint, buckets, credentials
Nominatim NOMINATIM_ Geocoding service endpoint
Camera CAMERA_ Default camera settings (FPS, resolution, protocol)
Detection DETECTION_ ML confidence thresholds, model path, device
Dispatch DISPATCH_WEIGHT_ Ambulance scoring weights and limits
Hospital HOSPITAL_WEIGHT_ Hospital selection weights and limits
Notification WHATSAPP_, SMS_, VOICE_ Multi-channel notification settings
Auth AUTH_ JWT settings, bcrypt rounds
Celery CELERY_ Task queue serialization, timeouts, concurrency
Monitoring PROMETHEUS_, GRAFANA_, LOKI_ Observability stack settings

Development

Running Tests

# Unit tests
docker exec ghe-api-dev pytest tests/unit -v

# Integration tests (requires all services)
docker exec ghe-api-dev pytest tests/integration -v

# Full suite with coverage
docker exec ghe-api-dev pytest --cov=src --cov-report=term-missing

Code Quality

# Linting
ruff check src/

# Formatting
black src/

# Type checking
mypy src/

Database Migrations

# Create a new migration
docker exec ghe-api-dev alembic revision --autogenerate -m "description"

# Apply migrations
docker exec ghe-api-dev alembic upgrade head

# Rollback one migration
docker exec ghe-api-dev alembic downgrade -1

Project Statistics

Metric Value
Python source files 71
Python lines of code ~31,000
TypeScript source files 20
TypeScript lines of code ~4,700
Total lines of code ~35,700
API endpoints 32
WebSocket channels 3
Database models 8
Service modules 6
Configuration variables 120+

License

This project is licensed under the MIT License. See the LICENSE file for details.

About

An autonomous emergency response orchestration platform for road accidents.

sherin-sef-ai.github.io/

Topics

artficial-intelligence emergency-response publicsafety aiagents

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages