SafePath AI: GeoAI & Safety-Evidence Route Navigation Platform

SafePath AI is an enterprise-grade GeoAI pedestrian routing and safety infrastructure decision-support platform. It evaluates multi-modal municipal telemetry (smart LED lighting, CCTV nodes, 24/7 emergency callboxes, open commercial active edges, and historical incident report context) to generate transparent, deterministic safety evidence scores for walking routes.

---

1. System Overview

SafePath AI bridges municipal spatial data, real-time routing engines, and grounded generative AI reasoning to help pedestrians select safer walking routes while providing city authorities with infrastructure gap analytics.

Key Capabilities

• Deterministic 6-Factor Safety Scoring Engine: Transparent, weighted safety scoring based strictly on physical evidence.
• Missing Telemetry Awareness: Never invents missing data; flags unmeasured parameters and downgrades confidence levels dynamically.
• 7-Tool Agentic Pipeline: Autonomous tool calling pipeline for candidate route extraction, lighting calculation, CCTV density analysis, emergency hub proximity lookup, incident context aggregation, and RAG grounding.
• Grounded RAG Knowledge Base: Uses vector similarity retrieval over CPTED (Crime Prevention Through Environmental Design) guidelines and municipal lighting standards with explicit citations.
• Interactive GeoAI Map: Custom Leaflet visualization with interactive route polylines, infrastructure nodes, hazard clusters, and gap corridors.
• Governance & Infrastructure Analytics: Heatmap dashboards for municipal urban planners to prioritize lighting and CCTV investments.

---

2. Architecture Diagram

┌──────────────────────────────────────────────────────────────────────────────────┐
│                                 FRONTEND (React + Vite)                          │
│  ┌────────────────────┐  ┌─────────────────────┐  ┌───────────────────────────┐  │
│  │ Route Search Form  │  │ Interactive Map     │  │ Route Recommendation Card │  │
│  └─────────┬──────────┘  └──────────┬──────────┘  └─────────────┬─────────────┘  │
│            │                        │                           │                │
│  ┌─────────▼────────────────────────▼───────────────────────────▼─────────────┐  │
│  │                     State Management & API Client                          │  │
│  └──────────────────────────────────┬─────────────────────────────────────────┘  │
└─────────────────────────────────────┼────────────────────────────────────────────┘
                                      │ HTTP / REST (/api/analyze, /api/rag, /api/agent)
┌─────────────────────────────────────▼────────────────────────────────────────────┐
│                             BACKEND (Express + Node.js)                          │
│                                                                                  │
│  ┌────────────────────────────────────────────────────────────────────────────┐  │
│  │                     Gemini Agent Orchestrator                             │  │
│  │          (Tool calling with Gemini 2.5 Flash / Deterministic Fallback)      │  │
│  └──────┬────────────┬─────────────┬─────────────┬────────────┬───────────────┘  │
│         │            │             │             │            │                  │
│  ┌──────▼─────┐ ┌────▼───────┐ ┌───▼──────┐ ┌────▼───────┐ ┌──▼────────────┐     │
│  │ Routing    │ │ Lighting   │ │ CCTV     │ │ Callbox    │ │ Incident    │     │
│  │ Tool       │ │ Telemetry  │ │ Node Tool│ │ Hub Tool   │ │ Context Tool│     │
│  └──────┬─────┘ └────┬───────┘ └───┬──────┘ └────┬───────┘ └──┬────────────┘     │
│         └────────────┼─────────────┼─────────────┼────────────┘                  │
│                      ▼             ▼             ▼                               │
│  ┌────────────────────────────────────────────────────────────────────────────┐  │
│  │                       Scoring Engine & Math Evaluator                      │  │
│  │          Score = ∑ (factor_value × factor_weight) × Data_Availability      │  │
│  └──────────────────────────────────┬─────────────────────────────────────────┘  │
│                                     │                                            │
│  ┌──────────────────────────────────▼─────────────────────────────────────────┐  │
│  │                        Vector Store & RAG Engine                           │  │
│  │          In-Memory Cosine Similarity + Grounded Citation Verification       │  │
│  └────────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────────┘

---

3. Setup Instructions

Prerequisites

• Node.js 18+ or Node.js 20+
• npm 9+

Quick Start

1. Clone the repository:

   git clone https://github.com/your-org/safepath-ai.git
   cd safepath-ai

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env
   # Add your GEMINI_API_KEY to .env if available (optional, deterministic engine works without it)

4. Run development server:

   npm run dev

   Open http://localhost:3000 in your browser.

5. Run test suite:

   npm run test

6. Build for production:

   npm run build
   npm start

---

4. Environment Variable Documentation

Variable Name	Required?	Default / Example	Description
GEMINI_API_KEY	Optional	AIzaSy...	Gemini API key for natural language agent reasoning. If missing, the app seamlessly runs on the deterministic 7-tool orchestrator.
APP_URL	Optional	http://localhost:3000	Host URL for self-referential endpoints and production deployment routing.
NODE_ENV	Optional	development	Environment mode (development or production).

Security Note: Never commit actual API keys to git. Define keys in .env or inject via host secret management.

---

5. API Documentation

POST /api/analyze

Executes complete SafePath AI route analysis for a origin and destination.

Request Body:

{
  "origin": "Downtown Central Station",
  "destination": "Innovation Tech Campus",
  "timeOfDay": "Night (10:15 PM)",
  "travelMode": "Standard Pace"
}

Response:

{
  "success": true,
  "data_availability_status": "Complete",
  "recommended_route": {
    "route_id": "route-b",
    "route_name": "Route B (Commercial Corridor)",
    "safety_score": 89,
    "travel_time": "24 min",
    "distance": "1.8 km",
    "recommendation_statement": "This route is recommended based on available safety evidence."
  },
  "candidate_routes_evaluated": [...],
  "tool_execution_logs": [...]
}

POST /api/rag

Performs vector retrieval over CPTED guidelines and municipal lighting documentation.

Request Body:

{
  "query": "What are CPTED standards for pedestrian pathway lighting?",
  "top_k": 3
}

---

6. RAG Documentation

The Retrieval-Augmented Generation (RAG) module grounds all safety explanations in official CPTED (Crime Prevention Through Environmental Design) municipal manuals and IESNA lighting standards.

Features

• In-Memory Vector Search: Uses TF-IDF cosine similarity embeddings over curated municipal policy documents.
• Strict Citation Requirements: Every RAG passage returned includes document_title, section, citation_code, and relevance_score.
• Zero Hallucination Guard: If no relevant passages match the query threshold (score > 0.05), the engine explicitly returns results_found: false and "Relevant verified information was not found."

---

7. GeoAI Documentation

SafePath AI evaluates geographical segment attributes across spatial buffer zones (50m - 100m corridor width):

• Lighting Coverage Density: Calculates smart LED streetlamp frequency and average foot-candle illuminance along polyline segments.
• CCTV Node Proximity: Measures density of active municipal CCTV cameras within 50m of sidewalk paths.
• Emergency Callbox Buffer: Distance-decay calculation from 24/7 blue-light emergency help points and police sub-stations.
• Commercial Active Edge: Foot traffic density and open storefront ratio during late-night hours (21:00 - 05:00).
• Incident Context Density: Inverse historical report density along pathway segments (100 = minimal incident history).

---

8. Agent Tool Documentation

The Gemini agent and fallback orchestrator execute a deterministic 7-tool sequence:

1. get_candidate_routes: Fetches physical paths between origin and destination.
2. get_lighting_telemetry: Measures streetlamp illuminance and density along segments.
3. get_cctv_telemetry: Retrieves active CCTV camera coverage percentages.
4. get_emergency_accessibility: Calculates distance to nearest 24/7 help callboxes.
5. get_incident_context: Evaluates historical report density context.
6. get_public_activity_index: Assesses commercial open-storefront density.
7. search_rag_knowledge_base: Retrieves grounded CPTED design standards.

---

9. Safety Scoring Methodology

Mathematical Formula

$$\text{Safety Score} = \min\left(100, \max\left(0, \sum_{i=1}^{n} (V_i \times W_i)\right)\right)$$

Where:

• $V_i$ = Raw factor value ($0 - 100$)
• $W_i$ = Factor weight

Default Factor Weights

• Lighting Coverage: $25%$ ($W = 0.25$)
• Safety Infrastructure (CCTV): $20%$ ($W = 0.20$)
• Emergency Accessibility: $15%$ ($W = 0.15$)
• Historical Incident Context: $15%$ ($W = 0.15$)
• Public Activity / Foot Traffic: $15%$ ($W = 0.15$)
• Route Connectivity / Sidewalk Quality: $10%$ ($W = 0.10$)

Missing Data Rule

If any factor $V_i$ is null or undefined, its weighted contribution is set to $0$ and the factor is explicitly marked as Unmeasured / Unavailable. It is never filled with random or predicted numbers.

---

10. Responsible AI Documentation

1. Non-Predictive / Non-Profilative: SafePath AI does NOT perform predictive policing, individual crime forecasting, or demographic profiling.
2. Telemetry Transparency: All scores are accompanied by an itemized factor breakdown explaining exact score origins.
3. Missing Telemetry Warning: When sensor coverage is low ($< 50%$), confidence is automatically downgraded from High to Medium or Low, alerting pedestrians to walk with standard caution.

---

11. Demo Instructions

1. Select Downtown Central Station as Start and Innovation Tech Campus as Destination.
2. Click Analyze Walking Routes.
3. Inspect the recommended Route B (Commercial Corridor) with a Safety Score of 89/100.
4. Click Inspect Formula & Data Evidence to review factor weightings and telemetry breakdown.
5. Toggle map layers (Green Recommended, Amber Gaps, Blue Infrastructure, Red Hotspots) to inspect spatial distribution.
6. Navigate to the Governance Dashboard tab to view municipal lighting gap analytics.

---

12. Known Limitations

• Simulated Municipal Feed: In the demonstration environment, municipal sensor telemetry is drawn from calibrated synthetic geo-datasets. Real-world deployment requires integration with city OpenData APIs or PostGIS databases.
• Static Weather Inputs: Current safety scoring assumes standard clear weather conditions. Heavy snow or flooding effects require real-time weather API overlays.

---

13. Final Folder Structure

safepath-ai/
├── .env.example                # Environment variable documentation & template
├── metadata.json               # Application metadata and platform capabilities
├── package.json                # Project dependencies and npm scripts
├── README.md                   # Complete production & technical documentation
├── server.ts                   # Express production server & API route proxies
├── vite.config.ts              # Vite bundle configuration
├── src/
│   ├── main.tsx                # Client entry point
│   ├── App.tsx                 # Main application layout & state orchestrator
│   ├── types.ts                # TypeScript interfaces and global data models
│   ├── scoringEngine.ts        # Deterministic 6-factor safety scoring engine
│   ├── apiClient.ts            # Client API wrapper
│   ├── mockData.ts             # Calibrated municipal spatial datasets
│   ├── __tests__/              # Automated Vitest unit test suite
│   │   └── safepath.test.ts    # 15 tests covering all 14 edge cases
│   ├── agent/                  # Agent tool definitions & execution engine
│   │   ├── agentCore.ts        # Agent orchestrator & fallback pipeline
│   │   └── tools.ts            # 7 deterministic safety tools
│   ├── rag/                    # Vector retrieval engine
│   │   └── vectorStore.ts      # In-memory TF-IDF vector store & CPTED knowledge base
│   └── components/             # Modular React UI components
│       ├── Header.tsx          # Navigation header & tab switcher
│       ├── RouteSearchForm.tsx # Mobile-optimized start/destination search
│       ├── InteractiveMap.tsx  # Leaflet map visualization
│       ├── SafetyLegend.tsx    # Map layer toggle legend
│       ├── RouteCard.tsx       # Route option display card
│       ├── RouteRecommendationPanel.tsx # Detailed score breakdown panel
│       ├── ExplainableAIPanel.tsx       # XAI decision transparency modal
│       ├── GovernanceDashboard.tsx      # Municipal planner analytics tab
│       ├── AgentOrchestratorView.tsx    # Agent tool execution inspector
│       ├── RAGKnowledgeView.tsx         # CPTED knowledge search tab
│       ├── DisclaimerBanner.tsx         # Safety disclaimer footer
│       ├── AboutView.tsx                # Methodology documentation tab
│       └── PrivacyView.tsx              # Responsible AI & privacy policy tab