🚨 Relief Ops

A microservices-based disaster management and relief coordination platform
Real-time disaster reporting • Resource tracking • Role-based access

Explore Features »

Report Bug · Request Feature

---

📋 Table of Contents

• About
• Features
• Architecture
• Tech Stack
• Getting Started
• API Endpoints
• Deployment
• Contributing

---

🌟 About

Relief Ops is a cloud-native disaster management platform built with Go microservices. It enables communities and organizations to coordinate disaster response through real-time reporting, resource discovery, and admin oversight.

Key Capabilities

• Three User Roles: Admin, Contributor, and Public users with distinct permissions
• Disaster Workflow: Report → Admin Review → Public Visibility
• Resource Discovery: Find nearby hospitals, shelters, fire stations, pharmacies, and police stations
• Event-Driven: Kafka-based async notifications to admins
• Geospatial Queries: MongoDB 2dsphere indexes for location-based searches
• Production-Ready: JWT auth, retry logic, horizontal scaling, Kubernetes deployment

---

✨ Features

👥 User Roles & Permissions

Public Users

• View approved disaster reports
• Search disasters by location
• View nearby emergency resources on map

Contributors

• All public user capabilities
• Report disasters with location and details
• Upload disaster information
• Wait for admin approval before public visibility

Admins

• All contributor capabilities
• Review and approve/reject disaster reports
• Receive email notifications for new disaster reports
• Manage disaster lifecycle

🚨 Disaster Management

• Geolocation-based disaster reporting
• Admin approval workflow
• Status tracking (pending, approved, rejected)
• Email notifications to admins via SendGrid
• Event-driven architecture with Kafka

🏥 Resource Discovery

• Find nearby emergency resources:
  • Hospitals
  • Police stations
  • Fire stations
  • Shelters
  • Pharmacies
• Geospatial radius search (e.g., "resources within 5km")
• Automatic data sync from OpenStreetMap via Overpass API
• Smart duplicate prevention by name + amenity type

🔐 Authentication & Security

• JWT-based stateless authentication
• Role-based access control (RBAC)
• Password hashing with bcrypt
• Secure cookie-based sessions
• Redis-backed token blacklist for logout

---

Event Flow

Contributor Reports Disaster
         ↓
Disaster Service (gRPC)
         ↓
MongoDB (Store)
         ↓
Kafka Producer (Publish Event)
         ↓
User Service Consumer (Receive Event)
         ↓
SendGrid API (Send Email to Admins)

---

🛠️ Tech Stack

Backend

• Go 1.25.1 - Primary language
• gRPC - Inter-service communication
• Gin - HTTP framework
• Protocol Buffers - Service definitions

Databases

• MongoDB 6.0 - Document database with geospatial support
• Redis 7.0 - Session management and caching

Message Queue

• Apache Kafka 4.0.0 - Event streaming (KRaft mode, 3 brokers)

Infrastructure

• Kubernetes - Container orchestration
• Docker - Containerization
• Minikube - Local development

External APIs

• SendGrid - Email notifications
• Overpass API - OpenStreetMap resource data

---

🚀 Getting Started

Prerequisites

# Required tools
go version          # Go 1.25.1+
docker --version    # Docker
kubectl version     # Kubernetes CLI
minikube version    # Minikube
protoc --version    # Protocol Buffers compiler

Quick Start

1. Clone and setup

   git clone https://github.com/Cprakhar/relief-ops.git
   cd relief-ops
   go mod download
   make generate-proto

2. Start local Kubernetes

   minikube start --memory=8192 --cpus=4
   kubectl create namespace relief-ops

3. Create secrets

   # JWT Secret
   kubectl create secret generic jwt-secret \
     --from-literal=jwt-secret=$(openssl rand -base64 48) \
     -n relief-ops
   
   # MongoDB
   kubectl create secret generic mongo-secret \
     --from-literal=mongo-uri="mongodb://mongo-db:27017" \
     -n relief-ops
   
   # Redis
   kubectl create secret generic redis-secret \
     --from-literal=redis-password=$(openssl rand -base64 32) \
     -n relief-ops
   
   # SendGrid (replace with your API key)
   kubectl create secret generic sendgrid-secret \
     --from-literal=api-key="YOUR_SENDGRID_API_KEY" \
     -n relief-ops
   
   # Kafka brokers
   kubectl create secret generic kafka-config \
     --from-literal=kafka-brokers="apache-kafka-0.apache-kafka.relief-ops.svc.cluster.local:9092,apache-kafka-1.apache-kafka.relief-ops.svc.cluster.local:9092,apache-kafka-2.apache-kafka.relief-ops.svc.cluster.local:9092" \
     -n relief-ops

4. Deploy infrastructure

   kubectl apply -f k8s/base/mongo-db.yaml
   kubectl apply -f k8s/base/redis-db.yaml
   kubectl apply -f k8s/base/apache-kafka.yaml
   
   # Wait for readiness
   kubectl wait --for=condition=ready pod -l app=mongo-db -n relief-ops --timeout=300s
   kubectl wait --for=condition=ready pod -l app=redis-db -n relief-ops --timeout=300s
   kubectl wait --for=condition=ready pod -l app=apache-kafka -n relief-ops --timeout=300s

5. Build and deploy services

   make build-all
   kubectl apply -f k8s/base/user-service.yaml
   kubectl apply -f k8s/base/disaster-service.yaml
   kubectl apply -f k8s/base/resource-service.yaml
   kubectl apply -f k8s/base/api-gateway.yaml

6. Verify deployment

   kubectl get pods -n relief-ops
   kubectl get svc -n relief-ops

---

💻 API Endpoints

Authentication

Register User

POST /auth/register
{
  "email": "user@example.com",
  "password": "SecurePass123",
  "name": "John Doe"
}

Login

POST /auth/login
{
  "email": "user@example.com",
  "password": "SecurePass123"
}
# Returns JWT token in cookie

Logout

POST /auth/logout
# Requires authenticated session

Disasters

Report Disaster (Contributors only)

POST /disasters
{
  "title": "Earthquake in San Francisco",
  "description": "6.5 magnitude earthquake",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "severity": 8,
  "tags": ["earthquake", "urgent"]
}

Get All Disasters (Public)

GET /disasters

Get Disaster by ID (Public)

GET /disasters/{id}

Review Disaster (Admins only)

POST /admin/review/{id}
{
  "approved": true
}

Resources

Get Nearby Resources (Public)

GET /resources/nearby?lat=37.7749&lon=-122.4194&radius=5000&type=hospital

Sync Resources from OpenStreetMap

POST /resources/sync?lat=37.7749&lon=-122.4194&radius=10000

---

☁️ Deployment

Microservices

Service	Port	Purpose
API Gateway	8080	HTTP REST entry point
User Service	9001	Authentication & notifications
Disaster Service	9002	Disaster reporting & management
Resource Service	9003	Resource discovery & sync

Environment Variables

Variable	Description	Required
JWT_SECRET	Secret for JWT signing	Yes
MONGO_URI	MongoDB connection string	Yes
KAFKA_BROKERS	Kafka broker addresses	Yes
SENDGRID_API_KEY	SendGrid API key	Yes
REDIS_PASSWORD	Redis password	Yes

Production Considerations

• Enable horizontal pod autoscaling
• Configure resource limits (CPU, memory)
• Set up persistent volumes for databases
• Use ingress for external access
• Enable TLS/SSL certificates
• Configure health checks and probes

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

⬆ Back to Top