penquinz01/gridlock-2.0

Purpose and entry points

ARES is a Bengaluru Traffic Police incident-response decision-support system. The FastAPI application starts at backend/app/main.py (uvicorn app.main:app) and exposes REST endpoints, chiefly POST /api/report, plus analysis, routing, map, hotspot, and station-portal APIs. The optional Vite/React operator UI starts from frontend/src/main.jsx and frontend/src/App.jsx.

API composition

Route modules are the HTTP boundary and delegate business work to services: backend/app/routes/report.py, backend/app/routes/analyze.py, and backend/app/routes/station_portal.py. backend/app/main.py composes these routers. The report route is the primary orchestration entry point for a minimally specified incident; specialized routes expose individual capabilities such as risk, recommendations, diversions, similarities, and maps.

Incident enrichment and inference

Incident coordinates, cause, and timestamp are normalized into model-ready fields. Location resolution maps coordinates to corridor and station, with local nearest-data lookup and optional Mappls live-place lookup: backend/app/services/location_service.py, backend/app/services/map_service.py, backend/app/utils/mappings.py. Time-derived features and inferred event/vehicle properties form the boundary between user input and analytics.

ML prediction and historical data

Pretrained scikit-learn Random Forest artifacts predict priority and road-closure needs: backend/models/priority_model.pkl, backend/models/road_closure_model.pkl. Historical feature data is held in backend/preprocessed_data/preprocessed_data.csv; it supports KNN-based similar-incident retrieval through backend/app/services/similarity_service.py. Model training/preprocessing is offline, represented by backend/jupyter_files/data_preprocess.ipynb and model notebooks, rather than a runtime training path.

Deterministic operational decisions

Predictions feed rule-based risk scoring and resource deployment recommendations. Risk combines priority, closure prediction, timing, incident type, and vehicle factors; recommendation logic converts the resulting level into officers, barricades, escalation, and recovery requirements. Core boundaries are backend/app/services/risk_service.py, backend/app/rules/risk_rules.py, backend/app/services/recommendation_service.py, and backend/app/rules/recommendation_rules.py.

Diversion, routing, and spatial analytics

The system generates interactive Folium diversion-map HTML around an incident and corridor warnings, while routing/diversion services provide operational route alternatives. Hotspot processing aggregates frequent/high-risk locations for corridor-level views. Components: backend/app/services/diversion_service.py, backend/app/services/routing_service.py, backend/app/services/hotspot_service.py, and backend/app/routes/map.py. These outputs are visualization/operational artifacts downstream of inference, not inputs to model scoring.

Persistence, portal, and external integration

SQLite persistence uses raw SQL through backend/app/database.py; it records incidents and resolution feedback. The station portal authenticates station-code users, authorizes queues, and closes incidents with actual outcome labels via backend/app/services/auth_service.py and backend/app/routes/station_portal.py. Feedback creates the learning-data boundary for future offline retraining. Runtime infrastructure is Python 3.10+, FastAPI/Uvicorn, SQLite, scikit-learn/joblib, and Folium; Mappls/MapmyIndia is an optional credential-driven external service configured through backend/app/config.py.