Skip to content
BranchesTags

Repository files navigation

🛡️ RideBuddy

Community-Driven & AI-Verified Real-Time Road Safety Co-Pilot

Next.js React TypeScript PostgreSQL Google Gemini PWA Ready License

Empowering daily commuters, two-wheeler riders, and municipal engineers with real-time hazard radar, hazard-scored navigation, AI damage analysis, and automated civic work order workflows.

Explore Features • System Architecture • Quickstart • API Reference • GovOps Portal • PWA Guide

📖 Table of Contents

  1. Overview & Problem Statement
  2. Key Features
  3. System Architecture
  4. Tech Stack
  5. Database Schema & Migrations
  6. API Endpoints
  7. Environment Variables
  8. Quickstart & Installation
  9. Progressive Web App (PWA)
  10. Performance, Battery & Mobile Optimization
  11. Contributing & License

🎯 Overview & Problem Statement

Potholes, waterlogged underpasses, road collapses, and unlit construction debris cause hundreds of thousands of vehicular accidents, severe spinal injuries, and billions in vehicle damages every year worldwide.

RideBuddy bridges the gap between citizens on the road and municipal public works departments (PWD):

  1. For Riders & Drivers: Provides real-time audio/visual warnings for upcoming road hazards, hands-free voice logging, safest-route navigation, and squad convoys.
  2. For Municipalities & PWD: Automates work order generation, tracks repair SLAs (24h/72h/168h), leverages AI to predict monsoon road washouts, and validates contractor repairs through citizen ground-truth verification.

🌟 Key Features

1. Multimodal Gemini AI Hazard Verification

  • Powered by Google Gemini Vision AI (gemini-1.5-flash / gemini-2.0-flash).
  • Analyzes uploaded road photos in real time:
    • Detects hazard authenticity (rejects indoor photos, screenshots, or unrelated images).
    • Estimates severity score (L1 Low, L2 Moderate, L3 Critical Danger).
    • Measures pothole depth, surface fracturing, and vehicle bottom-out risks.
    • Auto-generates structured civic descriptions with high confidence tags.

2. Hands-Free Voice Logger (Rider Safety)

  • Built using the native Web Speech API for two-wheeler riders navigating busy traffic.
  • Rider simply says: "Report pothole", "Hazard ahead", or "Bad road here".
  • RideBuddy immediately captures high-accuracy GPS coordinates, creates a hazard pin, and chimes an audio confirmation: "Hazard logged at your location".

3. "Proof of Repair" Civic Verification Loop

  • The Civic Trust Mechanism:
    1. Municipal road crews patch a pothole and upload a "Repaired Road" photo in the GovOps Portal.
    2. The next time a citizen rides within 60 meters of those coordinates, RideBuddy sends a subtle audio/visual prompt: "PWD marked this pothole as repaired. Confirm fix?"
    3. Riders tap "Yes, Fixed 👍" or "Still Broken ⚠️".
    4. Once confirmed by 2 independent riders, the contractor receives an SLA Quality Stamp, and each citizen earns +50 Karma points. If reported broken, the hazard automatically reopens with priority escalation.

4. AI Monsoon Risk & Road Deterioration Predictor

  • Aggregates road clusters with historical severity, waterlogging propensity, and user reports.
  • Computes the Road Quality Index (RQI) and Pre-Monsoon Vulnerability Score (0–100):
    • Critical Risk (Red): Severe asphalt erosion, deep rutting, high monsoon flood risk.
    • Warning (Yellow): Medium surface cracking requiring preventive tar sealing.
    • Good (Green): Stable road base.
  • Outputs automated engineering recommendations for PWD division engineers before monsoon seasons.

5. Dynamic Hazard-Scored Routing

  • Integrates with OSRM (Open Source Routing Machine) to retrieve alternative driving routes.
  • Performs fast spatial bounding-box intersections with active database hazards.
  • Calculates dynamic Safety Penalty Scores based on hazard density and severity, ranking routes from Safest (Recommended) to Fastest but Risky.

6. Real-Time Squad Convoys

  • Enables riders to create private squad rooms with shareable 6-digit convoy codes.
  • Synchronizes real-time live telemetry (GPS coordinates, speed, heading, and distance to destination) across all members of a motorcycle group.

7. Municipal GovOps Command Center

  • Live Operations Radar: MapLibre GL spatial map with Light, Dark, and Satellite layers.
  • Automated Work Order Generator: Generates formal PDF/Printable PWD work orders with unique IDs (PWD-WO-2026-XXXXX), SLA countdowns, contractor assignments, and coordinates.
  • Spatial GeoJSON & CSV Exporters: 1-click export for municipal GIS databases and QGIS workflows.
  • Image Lightbox with Zoom Loupe: Inspect road evidence at 2.8x magnification.

🏗️ System Architecture

flowchart TD
    subgraph Client ["Client Layer (Citizen & GovOps PWA)"]
        UI[Next.js 15 App Router / React 19]
        SW[Service Worker / CacheStorage / IndexedDB]
        GPS[Hardware GPS Stream & Geolocation API]
        Voice[Web Speech Recognition Engine]
        MapGL[MapLibre GL Vector Engine]
    end

    subgraph Server ["Next.js Serverless Route Handlers"]
        HazardsAPI["/api/hazards (CRUD, Voice, Proximity)"]
        VerifyAPI["/api/hazards/:id/repair-verify"]
        AuthAPI["/api/auth (JWT + Bcrypt)"]
        MonsoonAPI["/api/analytics/monsoon-risk"]
        SquadAPI["/api/squads (Convoy Telemetry)"]
    end

    subgraph AI ["Google Gemini AI"]
        VisionAI["Gemini Vision Multi-Modal Pipeline"]
    end

    subgraph Database ["Data & Storage Layer"]
        PG[(PostgreSQL Database / Neon)]
        Tables["hazards | users | votes | squads | repair_verifications"]
    end

    UI -->|Online HTTP / REST| Server
    UI -->|Offline Fallback| SW
    GPS -->|Coordinates| HazardsAPI
    Voice -->|Voice Triggers| HazardsAPI
    HazardsAPI -->|Image Payload| VisionAI
    VisionAI -->|Severity & Tags| HazardsAPI
    Server -->|SQL Queries & Pooling| PG
    PG --> Tables
    MapGL <-->|Vector Tiles & Bounding Boxes| HazardsAPI
Loading

💻 Tech Stack

Domain Technology Description
Framework Next.js 15 (App Router) High-performance React server and client components
UI Library React 19 + TypeScript Strict type safety, deterministic rendering, zero cascades
Styling TailwindCSS + Vanilla CSS Modern glassmorphism, responsive themes, custom design tokens
Mapping Engine MapLibre GL + Turf.js Hardware-accelerated WebGL vector tiles & geospatial analysis
Routing Engine OSRM API Geodesic pathfinding with dynamic hazard penalty penalties
Database PostgreSQL 16 (pg pool) Scalable relational storage with spatial index support
AI / Machine Learning Google Gemini Vision AI Real-time image validation, depth and hazard classification
Speech Engine Web Speech API Hands-free continuous voice recognition & speech synthesis
State & Cache TanStack React Query Optimistic mutations, real-time query refetching
PWA & Offline Service Worker / Cache API Standalone installable PWA with offline fallback caching

🗄️ Database Schema

RideBuddy uses a normalized PostgreSQL schema with indexed spatial columns:

-- Core Users Table
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  role VARCHAR(50) DEFAULT 'citizen', -- 'citizen' | 'official'
  karma_points INTEGER DEFAULT 0,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Hazards Table
CREATE TABLE hazards (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id),
  type VARCHAR(100) NOT NULL, -- 'pothole', 'flood', 'accident', 'roadblock', etc.
  severity INTEGER NOT NULL,  -- 1 (Low), 2 (Medium), 3 (High/Critical)
  lat DOUBLE PRECISION NOT NULL,
  lng DOUBLE PRECISION NOT NULL,
  description TEXT,
  image_url TEXT,
  repair_image_url TEXT,
  status VARCHAR(50) DEFAULT 'active', -- 'active' | 'in_progress' | 'resolved'
  repair_verified BOOLEAN DEFAULT FALSE,
  repair_verified_at TIMESTAMP WITH TIME ZONE,
  repair_verify_count INTEGER DEFAULT 0,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Citizen Repair Verifications Table
CREATE TABLE repair_verifications (
  id SERIAL PRIMARY KEY,
  hazard_id INTEGER REFERENCES hazards(id) ON DELETE CASCADE,
  user_id INTEGER REFERENCES users(id),
  is_fixed BOOLEAN NOT NULL,
  comment TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Squad Convoys Table
CREATE TABLE squads (
  id SERIAL PRIMARY KEY,
  code VARCHAR(10) UNIQUE NOT NULL,
  name VARCHAR(255) NOT NULL,
  leader_id INTEGER REFERENCES users(id),
  destination_lat DOUBLE PRECISION,
  destination_lng DOUBLE PRECISION,
  destination_name TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

🔌 API Endpoints

🚨 Hazard Management

  • GET /api/hazards: Retrieve all active hazards with optional bounding box and type filters.
  • POST /api/hazards: Submit a new hazard report (supports standard photo + Gemini AI, or hands-free voice_report: true).
  • PATCH /api/hazards/[id]/status: Update hazard status (active → in_progress → resolved) with repair proof photo upload.
  • GET /api/hazards/nearby-resolved?lat={lat}&lng={lng}&radius=60: Query resolved hazards within 60 meters for citizen verification prompts.
  • POST /api/hazards/[id]/repair-verify: Submit citizen verification result (is_fixed: true/false). Awards +50 Karma and verifies SLA.

👥 Squad Telemetry

  • POST /api/squads: Create a new convoy room.
  • POST /api/squads/join: Join a convoy using a 6-digit access code.
  • POST /api/squads/telemetry: Broadcast live GPS coordinates, speed, and heading.

🔐 Authentication

  • POST /api/auth/register: Create citizen or official account.
  • POST /api/auth/login: Authenticate and receive a signed JWT cookie (7-day validity).
  • GET /api/auth/me: Retrieve authenticated user session and karma level.

⚙️ Environment Variables

Create a .env.local file in the root directory:

# Database Configuration (PostgreSQL / Neon / Supabase / Local)
DATABASE_URL="postgresql://postgres:password@localhost:5432/ridebuddy?sslmode=prefer"

# JWT Authentication Secret
JWT_SECRET="your-super-strong-jwt-secret-key-change-in-production"

# Google Gemini API Key (For AI Image Hazard Verification)
GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere"

# MapTiler Key for Vector Tiles (Optional — falls back to CARTO Voyager/Dark raster tiles)
NEXT_PUBLIC_MAPTILER_KEY=""

# Base URL (Optional — defaults to relative paths in Next.js)
NEXT_PUBLIC_API_URL=""

🚀 Quickstart & Installation

Prerequisites

  • Node.js: v18.18.0 or higher (v20+ recommended)
  • PostgreSQL: v14+ database instance

1. Clone the Repository

git clone https://github.com/your-username/ride_buddy.git
cd ride_buddy

2. Install Dependencies

npm install

3. Apply Database Migrations

Run the SQL migration scripts located in the migrations/ directory against your PostgreSQL database:

psql $DATABASE_URL -f migrations/001_init_schema.sql
psql $DATABASE_URL -f migrations/007_repair_verification.sql

4. Start Local Development Server

npm run dev

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

  • Citizen Safe Navigation: http://localhost:3000/
  • Welcome Landing Page: http://localhost:3000/welcome
  • Citizen Dashboard: http://localhost:3000/dashboard
  • GovOps Municipal Command Center: http://localhost:3000/gov
  • Monsoon Risk AI Intelligence: http://localhost:3000/gov/analytics

5. Production Build

npm run build
npm run start

📱 Progressive Web App (PWA)

RideBuddy is built from the ground up as a 100% compliant Progressive Web App:

  • Standalone Experience: Runs full-screen on iOS and Android without browser address bars.
  • Dead-Zone Protection: Service Worker (public/sw.js) intercepts API requests with an automatic 3.5s timeout, instantly falling back to cached hazards and map tiles during mobile network drops on highways.
  • 1-Tap Installation:
    • Android / Chrome / Edge: Prompts native one-tap install banner.
    • iOS Safari: Interactive modal guides users to tap Share ⎋ → Add to Home Screen ➕.

⚡ Performance, Battery & Offline Resilience

  • Spatial Bounding-Box Filtering: Proximity checks use lightweight coordinate window filters (~350m threshold) prior to executing geodesic calculations, reducing mobile CPU load by over 95%.
  • Intelligent GPS Hardware Throttling: Replaced aggressive polling with a hardware stream watcher and a 4s fallback heartbeat, drastically extending smartphone battery life during long rides.
  • Deterministic React 19 State Architecture: 0 cascading renders, 0 ESLint warnings, and strict memoization of spatial clusters and routing penalties.

🤝 Contributing & License

Contributions, issues, and feature requests are welcome!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Distributed under the MIT License. See LICENSE for more information.

Built with ❤️ for safer roads everywhere.

About

RideBuddy Community-Driven & AI-Verified Safe Navigation

ridebuddy-six.vercel.app

Topics

ai-governancecommunitycommunity-platformhazard-detectionhazard-mapindian-roadsmapmaplibre-pluginsnavigationnavigationenginepostgresride-sharingsaferidesih2025

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages