IGNITE - GitLite

KO | EN

gitlite — search

#agents #gemini #typescript #open-source #cpp #csharp #tensorflow #golang #pdf #javascript

IGNITE

(★ 9)

A destination-agnostic tourist safety and route-planning system for India. Uses a deterministic, multi-factor risk engine across six terrain profiles to fuse live weather, elevation, hazard mapping, and emergency-service proximity into explainable safety scores with real-time re-routing, SOS dispatch for low-connectivity areas.

File Explorer

ZIP Download

- index.py
- - requirements.txt
  - test_pilgrimage_seed_and_risk.py
  - test_qa_security_audit.py
  - test_simulation_bench.py
  - test_system_e2e.py
- - .env.example
  - .gitignore
  - index.html
  - package-lock.json
  - package.json
  - README.md
  - tsconfig.app.json
  - tsconfig.json
  - tsconfig.node.json
  - vercel.json
  - vite.config.ts
.gitignore
ARCHITECTURE.md
DEPLOYMENT_CHECKLIST.md
JUDGE_ONE_PAGER.md
package-lock.json
package.json
README.md
requirements.txt
vercel.json
walkthrough.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **Travel safely, not just smartly — sovereign-scale, explainable risk intelligence and dynamic re-routing for any destination in India.**

[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)]()
[![Live Demo](https://img.shields.io/badge/Live_Demo-ignite--lemon--nu.vercel.app-blueviolet.svg?style=flat&logo=vercel)](https://ignite-lemon-nu.vercel.app)
[![Version](https://img.shields.io/badge/Version-2.1.0-blue.svg)]()
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110.0-009688.svg?logo=fastapi)](https://fastapi.tiangolo.com)
[![React](https://img.shields.io/badge/React-18.3.1-61DAFB.svg?logo=react)](https://reactjs.org)
[![PostGIS](https://img.shields.io/badge/PostGIS-Spatial_ST_Intersects-336791.svg?logo=postgresql)](https://postgis.net)
[![Coverage](https://img.shields.io/badge/Pan--India-28_States_%2B_8_UTs-orange.svg)]()

**Live Application**: [https://ignite-lemon-nu.vercel.app](https://ignite-lemon-nu.vercel.app)

---

## Overview

**IGNITE** is a destination-agnostic tourist safety and smart itinerary system engineered for India. Unlike conventional travel applications that act as static directories or rely on opaque black-box machine learning models, IGNITE utilizes **deterministic, mathematical multi-factor risk engines** and real-time geospatial data (live weather, ground elevation, PostGIS hazard polygons, crowd bottlenecks, and emergency infrastructure proximity) to synthesize and adapt day-wise itineraries on the fly. The system operates universally across all 28 States and 8 Union Territories of India: whether a tourist searches a high-altitude Himalayan trail, a coastal marine beach, a dense wildlife reserve, an arid desert dune, a dense riverine plains pilgrimage, or a modern urban heritage campus, IGNITE automatically resolves coordinates, samples real ground altitude, classifies the environmental terrain profile, and enforces strict region-specific safety protocols with complete mathematical explainability.

---

## Features & Capabilities

| Feature | Description |
| :--- | :--- |
| **Destination-Agnostic Resolver** | Converts arbitrary Indian place names or landmarks into GPS coordinates, bounding boxes, and ground elevation profiles via OSM Nominatim and Open-Meteo with sovereign Indian boundary enforcement (`6.0°N–37.6°N`, `68.0°E–97.5°E`). |
| **6-Profile Regional Risk Engine** | Dynamically swaps mathematical weight vectors across six canonical environmental profiles (`HILL_MOUNTAIN`, `COASTAL_MARINE`, `FOREST_WILDLIFE`, `DESERT_ARID`, `URBAN_HERITAGE`, `PLAINS_RIVERINE`) to calculate accurate 0–100 safety risk scores. |
| **Curated National Pilgrimage Dataset** | Pre-seeded with 21 iconic pilgrimage sites across 4 major national circuits (Char Dham, Chota Char Dham, 12 Jyotirlingas, Prominent Shrines) with dynamic crowd-density, mobility exertion tiers, and festival surge multipliers. |
| **Dynamic Re-Routing Engine** | Continuously evaluates live GPS position against active hazard zones and IMD alert levels; triggers immediate topological safe bypass routes and shelter diversion if risk score exceeds 65.0. |
| **Emergency SOS & 2G GSM Gateway** | Dynamically queries nearest hospitals, police posts, and SDRF stations within 15km via Overpass QL and formats a 140-character compact SMS string for low-bandwidth 2G / GSM cell networks. |
| **Spatial PostGIS Geo-Fencing** | Executes spatial polygon intersections (`ST_Intersects`) between user coordinates and geological debris slides, floodplains, tidal surges, and wildfire corridors. |
| **IndexedDB Offline Persistence** | Caches full itineraries, topological polyline coordinates, hazard boundaries, and emergency shelter nodes into browser IndexedDB (`IgniteOfflineDB`) with LocalStorage fallback for zero-network environments. |
| **Group Mesh Radar & Dispersion Alert** | Tracks group member positions relative to the tour leader and triggers automatic alerts if members straggle beyond a configurable separation threshold (default: 150m). |
| **Multilingual Voice Explainability** | Translates mathematical risk scores into natural-language safety briefings with Web Speech API Text-to-Speech (TTS) support in English and Hindi. |
| **Regulated Budget Optimizer** | Allocates realistic day-wise expenses across lodging, transit, permits, and food while strictly reserving a mandatory **15% emergency liquidity cushion**. |
| **Explainability Matrix** | Breaks down the aggregate risk score into sub-factor visual gauges with contextual operational details (e.g., rainfall rate, wind speed, elevation gain, nearest hospital transit distance). |

---

## What It Can Do Now

- **Resolve Any Indian Destination**: Geocodes arbitrary free-text place queries across India and samples real elevation in meters without hardcoded place tables.
- **National Pilgrimage Circuits Quick-Selector**: Instant 1-click filtering and interactive map zoom for Char Dham (Cardinal), Chota Char Dham (Himalayan), 12 Jyotirlingas, and Prominent Shrines (Ajmer Sharif, Shirdi, Palitana, Akshardham).
- **Enforce Dynamic Curfews**: Applies regional curfew restrictions based on environmental classification (e.g., 17:00 IST for wildlife sanctuaries, 17:30 IST for alpine trails, 19:00 IST for marine beaches, 21:30 IST for riverine plains, 22:00 IST for urban centers).
- **Calculate Live Road & Trail Polylines**: Retrieves topological footpaths and road geometries between waypoints via OSRM.
- **Simulate Extreme Disaster Injections**: Injects multi-region disaster scenarios (Himalayan cloudbursts, Bay of Bengal cyclones, Brahmaputra floods, Thar heatwaves, Plains crowd surges) via an interactive simulation bench to test dynamic rerouting.
- **Broadcast Real-Time WebSocket Alerts**: Pushes telemetry updates and hazard breach notifications across client WebSocket channels (`/api/v1/ws/alerts/{trip_id}`).
- **Protect Infrastructure with Rate Limiting**: Enforces a sliding-window gateway rate limiter (60 req/min per IP) to prevent downstream API exhaustion.
- **Secure Guest & User Identity**: Employs HMAC-SHA256 cryptographically verified JWT sessions alongside zero-friction emergency guest authentication (`guest_*`).

---

## The Problem

| Dimension | Generic Travel Apps (Google Maps, MakeMyTrip) | Static Hazard Advisories (State Disaster Portals) | Manual Trip Planning | SafeTrail AI (This System) |
| :--- | :--- | :--- | :--- | :--- |
| **Safety Data Used** | Traffic & distance only; blind to landslides, cloudbursts, and AMS hypoxia. | Broad state/district text bulletins; no waypoint-level GPS mapping. | Outdated blog posts, travel forums, and word-of-mouth. | **Live multi-source telemetry (IMD alerts, real elevation, Overpass emergency grid, PostGIS hazard polygons).** |
| **Real-Time Adaptation** | Reroutes only for road congestion; ignores environmental hazard zones. | None; static PDF bulletins updated every 12–24 hours. | Zero automated response during active transit emergencies. | **Sub-second dynamic rerouting to safe topological bypass corridors and verified shelters over WebSockets.** |
| **Explainability** | Opaque estimated travel time; no safety breakdown. | Generic warnings without actionable mathematical scoring. | Purely intuitive guesswork. | **Deterministic, weighted 4-5 factor scoring (0–100) with plain-language English/Hindi voice briefings.** |
| **Destination Coverage** | Global road networks, but no specialized disaster risk modeling. | Limited to select high-profile state pilgrim routes. | User-limited knowledge. | **100% Pan-India coverage (All 28 States & 8 Union Territories) across 6 canonical environmental profiles.** |
| **Offline Reliability** | Limited offline map caching; fails when server sync drops. | Web-only PDF portals; unusable in remote valleys. | Printed notes or memory. | **IndexedDB client-side storage + 140-character 2G GSM SMS payload for dead-zone emergency dispatch.** |
| **Cost & Complexity** | Expensive proprietary routing APIs and heavy tracking SDKs. | Fragmented across disjoint state government websites. | High cognitive and planning burden on the traveler. | **Open-source stack (FastAPI, OSM Nominatim, Overpass QL, OSRM, Open-Meteo, Leaflet) with zero black-box ML overhead.** |

---

## System Architecture

```
+---------------------------------------------------------------------------------------------------+
|                                       CLIENT LAYER (Web & Mobile)                                 |
|   Next.js 14 / Vite React SPA  |  Leaflet.js Map Viewer  |  IndexedDB Offline Cache  |  WebSockets |
|   Popular Pilgrimage Circuits Tray  |  Multilingual Voice (EN/HI)  |  Live Hazard Visualizer      |
+---------------------------------------------------------------------------------------------------+
                                                  |  HTTPS / WSS
                                                  v
+---------------------------------------------------------------------------------------------------+
|                               API GATEWAY & SECURITY LAYER (FastAPI)                              |
|   CORS Middleware  |  Sliding-Window Rate Limiter (60 req/min)  |  HMAC-SHA256 JWT Token Validator |
+---------------------------------------------------------------------------------------------------+
                                                  |
        +-----------------------------------------+-----------------------------------------+
        |                                         |                                         |
        v                                         v                                         v
+-----------------------+             +-----------------------+             +-----------------------+
|  DESTINATION RESOLVER |             |  SOS & DISPATCH MESH  |             |  GROUP MESH RADAR     |
| - Sovereign Boundary  |             | - 15km Overpass Query |             | - Haversine Distance  |
| - Nominatim Geocode   |             | - Nearest Hosp/Police |             | - 150m Separation     |
| - Open-Meteo Ground Z |             | - 140-Char 2G SMS     |             | - Scatter Alerts      |
| - National Circuits   |             | - Emergency Helipads  |             | - Leader Sync Mesh    |
+-----------------------+             +-----------------------+             +-----------------------+
        |                                         |                                         |
        +-----------------------------------------+-----------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|                               DATA AGGREGATION & CACHING LAYER                                    |
|   Redis Cache (15m Weather, 6h Amenities, 24h Geocodes)  |  Async In-Memory Mock Fallback         |
|   - Open-Meteo API (Forecast & Elevation)               - OSM Overpass QL (Emergency Amenities)  |
|   - OSRM Routing Engine (Topological Polylines)         - PostGIS / Shapely (Spatial Polygons)   |
|   - Pilgrimage Metadata (Crowd Risk, Peak Seasons, Mobility Tiers, Security Holding Delay)       |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|                               ADAPTIVE RISK & RE-ROUTING ENGINE                                   |
|   Swaps Mathematical Weight Formulations (Hill / Coastal / Forest / Desert / Urban / Plains)      |
|   - Bounding Box Polygon Intersection  |  IMD Early Warning Multipliers (Yellow / Orange / Red)   |
|   - Dynamic Safe Bypass Generation     |  15% Emergency Medical Reserve Allocation                |
|   - Dynamic Crowd Factor Modulation (Peak Seasons, Stampede Risk, Staircase Exertion)            |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|                               EXPLAINABILITY & REASONING LAYER                                    |
|   - Deterministic Plain-Language Explainability Matrix (EN / HI)                                  |
|   - Google Gemini LLM Contextual Synthesis (Optional API Key, Zero-Impact Fallback)               |
+---------------------------------------------------------------------------------------------------+
```

---

## Risk Scoring Logic / Under the Hood

SafeTrail AI uses deterministic mathematical models instead of black-box neural networks. This guarantees that **every risk score is explainable, repeatable, and verifiable by search and rescue authorities**.

### 1. Mathematical Weight Formulations by Region Type

$$\text{Risk}_{\text{Hill}} = 0.30 \cdot S_{\text{Landslide}} + 0.25 \cdot S_{\text{Squall}} + 0.20 \cdot S_{\text{Hypoxia}} + 0.15 \cdot S_{\text{MedicalIso}} + 0.10 \cdot S_{\text{Crowd}}$$

$$\text{Risk}_{\text{Coastal}} = 0.35 \cdot S_{\text{Surge}} + 0.25 \cdot S_{\text{Precip}} + 0.15 \cdot S_{\text{RipCurrent}} + 0.15 \cdot S_{\text{HeatUV}} + 0.10 \cdot S_{\text{Density}}$$

$$\text{Risk}_{\text{Forest}} = 0.30 \cdot S_{\text{Wildlife}} + 0.25 \cdot S_{\text{ForestFire}} + 0.20 \cdot S_{\text{Flood}} + 0.20 \cdot S_{\text{Isolation}} + 0.05 \cdot S_{\text{Permit}}$$

$$\text{Risk}_{\text{Desert}} = 0.40 \cdot S_{\text{Dehydration}} + 0.25 \cdot S_{\text{Sandstorm}} + 0.25 \cdot S_{\text{WaterIso}} + 0.10 \cdot S_{\text{SandMobility}}$$

$$\text{Risk}_{\text{Urban}} = 0.40 \cdot S_{\text{Stampede}} + 0.25 \cdot S_{\text{Waterlogging}} + 0.20 \cdot S_{\text{Ambulance}} + 0.15 \cdot S_{\text{AQI}}$$

$$\text{Risk}_{\text{Plains}} = 0.35 \cdot S_{\text{Stampede}} + 0.25 \cdot S_{\text{RiverineFlood}} + 0.20 \cdot S_{\text{HeatStress}} + 0.20 \cdot S_{\text{EmergencyTransit}}$$

### 2. National Early Warning Alert Multipliers
If the India Meteorological Department (IMD) or State Disaster Management Authority issues an alert for the sector, the raw risk score is scaled deterministically:
- **IMD RED ALERT**: $\text{Score}_{\text{final}} = \min(100.0, \max(85.0, \text{Score}_{\text{raw}} \times 1.6))$ $\rightarrow$ Triggers mandatory **EMERGENCY_REROUTE**
- **IMD ORANGE ALERT**: $\text{Score}_{\text{final}} = \min(100.0, \max(65.0, \text{Score}_{\text{raw}} \times 1.3))$ $\rightarrow$ Triggers **ADVISORY_CAUTION**
- **IMD YELLOW ALERT**: $\text{Score}_{\text{final}} = \min(100.0, \max(40.0, \text{Score}_{\text{raw}} \times 1.15))$

> **Why this matters**: In life-safety critical operations, an operations commander or tourist must know *exactly* why a route was flagged (e.g., "30% weight applied because of 42mm/hr precipitation on a steep slope above 2,800m altitude"), rather than trusting an unexplainable ML confidence score.

---

## What Your User Sees

### Sample Input
```json
{
  "destination": "Munnar Top Station",
  "duration_days": 2,
  "budget_tier": "STANDARD",
  "total_budget_inr": 12000.0,
  "fitness_level": "MODERATE",
  "language": "en"
}
```

### Sample Output (Annotated with Risk Scoring & Emergency Reserve)
```json
{
  "destination_id": "dest_munnar_top_station",
  "destination": "Munnar Top Station",
  "state_ut": "Kerala",
  "region_type": "HILL_MOUNTAIN",
  "region_name": "Himalayan & Hill Mountain",
  "emergency_agency": "SDRF / Mountain Rescue Brigade",
  "duration_days": 2,
  "fitness_level": "MODERATE",
  "overall_safety_score": 28.4,
  "overall_risk_category": "LOW",
  "budget_breakdown": {
    "tier": "STANDARD",
    "total_budget_inr": 12000.0,
    "allocated_total_inr": 6800.0,
    "remaining_balance_inr": 5200.0,
    "categories": {
      "accommodation_inr": 1500.0,
      "food_and_hydration_inr": 1400.0,
      "local_transit_taxi_inr": 1600.0,
      "permits_safari_darshan_inr": 500.0,
      "emergency_medical_reserve_inr": 1800.0
    }
  },
  "days": [
    {
      "day_number": 1,
      "title": "Day 1: Arrival & Core Sector Transit (Munnar Top Station)",
      "distance_km": 11.0,
      "elevation_gain_m": 350,
      "acclimatization_safety": "Safe pacing. Night halt strictly adhering to 17:30 IST curfew.",
      "day_risk_score": 27.2,
      "checkpoints": [
        {
          "sequence": 1,
          "name": "Munnar Entry & Transit Hub",
          "altitude_m": 1500,
          "total_risk_score": 24.5,
          "risk_level": "LOW",
          "sub_scores": {
            "terrain_landslide": { "score": 22.0, "label": "Landslide & Slope", "details": "Stable Sector" },
            "weather_squall": { "score": 18.5, "label": "Alpine Weather & Rain", "details": "Rain: 0.0mm/h, Temp: 18°C" },
            "altitude_hypoxia": { "score": 0.0, "label": "Altitude & Hypoxia (AMS)", "details": "Elevation: 1500m (Below AMS threshold)" }
          }
        }
      ]
    }
  ],
  "mandatory_safety_advisories": [
    "Mandatory acclimatization halt above 2,800m altitude.",
    "Trekking past 17:30 IST is prohibited by State Police due to freezing temperatures.",
    "Carry 1 portable oxygen canister and waterproof alpine gear."
  ]
}
```

---

## Integrations & API Usage

### 1. Resolve Arbitrary Indian Destination
```bash
curl -X POST "http://localhost:8000/api/v1/destinations/resolve" \
     -H "Content-Type: application/json" \
     -d '{"query": "Puri Blue Flag Beach"}'
```

### 2. Generate Risk-Weighted Itinerary
```bash
curl -X POST "http://localhost:8000/api/v1/itinerary/generate" \
     -H "Content-Type: application/json" \
     -d '{
       "destination": "Kaziranga National Park",
       "duration_days": 2,
       "budget_tier": "STANDARD",
       "total_budget_inr": 15000.0,
       "fitness_level": "MODERATE",
       "language": "en"
     }'
```

### 3. Trigger Emergency SOS & 140-Char SMS Dispatch
```bash
curl -X POST "http://localhost:8000/api/v1/sos/trigger" \
     -H "Content-Type: application/json" \
     -d '{
       "user_name": "Arnav Sharma",
       "user_phone": "+91-9876543210",
       "latitude": 19.8000,
       "longitude": 85.8300,
       "altitude_m": 12,
       "medical_condition": "Acute heat exhaustion",
       "battery_level_percent": 18,
       "emergency_contacts": ["+91-9811122233"]
     }'
```

### 4. Live Risk Recheck & Hazard Breach Evaluation
```bash
curl -X POST "http://localhost:8000/api/v1/risk/recheck" \
     -H "Content-Type: application/json" \
     -d '{
       "trip_id": "trip_demo_01",
       "destination_id": "Puri",
       "lat": 19.7983,
       "lon": 85.8249,
       "altitude_m": 8,
       "weather": {
         "precipitation_mm_hr": 45.0,
         "wind_speed_kmh": 65.0,
         "temperature_c": 28.0,
         "imd_alert": "RED"
       }
     }'
```

### 5. LLM Reasoning Layer Integration Snippet
```python
# Structured LLM safety briefing synthesis using Google Gemini API
url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key={GEMINI_API_KEY}"
payload = {
    "contents": [{"parts": [{"text": f"Review tourist itinerary for {destination} ({region_type}). Risk score: {score}/100."}]}],
    "generationConfig": {"response_mime_type": "application/json"}
}
# Automatically defaults to deterministic rule-based explainability if API key is not present
```

---

## Configuration

All configuration is managed via environment variables or a `.env` file:

| Environment Variable | Default Value | Description |
| :--- | :--- | :--- |
| `PROJECT_NAME` | `SafeTrail AI — Pan-India Tourist Safety` | Display title for OpenAPI and Swagger documentation. |
| `VERSION` | `2.0.0` | API SemVer release tag. |
| `API_V1_STR` | `/api/v1` | Root prefix for API version 1 routers. |
| `REDIS_URL` | `redis://localhost:6379/0` | Connection string for Redis caching. Falls back to in-memory mock if offline. |
| `DATABASE_URL` | `sqlite+aiosqlite:///./safetrail.db` | SQLAlchemy async database connection URI (supports PostGIS on PostgreSQL). |
| `NOMINATIM_URL` | `https://nominatim.openstreetmap.org` | OpenStreetMap Nominatim geocoding gateway. |
| `OPEN_METEO_URL` | `https://api.open-meteo.com/v1/forecast`| Meteorological API for live precipitation, wind, and alerts. |
| `OVERPASS_API_URL`| `https://overpass-api.de/api/interpreter` | Overpass QL endpoint for hospital, police, and shelter discovery. |
| `OSRM_ROUTING_URL`| `https://router.project-osrm.org` | OSRM routing gateway for topological road and walking geometries. |
| `DEFAULT_CURFEW_HOUR` | `18` | Default fallback sunset curfew hour (IST). |

---

## Get Started

### Prerequisites
- **Python**: 3.11 or higher
- **Node.js**: 18.x or 20.x LTS
- **npm** or **yarn**

### 1. Clone & Set Up Backend
```bash
# Clone the repository
git clone https://github.com/your-username/safetrail-ai.git
cd safetrail-ai/apps/api

# Create and activate virtual environment
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start FastAPI server (Port 8000)
python -m uvicorn app.main:app --port 8000 --host 127.0.0.1 --reload
```

### 2. Set Up Frontend Web Application
```bash
# In a separate terminal window
cd safetrail-ai/apps/web

# Install dependencies
npm install

# Start Vite React development server (Port 5173 / 3000)
npm run dev
```

Visit `http://localhost:5173` in your browser. Interactive Swagger API documentation is available at `http://localhost:8000/api/v1/docs`.

---

## Docker Quick Start

Deploy the full stack with a single command:

```bash
# Build and start all services
docker compose up --build -d

# Verify health status
curl http://localhost:8000/health
```

### Sample Health Check Response
```json
{
  "status": "healthy",
  "service": "SafeTrail AI — Pan-India Tourist Safety Engine",
  "version": "2.1.0",
  "supported_region_types": [
    "HILL_MOUNTAIN",
    "COASTAL_MARINE",
    "FOREST_WILDLIFE",
    "DESERT_ARID",
    "URBAN_HERITAGE",
    "PLAINS_RIVERINE"
  ],
  "redis_caching": "ACTIVE (Async Redis / Fast InMemory Fallback)",
  "spatial_engine": "PostGIS / Shapely Polygon Intersection",
  "coverage": "All 28 States & 8 Union Territories of India"
}
```

---

## Error Handling

The API returns standard RFC-7807 compliant error payloads with descriptive status codes:

| Error Code | HTTP Status | Description |
| :--- | :--- | :--- |
| `OUTSIDE_SOVEREIGN_TERRITORY` | `400 Bad Request` | Coordinates fall outside the sovereign bounding box of India (`6.0°N–37.6°N`, `68.0°E–97.5°E`). |
| `INVALID_AUTHORIZATION_TOKEN` | `401 Unauthorized` | JWT token signature verification failed, expired, or malformed. |
| `RATE_LIMIT_EXCEEDED` | `429 Too Many Requests` | Client IP exceeded 60 requests/minute. Header includes `Retry-After`. |
| `DESTINATION_NOT_FOUND` | `404 Not Found` | Geocoding service could not resolve place name within Indian bounds. |
| `WEATHER_API_TIMEOUT` | `200 OK (Degraded)` | External weather API timed out; system gracefully falls back to seasonal baseline. |
| `OVERPASS_SERVICE_DEGRADED` | `200 OK (Degraded)` | Public Overpass instance throttled; system utilizes synthesized emergency grid within 1–5km. |

---

## Testing

SafeTrail AI includes comprehensive end-to-end integration, pilgrimage seed verification, and parameterized security audit test suites:

```bash
# Run Pilgrimage Seed & Multi-Archetype Risk Engine Tests (29 Scenarios)
python -m pytest apps/api/test_pilgrimage_seed_and_risk.py -v

# Run Parameterized QA & Security Audit Suite (24 Tests covering all 6 regions)
python -m pytest apps/api/test_qa_security_audit.py -v

# Run Complete Combined Test Suite (53 Tests)
python -m pytest apps/api/test_qa_security_audit.py apps/api/test_system_e2e.py apps/api/test_pilgrimage_seed_and_risk.py -v

# Run Frontend Type-Check & Production Build Validation
cd apps/web && npm run build
```

### Test Suite Execution Output
```
============================= test session starts =============================
platform win32 -- Python 3.14.6, pytest-9.1.1 -- rootdir: /safetrail-ai
collected 53 items

apps/api/test_qa_security_audit.py::test_region_classifier_generalization PASSED      [ 33%]
apps/api/test_qa_security_audit.py::test_risk_engine_weight_formulations PASSED       [ 35%]
apps/api/test_qa_security_audit.py::test_sovereign_territory_validation PASSED        [ 37%]
apps/api/test_qa_security_audit.py::test_jwt_security_and_guest_tokens PASSED         [ 39%]
apps/api/test_qa_security_audit.py::test_sos_dispatch_and_sms_length PASSED           [ 41%]
apps/api/test_qa_security_audit.py::test_itinerary_15_percent_emergency_reserve PASSED[ 43%]
apps/api/test_qa_security_audit.py::test_spatial_geofencing_detection PASSED          [ 45%]
apps/api/test_pilgrimage_seed_and_risk.py::test_generic_destination_resolution PASSED [ 72%]
apps/api/test_pilgrimage_seed_and_risk.py::test_pilgrimage_circuits_endpoint PASSED   [ 75%]
apps/api/test_pilgrimage_seed_and_risk.py::test_destination_search_pilgrimage PASSED  [ 79%]
apps/api/test_pilgrimage_seed_and_risk.py::test_risk_archetype_kedarnath PASSED       [ 82%]
apps/api/test_pilgrimage_seed_and_risk.py::test_risk_archetype_rameswaram PASSED      [ 86%]
apps/api/test_pilgrimage_seed_and_risk.py::test_risk_archetype_akshardham PASSED      [ 89%]
apps/api/test_pilgrimage_seed_and_risk.py::test_risk_archetype_shirdi PASSED          [ 93%]
apps/api/test_pilgrimage_seed_and_risk.py::test_hilltop_staircase_palitana PASSED     [ 96%]
apps/api/test_pilgrimage_seed_and_risk.py::test_no_hardcoded_destination PASSED       [100%]

======================= 53 passed in 5.69s (100% PASS RATE) =======================
```

---

## Design Philosophy

1. **Explainable Over Black-Box**: Lives depend on safety decisions. Risk scoring uses deterministic mathematical equations, verified weight vectors, and official agency advisories rather than opaque deep neural networks.
2. **Safety Data Must Never Be Stale**: Cache layers implement strict TTL policies (15-min weather, 6-hr emergency amenities, 24-hr geocodes) with automatic real-time WebSocket hazard invalidation.
3. **Works Anywhere in India, Not Just One Trail**: Dynamic geocoding, real elevation sampling, and data-driven environmental classification eliminate hardcoded geographic silos.
4. **Field Resilience & Graceful Degradation**: If cloud networks drop, IndexedDB and 140-char 2G SMS payloads ensure the system remains operational in remote Himalayan passes or dense wildlife sectors.

---

## Roadmap & Future Work

- [ ] **Direct INCOIS API Integration**: Native webhook sync with Indian National Centre for Ocean Information Services for live coastal swell surge bulletins.
- [ ] **FSI Forest Fire Thermal Feed**: Ingestion of real-time MODIS / VIIRS active forest fire telemetry from the Forest Survey of India.
- [ ] **BLE Mesh Peer-to-Peer SOS Relay**: Off-grid tourist-to-tourist Bluetooth Low Energy (BLE) packet forwarding when cellular towers are inaccessible.
- [ ] **Biometric Darshan Queue Integration**: Live API synchronization with temple trust queue management portals (e.g., TTD Tirupati, Shri Jagannath Temple Administration).

---

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.