DOCUMENTATION.md

RoadSoS — Emergency Services Locator for Road Accidents

National Road Safety Hackathon 2026 | IIT Madras

---

📋 Software Packages Used

Package	Version	Purpose
Python	3.10+	Core programming language
Gradio	≥4.0.0	Web UI framework (responsive, mobile-friendly)
Folium	≥0.19.0	Interactive map generation (Leaflet.js wrapper)
Geopy	≥2.4.0	Geocoding (Nominatim integration)
SQLite3	Built-in	Local database for incident logging
urllib	Built-in	HTTP requests to Overpass API
json	Built-in	Data serialization
math	Built-in	Haversine distance calculation

External APIs (No API key required — Free and Open):

API	Provider	Purpose
Overpass API	OpenStreetMap	Real-time query for hospitals, police, fire stations
Nominatim	OpenStreetMap	Forward/reverse geocoding (text → coordinates)

---

🏗️ System Architecture

USER (Web/Mobile) → GRADIO UI → PYTHON BACKEND → Overpass API (OSM) + SQLite DB
                                                 → Nominatim (Geocoding)
                                                 → Folium (Map Generation)

---

📝 Assumptions

1. Internet connectivity required for real-time Overpass API queries
2. Users provide text location or GPS coordinates
3. OpenStreetMap data is comprehensive for metro cities; Tier-3 may be sparse
4. National emergency numbers (112, 108, 100) always shown as fallback
5. Designed for Golden Hour use — speed over comprehensiveness
6. English-only (production would need i18n for 22 Indian languages)
7. SQLite sufficient for hackathon; production needs PostgreSQL + PostGIS
8. No personal identifiers stored; location logged for analytics only

---

🚀 How to Run

pip install -r requirements.txt
python database/init_db.py
python app.py
# → http://localhost:7860

---

📊 Database Schema

• incidents: timestamp, lat/lon, type, severity, description, services found
• emergency_searches: timestamp, lat/lon, location text, radius, results count
• trauma_centers: name, city, state, lat/lon, phone, type, ICU/blood bank flags

---

🔗 Data Sources

1. OpenStreetMap (Overpass API) — live hospital/police/fire station data
2. Motor Vehicles Amendment Act 2019 — Section 134A (Good Samaritan Law)
3. MoRTH — Emergency number directory
4. NHAI — Highway helpline data
5. GVK EMRI — 108 Ambulance coverage
6. Supreme Court of India — Good Samaritan Guidelines (2016)