resq

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 9)

ResQ (Rescue) is a production disaster-response platform for Sri Lanka live flood monitoring, SOS reporting, relief coordination and admin dashboards. This repository contains the web frontend, mobile app, and backend services.

resq Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

#  ResQ - National Disaster Response Platform

[![Production Status](https://img.shields.io/badge/status-production%20deployed-brightgreen)](https://resq-five.vercel.app)
[![Built For](https://img.shields.io/badge/built%20for-Sri%20Lanka-red)](https://www.dmc.gov.lk)

**ResQ Hub — Version 1.1** (Released: 2025-12-05)

## What's New (v1.1)

- OAuth2 Automatic Token Refresh for external FloodSupport APIs (secure, backend-managed; 7-day token lifetime).
- Enhanced map popup cards across the Citizen Map: modern mobile-first card UI with Call, Nav (directions), and Details buttons for SOS, Flood, Disaster, and Relief markers.
- Improved UX for SOS/recovery workflows: better priority badges, condition tags, and a detailed modal view for emergency information.
- Updated documentation and changelog entries for v1.1.

ResQ (Rescue) is a production disaster-response platform for Sri Lanka — live flood monitoring, SOS reporting, relief coordination and admin dashboards. This repository contains the web frontend, mobile app, and backend services.

Live deployment (primary):
- Frontend: https://resq-five.vercel.app
- Backend: https://resq-backend-3efi.onrender.com

Quick links:
- Documentation: `./docs/`
- Contributing guide: `CONTRIBUTING.md`
- Issue templates: `.github/ISSUE_TEMPLATE/`

Getting started (developer): see `CONTRIBUTING.md` for full setup and coding guidelines. Minimal steps:

```powershell
npm install
cd src/web-dashboard/frontend
npm install
npm run dev      # start frontend (Vite)
cd ../../backend
npm install
npm run dev      # start backend (nodemon / node)
```

Contributing
- Please read `CONTRIBUTING.md` before opening issues or pull requests. It contains environment setup, lint/test commands, and PR guidelines.

License
- This project is licensed under the Apache License 2.0. Apache-2.0 is a permissive, widely-used open-source license that allows commercial use, modification, distribution and private use while protecting contributors with a patent grant. If you rely on third-party or government data/APIs, confirm their reuse terms separately.

Support / Contact
- Security issues: use `.github/ISSUE_TEMPLATE/security_disclosure.md` or email the maintainer at `shalonfernando52@gmail.com`.
- General questions or PR/maintainer contact: `shalonfernando52@gmail.com`.

----

For more details (architecture, API docs, deployment), see the `docs/` folder.
- 🌊 **Live Flood Monitoring** - Real-time water levels from 39 DMC gauging stations
  - 15-minute update intervals
  - Water level trends (Rising/Falling)
  - Alert status: MAJOR, MINOR, ALERT, NORMAL
  - Rainfall data and timestamps
  
- 🗺️ **Interactive Risk Map** - Leaflet-powered disaster visualization
  - Flood alerts with custom markers (🌊)
  - Relief camps locations (⛺)
  - User location with accurate geocoding (📍)
  - Shows: "St Mary's Road, Kochchikade, Gampaha District"
  - Clickable markers with detailed info popups

- 📊 **Dashboard Statistics**
  - Total road reports
  - Active disasters
  - Affected districts
  - Blocked routes

#### Relief & Support
- 🆘 **Relief Demand Tracker** - Find nearby assistance
  - Search radius: 5-200km (debounced slider)
  - Distance-sorted results
  - Urgency filtering (emergency, high, medium, low)
  - Shows help requests + volunteer contributions
  - Real-time availability status
  
- 💚 **Volunteer Registration** - Offer support to affected communities
  - Comprehensive form (name, contact, location)
  - Select contribution type (goods, services, labor)
  - Specify resources available
  - Set urgency level
  - Submitted to Supabase Relief API

- 📞 **Emergency Contacts** - District-specific DDMCU hotlines
  - 4 main emergency services (Fire, Police, Ambulance, Disaster)
  - District-specific contacts with direct call buttons
  - Automatic district detection from user location

#### Navigation & Safety
- 🛣️ **LankaRouteWatch** - Safe route planning
  - Location search with Nominatim autocomplete
  - Replace district dropdowns with address search
  - Road hazard reports with distances
  - Risk level assessment (Low/Medium/High)
  - Detailed hazard breakdown when routes blocked
  - Real-time road closure information
  
- 💬 **AI Safety Assistant** - Google Gemini-powered guidance
  - Natural language emergency queries
  - Contextual safety recommendations
  - Quick question templates
  - 24/7 availability

#### Weather & Alerts
- ☁️ **Weather Dashboard** - Current conditions for user location
  - Temperature, humidity, wind speed
  - Weather icons and descriptions
  - Powered by OpenWeatherMap API
  
- 📋 **Recent Alerts Feed** - Latest DMC flood alerts
  - Severity badges (MAJOR, MINOR, ALERT)
  - Station names and river information
  - Water level changes
  - Sortable and filterable

### 🔐 Admin & Responder Dashboard (Authenticated Access)

#### Authentication & Access Control
- 👥 **Role-Based Authentication**
  - Individual ID + OTP login for admins/responders
  - JWT-based citizen authentication (signup/login)
  - JWT token-based sessions (30-day expiration)
  - Admin vs Responder vs Citizen permissions
  - Shadow account system for emergency SOS without registration
  - Secure logout with token cleanup

#### Emergency Management & Real-Time Communication
- 🚨 **SOS Dashboard** - Real-time emergency monitoring
  - Live signal feed from MongoDB
  - Auto-refresh every 30 seconds
  - Auto-escalation every 5 minutes
  - Priority sorting (Critical → High → Medium → Low)
  - Status management (Pending → Acknowledged → Responding → Resolved)
  - GPS coordinates display
  - Responder assignment workflow
  - Role-based filtering (admins see all, responders see active only)
  
- 💬 **Real-Time Messaging System** (Socket.io)
  - Bidirectional chat between citizens and responders
  - Message history for each SOS signal
  - Real-time notifications via WebSocket
  - Sender identification (citizen/responder/admin)
  - Message timestamps and read status
  - Auto-scroll to latest messages
  
- 📱 **Citizen SOS Dashboard**
  - View all personal SOS submissions
  - Track responder responses in real-time
  - Send messages to assigned responders
  - Update SOS status (resolved/false alarm)
  - 30-second auto-refresh
  - Click to expand message details
  
- 📝 **Reports Dashboard** - Citizen incident management
  - Review submitted reports with photos
  - Status updates (Pending → Verified → Resolved)
  - Filter by type (food, shelter, medical, danger)
  - Location and timestamp information
  - Batch operations

#### Disaster Operations
- 🗺️ **Live Disaster Heat Map** - Real-time DMC flood visualization
  - 39 gauging station markers
  - Color-coded alert status
  - Water level display
  - Rising/Falling indicators
  - Interactive popups
  - Auto-refresh every 5 minutes
  
- 🔥 **Disaster Management** - Create and track events
  - Disaster type selection (Flood, Landslide, Fire, etc.)
  - Severity levels (Low, Medium, High, Critical)
  - Affected districts and locations
  - Description and status tracking
  - Timeline management

#### Analytics & Insights
- 📊 **Analytics Dashboard** - Comprehensive metrics
  - Emergency Statistics
    - Total citizen reports
    - Pending reports count
    - Active disasters
    - Pending SOS signals
  - Visual charts with Recharts
  - Real-time data updates
  - Exportable reports
  
- ⛺ **Relief Camp Management** - Coordinate assistance
  - Track help requests from citizens
  - Monitor volunteer contributions
  - Location-based camp mapping
  - Urgency prioritization
  - Status updates (Pending → Available → Resolved)

#### Resource Operations
- 📦 **Resource Management** - Supply allocation
  - Inventory tracking
  - Distribution planning
  - Location-based assignment
  - Status monitoring
  - History logs

### Recent Updates (November 2025 - Production Deployment)

#### LankaRouteWatch Features
-  **Location Search** - Nominatim autocomplete for start/end locations (replacing district dropdowns)
-  **Road Hazard Display** - Shows detailed reports when no safe routes available
-  **Distance Calculation** - Displays hazard distance from route with severity indicators
-  **Backend Geocoding Proxy** - `/api/geocode/reverse` endpoint to avoid CORS issues

#### Production Fixes
-  **CORS Configuration** - Supports all Vercel preview deployments (*.vercel.app)
-  **JWT Authentication** - Environment variable validation with clear error messages
-  **Supabase Fallback** - Graceful handling when external API unavailable
-  **Error Logging** - Comprehensive console logging for debugging production issues
-  **Environment Setup** - Complete guide in `RENDER_ENV_SETUP.md`

#### Deployment Infrastructure
-  **Frontend Deployed** - Vercel with automatic preview deployments
-  **Backend Deployed** - Render with MongoDB Atlas (Singapore region)
-  **CI/CD Pipeline** - GitHub integration with auto-deploy on push
-  **Environment Variables** - Secure secret management on both platforms
-  **Deployment Guides** - `QUICK_DEPLOY.md`, `DEPLOYMENT_GUIDE.md`, `RENDER_ENV_SETUP.md`

#### Code Quality & Maintenance
-  **Removed Payment System** - Streamlined to core disaster response features
-  **Fixed Map Display** - Explicit height (600px) resolves Leaflet rendering
-  **DMC Timestamp Clarity** - "Last DMC Update" badge shows batch update time
-  **Volunteer System** - Complete CRUD workflow for relief contributions
-  **Admin Map Fix** - Uses live DMC flood data instead of MongoDB

##  Authentication & Messaging System

### Dual Authentication Architecture

The platform implements a sophisticated dual authentication system to handle different user types:

#### 1. **Citizen Authentication** (JWT-based)
- **Signup**: Email/phone + password with bcrypt hashing
- **Login**: Identifier (email or phone) + password
- **Token**: 30-day JWT with citizenId, phone, email, name, role, account_type
- **Storage**: localStorage (`citizen_token`, `citizen_user`)
- **Shadow Accounts**: Emergency SOS submissions create shadow accounts for follow-up
- **Features**:
  - No authentication required for emergency SOS
  - Optional login to track SOS history
  - Real-time messaging with responders
  - Personal SOS dashboard

#### 2. **Admin/Responder Authentication** (Individual ID + OTP)
- **Login**: Individual ID + OTP code
- **Mock SLUDI**: Simulated eSignet authentication for development
- **Token**: JWT with individualId, name, email, role (admin/responder)
- **Storage**: localStorage (`access_token`, `user`)
- **Features**:
  - Role-based dashboard access
  - SOS management and assignment
  - Real-time communication with citizens

### Real-Time Messaging System (Socket.io)

#### Architecture
- **Server**: Socket.io 4.8.1 integrated with Express.js backend
- **Client**: Socket.io-client with room-based communication
- **Persistence**: Messages stored in SOS `victim_status_updates` array
- **Real-Time Events**:
  - `join-sos-room` - Connect to specific SOS conversation
  - `new-message` - Receive real-time message notifications
  - `responder-update` - Status changes and assignments
  - `location-update` - Responder location tracking

#### Message Flow
1. **Citizen sends message**: 
   - POST `/api/sos/:id/messages` with JWT token
   - Backend validates authentication, saves to MongoDB
   - Socket.io emits `new-message` event to `sos_${sosId}` room
   - All connected parties receive instant notification

2. **Responder responds**:
   - Same endpoint, different JWT token
   - Message tagged with sender_role (citizen/responder/admin)
   - Real-time delivery to citizen's dashboard

3. **Message History**:
   - GET `/api/sos/:id/messages` retrieves full conversation
   - Sorted by timestamp
   - Sender identification and role display

#### API Endpoints

**Messaging:**
- `POST /api/sos/:id/messages` - Send message (requires authentication)
- `GET /api/sos/:id/messages` - Get conversation history
- `PUT /api/sos/:id/status` - Update SOS status

**Citizen SOS:**
- `POST /api/public/sos` - Submit SOS (optional auth via Bearer token)
- `GET /api/sos/citizen/my-sos` - Get citizen's SOS history (requires citizen token)
- `POST /api/citizen-auth/signup` - Create citizen account
- `POST /api/citizen-auth/login` - Citizen login

**Admin/Responder SOS:**
- `GET /api/admin/sos/dashboard` - Admin dashboard with stats and pagination
- `GET /api/sos/public/nearby` - Responder view of all active SOS

### Technical Implementation Details

#### Token Structure (Citizen):
```json
{
  "citizenId": "692d6bf9a91455d306199e87",
  "phone": "0771234567",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "citizen",
  "account_type": "verified",
  "iat": 1733054400,
  "exp": 1735646400
}
```

#### Message Schema:
```json
{
  "message": "Responder: Help is on the way, ETA 15 minutes",
  "update_type": "chat_message",
  "timestamp": "2025-12-01T18:30:00.000Z",
  "sender_id": "responder001",
  "sender_role": "responder",
  "sender_name": "John Smith"
}
```

#### Socket.io Rooms:
- Room naming: `sos_${sosId}` (e.g., `sos_674d5a2b1c9d440017e3e4b8`)
- Multiple users can join same room
- Real-time broadcast to all room participants

## 🛠️ Technology Stack

### Frontend
- **Framework**: React 18.3.1 + TypeScript
- **Build Tool**: Vite 7.1.0 (fast HMR and optimized builds)
- **Routing**: React Router DOM v7 (latest)
- **UI Framework**: Tailwind CSS 3.4.17 + PostCSS
- **Icons**: Lucide React (modern, tree-shakeable)
- **Maps**: Leaflet 1.9.4 + React-Leaflet 4.2.1
- **HTTP Client**: Axios 1.7.9
- **Notifications**: React Hot Toast (lightweight toast library)
- **Charts**: Recharts 2.15.0 (data visualization)
- **State Management**: React Context API + Hooks
- **Mobile App**: React Native 0.76.5 (separate development)

### Backend
- **Runtime**: Node.js 20.x
- **Framework**: Express.js 5.1.0
- **Database**: MongoDB 8.11.0 with Mongoose ODM
- **Authentication**: 
  - JWT tokens with bcrypt password hashing
  - Dual auth system: Admin/Responder (Individual ID + OTP) + Citizen (email/phone + password)
  - Shadow account system for emergency submissions without registration
  - 30-day token expiration
- **Real-Time Communication**: Socket.io 4.8.1 for bidirectional messaging
- **AI Integration**: Google Gemini AI API for safety chatbot
- **HTTP Client**: Axios for external API calls
- **Security**: Helmet, express-rate-limit, CORS, JWT verification
- **Middleware**: body-parser, dotenv, express-sanitizer, authenticateToken
- **Services**: 
  - SOS Auto-Escalation (5-min intervals)
  - Socket.io Service for real-time notifications
  - Message persistence in SOS victim_status_updates

### Production APIs & External Services
- **DMC Flood API**: Real-time water level monitoring (39 stations, 15-min updates)
- **Supabase Relief API**: Relief camp coordination and volunteer management
- **OpenStreetMap Nominatim**: Reverse geocoding (address from coordinates)
- **MongoDB Atlas**: User-generated data (SOS signals, reports, chat logs)
- **Google Gemini AI**: Emergency guidance chatbot

### Deployment & Infrastructure
- **Frontend Hosting**: Vercel (https://resq-five.vercel.app)
  - Automatic preview deployments for PRs
  - Edge CDN for fast global delivery
  - Zero-config SSL certificates
- **Backend Hosting**: Render (https://resq-backend-3efi.onrender.com)
  - Auto-deploy from GitHub
  - Health check monitoring
  - Environment variable management
- **Database**: MongoDB Atlas (Singapore region)
  - Geospatial indexing for location queries
  - Automatic backups
  - High availability cluster
- **Version Control**: GitHub (disaster-response-sl/resq)
  - Feature branch workflow
  - Protected main branch
- **CI/CD**: Automatic deployment on push to main/feature branches

## 📚 API Documentation

### DMC Flood Data API
- **Base URL**: `https://lk-flood-api.vercel.app`
- **Documentation**: [Swagger UI](https://lk-flood-api.vercel.app/docs) | [ReDoc](https://lk-flood-api.vercel.app/redoc)
- **Full Docs**: [docs/sriLankaFloodDataAPI.md](./docs/sriLankaFloodDataAPI.md)

**Key Endpoints**:
- `GET /alerts` - Active flood alerts (MAJOR, MINOR, ALERT)
- `GET /levels/latest` - Latest water levels for all 39 stations
- `GET /stations` - Station metadata with GPS coordinates
- `GET /rivers` - River information with basin data

**Example Response** (`/alerts`):
```json
{
  "station_name": "Hanwella",
  "river_name": "Kelani Ganga",
  "water_level": 10.75,
  "alert_status": "MAJOR",
  "rising_or_falling": "Falling",
  "timestamp": "2025-11-30 12:30:00"
}
```

### Supabase Relief Coordination API
- **Base URL**: `https://cynwvkagfmhlpsvkparv.supabase.co/functions/v1/public-data-api`
- **Documentation**: [docs/publicDataAPI.md](./docs/publicDataAPI.md)

**Query Parameters**:
- `type` - `requests` (help needed) or `contributions` (help offered)
- `status` - `pending`, `resolved`, `available`
- `urgency` - `emergency`, `high`, `medium`, `low`
- `lat`, `lng`, `radius_km` - Location-based filtering
- `search` - Text search across all fields

**Example**: Find emergency help requests within 30km:
```
GET /public-data-api?type=requests&urgency=emergency&lat=6.9271&lng=79.8612&radius_km=30&sort=distance
```
## 🚀 Quick Start

### Prerequisites
- Node.js (v18 or higher recommended: v20.x)
- MongoDB Atlas account (free tier available)
- Git
- Code editor (VS Code recommended)
- Google Gemini API key (for AI chatbot)

### Local Development Setup

#### 1. Clone the repository
```bash
git clone https://github.com/disaster-response-sl/resq.git
cd resq
```

#### 2. Backend Setup

```bash
cd src/web-dashboard/backend
npm install
```

Create a `.env` file in `src/web-dashboard/backend/`:
```env
# Server Configuration
PORT=5000
NODE_ENV=development

# Database
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/disaster_platform

# Authentication
JWT_SECRET=your-secure-random-64-character-string
JWT_EXPIRES_IN=24h
USE_MOCK_SLUDI=true

# AI Integration
GEMINI_API_KEY=your-google-gemini-api-key

# External Services (optional - uses public APIs if not set)
OPENWEATHER_API_KEY=your-openweather-api-key
```

**Generate JWT_SECRET:**
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Start the backend server:
```bash
npm run dev
```
✅ Server runs on `http://localhost:5000`

#### 3. Frontend Setup

```bash
cd src/web-dashboard/frontend
npm install
```

Create a `.env` file in `src/web-dashboard/frontend/`:
```env
VITE_API_BASE_URL=http://localhost:5000
```

Start the development server:
```bash
npm run dev
```
✅ Frontend runs on `http://localhost:5173`

### 🧪 Test the Application

**Citizen Portal (No Login):**
- Navigate to `http://localhost:5173`
- Access all public features (SOS, reports, relief tracker, etc.)

**Admin/Responder Login:**
- Click "Admin Login" or "Responder Login"
- Use your assigned credentials to access the system

### Mobile App Setup

1. **Install mobile app dependencies**
   ```bash
   cd src/MobileApp
   npm install
   ```

2. **Install React Native dependencies**
   ```bash
   npx react-native install
   ```

3. **Start Metro bundler**
   ```bash
   npx react-native start
   ```

4. **Run on Android/iOS**
   ```bash
   # Android
   npx react-native run-android
   
   # iOS
   npx react-native run-ios
   ```

### Web Dashboard Setup

1. **Install web dashboard dependencies**
   ```bash
   cd src/web-dashboard/frontend
   npm install
   ```

2. **Start the development server**
   ```bash
   npm start
   ```

## 🧪 Testing

### Access Levels

**Admin Access:**
- Role: Administrator (full access)
- Requires authorized credentials

**Responder Access:**
- Role: Responder (field operations)
- Requires authorized credentials

**Citizen Access:**
- No login required for public portal
- Full access to SOS, reporting, relief tracker, and AI assistant

### API Endpoints

#### Authentication
- `POST /api/mobile/login` - User authentication
- `POST /api/mobile/register` - User registration

#### Disasters
- `GET /api/mobile/disasters` - Get active disasters
- `POST /api/mobile/disasters` - Create new disaster

#### SOS Signals
- `GET /api/mobile/sos-signals` - Get recent SOS signals
- `POST /api/mobile/sos` - Send SOS signal

#### Reports
- `GET /api/mobile/reports` - Get recent reports
- `POST /api/mobile/reports` - Submit new report

#### Resources
- `GET /api/mobile/resources` - Get available resources
- `POST /api/mobile/resources` - Add new resource

#### Chat
- `GET /api/mobile/chat-logs` - Get chat history
- `POST /api/mobile/chat` - Send chat message

## 👥 Team

### Development Team
- **Shalon Fernando** - Lead Software Engineer & Full Stack Architect
  
- **Gaindu** - Web Dashboard Development
  
- **Lehan** - Web Dashboard Development
  
- **Pavith** - Web Dashboard Development

### Recent Contributions
- **Shalon**: Production deployment, UI/UX redesign, LankaRouteWatch implementation, location services, debouncing, CORS fixes, environment setup guides, real time api integration.

## 🔧 Configuration

### Environment Variables

#### Mobile App (config/api.ts)
```typescript
export const API_BASE_URL = 'http://10.0.2.2:5000'; // Android Emulator
// export const API_BASE_URL = 'http://localhost:5000'; // iOS Simulator
```

### API Configuration
- **Base URL**: `http://localhost:5000` (development)
- **Authentication**: Bearer token in Authorization header
- **Content-Type**: `application/json`

## 🚨 Emergency Features

### SOS Signal
- One-tap emergency button
- Automatic GPS location capture
- Priority level selection (High/Medium/Low)
- Message field for additional details

### Real-time Alerts
- Push notifications for new disasters
- Location-based risk assessment
- Weather integration
- Offline capability

### AI Safety Assistant
- Natural language processing
- Contextual safety recommendations
- Pre-defined quick questions
- Emergency contact information

## 📱 Mobile App Features

### Authentication
- SLUDI mock authentication
- Role-based access (Citizen/Responder)
- Secure token storage

### Dashboard
- Current location weather
- Risk assessment based on nearby disasters
- Quick action buttons (SOS, Report, Chat)
- Recent alerts feed
- Available resources display

### Reporting
- Incident type selection
- Photo upload capability
- Location confirmation
- Status tracking

## 💻 Web Dashboard Features

### Admin Panel
- Role-based access control
- Real-time statistics
- Geographic data visualization
- Resource management

### Disaster Management
- Create and update disasters
- Set severity levels
- Publish public alerts
- Status tracking

### SOS Monitoring
- Live emergency signal feed
- Priority-based sorting
- Geographic clustering
- Response assignment

## 🔒 Security Features

- JWT token authentication
- Role-based access control
- Input validation and sanitization
- Secure API endpoints
- Environment variable protection

## 📊 Performance Optimizations

- Offline-first mobile design
- Real-time WebSocket connections
- Geospatial database indexing
- Image compression and caching
- Lazy loading for large datasets

## 🚀 Production Deployment

### Current Production Status ✅

**Frontend:** https://resq-five.vercel.app
- Hosted on Vercel
- Automatic deployments from GitHub
- Global CDN distribution
- SSL/HTTPS enabled

**Backend:** https://resq-backend-3efi.onrender.com
- Hosted on Render
- Connected to MongoDB Atlas (Singapore)
- Auto-deploy from GitHub
- Health monitoring enabled

### Quick Deploy Commands

**Deploy Frontend (Vercel):**
```bash
# Install Vercel CLI
npm i -g vercel

# Deploy
cd src/web-dashboard/frontend
vercel --prod
```

**Deploy Backend (Render):**
- Push to GitHub `main` or `feature-deployment-ready` branch
- Render auto-deploys in 2-3 minutes
- Or use "Manual Deploy" in Render Dashboard

### Environment Variables for Production

**Critical variables that MUST be set on Render:**

```env
JWT_SECRET=<64-char-random-string>  # Required for login
USE_MOCK_SLUDI=true                  # Enable authentication
MONGO_URI=<mongodb-atlas-url>        # Database connection
NODE_ENV=production
JWT_EXPIRES_IN=24h
```

**See [RENDER_ENV_SETUP.md](./RENDER_ENV_SETUP.md) for complete setup guide.**

---

## 🐛 Troubleshooting

### Production Issues

**1. Login Fails with 500 Error**
- ❌ Missing `JWT_SECRET` on Render
- ✅ Add environment variable: See [RENDER_ENV_SETUP.md](./RENDER_ENV_SETUP.md)
- ✅ Verify with: `curl https://resq-backend-3efi.onrender.com/api/test`

**2. Relief Camps Show Empty or Error**
- ⚠️ External Supabase API may be slow/unavailable
- ✅ Backend now returns empty array gracefully (not critical)
- ✅ Shows: "Relief camps service temporarily unavailable"

**3. CORS Errors in Production**
- ✅ Fixed: Backend allows all `*.vercel.app` domains
- ✅ Redeploy backend if still seeing errors

### Local Development Issues

**1. MongoDB Connection Error**
- Verify `MONGO_URI` in `.env` file
- Check network connectivity
- Ensure IP whitelist in MongoDB Atlas (add 0.0.0.0/0 for development)
- Test connection: `mongosh <your-mongo-uri>`

**2. Backend Port Already in Use**
```bash
# Windows: Find and kill process on port 5000
netstat -ano | findstr :5000
taskkill /PID <process-id> /F

# Or change PORT in .env file
```

**3. Frontend Can't Connect to Backend**
- Verify backend is running: `curl http://localhost:5000/api/health`
- Check `VITE_API_BASE_URL` in frontend `.env`
- Clear browser cache and reload

**4. GPS Location Issues**
- Enable location permissions in browser
- Use HTTPS (required for geolocation API)
- Check device GPS settings
- Verify location services are enabled

**5. Leaflet Map Not Displaying**
- Check browser console for errors
- Verify map container has explicit height (600px)
- Import Leaflet CSS: `import 'leaflet/dist/leaflet.css'`

### Debug Commands

```bash
# Check backend logs
cd src/web-dashboard/backend
npm run dev

# Test backend health
curl http://localhost:5000/api/health

# Test MongoDB connection
curl http://localhost:5000/api/public/stats

# Check frontend build
cd src/web-dashboard/frontend
npm run build

# Mobile app logs
cd src/MobileApp
npx react-native log-android
npx react-native log-ios
```

### Verification Checklist

After deployment, verify these features:

- [ ] Backend health check responds: `/api/health`
- [ ] Admin login works with authorized credentials
- [ ] Statistics display correctly (reports, disasters, SOS)
- [ ] Location shows accurate address
- [ ] Road reports display on LankaRouteWatch
- [ ] SOS signals load on dashboard
- [ ] Disaster heat map shows DMC flood data
- [ ] Relief tracker search works (debounced)
- [ ] AI chatbot responds to queries
- [ ] Emergency contacts display DDMCU hotlines

## 📚 Documentation

### Deployment Guides
- **[QUICK_DEPLOY.md](./QUICK_DEPLOY.md)** - Quick reference for deploying to Vercel and Render
- **[DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)** - Comprehensive deployment guide with troubleshooting
- **[RENDER_ENV_SETUP.md](./RENDER_ENV_SETUP.md)** - Environment variable setup for Render backend
- **[PRODUCTION_FIX_SUMMARY.md](./PRODUCTION_FIX_SUMMARY.md)** - Production error fixes and solutions

### API Documentation
- **[DMC Flood Data API](./docs/sriLankaFloodDataAPI.md)** - Real-time flood monitoring (39 stations)
- **[Supabase Relief API](./docs/publicDataAPI.md)** - Relief camp coordination and volunteer management
- **[Backend API Endpoints](./docs/api.md)** - Internal API documentation (if available)

### Architecture & Schema
- **[Database Schema](./docs/schema.md)** - MongoDB collections and data models (if available)
- **[Project Structure](./docs/)** - Full documentation folder

## 📄 License

This project is developed for Codefest's Revive Nation hackathon and is intended for educational and demonstration purposes.

## 🔧 Technical Improvements & Optimizations

### Performance Enhancements
- ✅ **Debounced Search** - Relief Tracker radius slider with 800ms delay prevents notification spam
- ✅ **Lazy Loading** - Efficient component loading reduces initial bundle size
- ✅ **Geospatial Indexing** - MongoDB 2dsphere index for fast location queries
- ✅ **CDN Distribution** - Vercel Edge Network for global low-latency access
- ✅ **API Response Caching** - Reduced redundant external API calls

### Error Handling & Resilience
- ✅ **JWT Validation** - Backend checks for JWT_SECRET before authentication
- ✅ **Supabase Fallback** - Graceful degradation when external API unavailable
- ✅ **CORS Configuration** - Supports all Vercel preview deployments (*.vercel.app)
- ✅ **Comprehensive Logging** - Console logging for debugging production issues
- ✅ **Rate Limiting** - 10,000 requests per 15 min (5 for auth endpoints)
- ✅ **Input Sanitization** - NoSQL injection prevention

### Location Services
- ✅ **Reverse Geocoding** - Accurate address from coordinates
  - Direct Nominatim API (10s timeout)
  - Backend proxy fallback (12s timeout)
  - Shows: "St Mary's Road, Kochchikade, Gampaha District"
- ✅ **Location Autocomplete** - Search locations by name (Nominatim)
- ✅ **Distance Calculations** - Haversine formula for accurate distances
- ✅ **CORS Proxy** - `/api/geocode/reverse` endpoint avoids browser CORS issues

### Mobile Responsiveness
- ✅ **Adaptive Layouts** - Tailwind breakpoints (sm, md, lg, xl)
- ✅ **Touch-Friendly UI** - Larger buttons and spacing on mobile
- ✅ **Responsive Grid** - 2 columns on mobile, 4-5 on desktop
- ✅ **Navbar Visibility** - Logo and subtitle visible on all screen sizes
- ✅ **Mobile-First Design** - Progressive enhancement approach

### Security Features
- ✅ **Helmet.js** - Secure HTTP headers
- ✅ **JWT Authentication** - Stateless token-based auth
- ✅ **Environment Variables** - Secure secret management
- ✅ **HTTPS Enforcement** - SSL certificates on production
- ✅ **Rate Limiting** - Brute force protection
- ✅ **Input Validation** - Prevents injection attacks

### Monitoring & Observability
- ✅ **Health Check Endpoint** - `/api/health` for uptime monitoring
- ✅ **Test Endpoint** - `/api/test` shows environment status
- ✅ **Console Logging** - Structured logs with emojis (✅, ❌, ⚠️)
- ✅ **Error Tracking** - Comprehensive error messages
- ✅ **API Response Logging** - Track external API calls

---

## 🎯 Known Limitations & Future Enhancements

### Current Limitations
- ⚠️ **Mock Authentication** - Uses Individual ID + OTP instead of real SLUDI
- ⚠️ **Supabase Dependency** - Relief camps may be unavailable if external API down
- ⚠️ **Single Language** - Currently English only (Sinhala/Tamil planned)
- ⚠️ **No Real-Time Sync** - Dashboard updates on refresh (WebSocket planned)

### Planned Features
- 🔮 **Real SLUDI Integration** - Connect to actual eSignet authentication
- 🔮 **Multi-Language Support** - Sinhala, Tamil, English
- 🔮 **Push Notifications** - Real-time alerts to mobile devices
- 🔮 **Offline Mode** - Service worker for offline access
- 🔮 **WebSocket Integration** - Live dashboard updates
- 🔮 **Advanced Analytics** - Predictive disaster modeling
- 🔮 **SMS Gateway** - Send alerts via SMS for areas without internet
- 🔮 **Drone Integration** - Aerial surveillance and delivery coordination

---

## 🙏 Acknowledgments

### Data Sources & APIs
- **Sri Lanka DMC** - Real-time flood monitoring data (39 gauging stations)
- **Supabase** - Relief camp coordination and volunteer management
- **OpenStreetMap Nominatim** - Geocoding and location search
- **Google Gemini AI** - Emergency guidance chatbot
- **OpenWeatherMap** - Weather data integration

### Technology Partners
- **Vercel** - Frontend hosting and CDN
- **Render** - Backend hosting and deployment
- **MongoDB Atlas** - Cloud database hosting
- **GitHub** - Version control and CI/CD

### Open Source Community
- React and React Native communities
- Leaflet mapping library
- Tailwind CSS framework
- Lucide icons
- All npm package maintainers

### Special Thanks
- Sri Lanka Digital Public Infrastructure (DPI) team
- Disaster Management Centre (DMC) Sri Lanka
- ICTA Sri Lanka
- Codefest Hackathon organizers
- All contributors and testers

---

**Built with ❤️ for Sri Lanka's disaster response needs**

*This platform demonstrates the potential of AI and modern technology in addressing critical national challenges. We aim to save lives, coordinate relief efforts, and empower citizens during disasters.*

**🌟 Star this repo if you find it useful!**

---

## 📞 Contact & Support

- **GitHub Issues**: [Report bugs or request features](https://github.com/disaster-response-sl/resq/issues)
- **Production Site**: [https://resq-five.vercel.app](https://resq-five.vercel.app)
- **Documentation**: [Full docs folder](./docs/)

**Emergency Hotline (Sri Lanka):** 117 (DMC Disaster Management Centre)

resq

resq Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

resq

resq Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README