ReliefOps AI

AI-assisted intake and deterministic dispatch planning for disaster relief operations.
Turn messy field reports, CSVs, PDFs, and images into reviewable incident, team, and resource records, then allocate scarce response assets across all open cases with a global planning workflow.

View Repository | Report Bug | Request Feature

Table of Contents

1. About The Project
   • Why It Is Different
   • Built With
2. Architecture Overview
3. Core Workflows
   • Graph 1: Intake And Review
   • Graph 2: Dispatch Planning
4. Project Structure
5. Getting Started
   • Prerequisites
   • Installation
   • Configuration
   • Running Locally
6. Usage
7. Testing
8. Deployment
9. Roadmap
10. Contributing
11. Contact

About The Project

ReliefOps AI is an operations console for NGOs, emergency coordinators, and relief teams that need to move from chaotic incoming information to trustworthy dispatch decisions.

The project solves two connected problems:

• Intake is messy. Real-world reports arrive as CSVs, PDFs, screenshots, field notes, copied messages, and partial spreadsheets.
• Dispatch is constrained. Teams, volunteers, vehicles, medical kits, fuel, and other supplies are limited and cannot be assigned independently to every case.

ReliefOps AI combines AI-assisted understanding with deterministic backend validation:

• AI helps extract incidents, teams, and resources from unstructured or mixed sources.
• Operators review, edit, reevaluate, remove, and confirm before anything becomes an operational record.
• Dispatch planning uses backend-owned logic for availability, stock arithmetic, routing, and assignment confirmation.

This keeps the system useful in real operations without asking users to blindly trust model output.

(back to top)

Why It Is Different

Most incident tools stop at "capture the report." ReliefOps AI goes further:

• Preview-first ingestion instead of upload-and-pray.
• Human confirmation before persistence.
• Batch dispatch planning across all open cases, not just one case at a time.
• Separate browser-side maps rendering from backend routing and geocoding.
• AI used for extraction and reevaluation, not for hidden feasibility math or automatic dispatch.

In one line:

From chaotic reports to coordinated response.

Built With

• Next.js 16
• React 19
• TypeScript
• Tailwind CSS 4
• shadcn/ui
• FastAPI
• Pydantic 2
• Firebase Authentication
• Cloud Firestore
• Google Maps JavaScript API
• Google Geocoding API
• Google Routes API
• Gemini API
• LangGraph
• Ollama with local Gemma 4 fallback for development

(back to top)

Architecture Overview

ReliefOps AI is split into a web console and an API service.

flowchart LR
  UI["Next.js operator console"] --> API["Central API helper"]
  API --> Auth["Firebase token + X-Org-Id"]
  Auth --> FastAPI["FastAPI routes"]
  FastAPI --> Graphs["Graph 1 / Graph 2 services"]
  Graphs --> AI["Gemini or local Ollama fallback"]
  Graphs --> Maps["Geocoding + Routes APIs"]
  Graphs --> Repo["Firestore or memory repository"]

Loading

Design rule:

• Frontend handles review, interaction, loading states, and operator workflow.
• Backend validates, plans, persists, and protects operational truth.
• AI suggests structured understanding and reevaluation patches.
• Humans confirm before operational records are committed.

Frontend API Design

Frontend traffic is intentionally centralized through web/src/lib/api.ts instead of scattered raw fetch calls.

Advantages:

• One contract for auth and organization scoping.
• Consistent request headers.
• Easier cache invalidation after mutations.
• Cleaner pages and components.
• Centralized session-expiry handling.

Tradeoffs:

• Frontend and backend types must stay in sync.
• A bug in the shared API helper can affect multiple screens.
• Long-running AI flows still need careful UX around waiting and retries.

Backend Design

The backend is organized around:

• FastAPI routes
• dependency-based auth and organization guards
• service-layer graph orchestration
• repository abstraction
• Pydantic domain models
• Firebase and Google Cloud integrations

The most important invariant is this:

AI may help explain and extract. The backend still owns feasibility, stock math, routing truth, and confirmation.

(back to top)

Core Workflows

Graph 1: Intake And Review

Graph 1 is the preview-first ingestion workflow.

flowchart TD
  Source["CSV / PDF / image / text"] --> Parse["Parse source into text or rows"]
  Parse --> Extract["Gemini row-batch or document extraction"]
  Extract --> Drafts["Editable incident / team / resource drafts"]
  Drafts --> Enrich["Geocode, duplicate checks, provenance"]
  Enrich --> Review["GraphRun review workspace"]
  Review --> Reevaluate["Prompt or field-based reevaluation"]
  Reevaluate --> Confirm["Operator confirmation"]
  Confirm --> Persist["Cases, teams, resources, jobs, tokens, vectors"]

Loading

Graph 1 supports:

• unknown CSV rows
• mixed incident/team/resource documents
• PDF, image, and text imports
• full draft reevaluation
• source provenance
• duplicate warnings
• editable location review before commit

Graph 2: Dispatch Planning

Graph 2 is the dispatch planner. It supports both focused single-case planning and batch planning across all open cases.

flowchart TD
  OpenCases["Load open cases"] --> Rank["Rank by planning priority"]
  Rank --> Assets["Fetch teams, volunteers, resources"]
  Assets --> Candidates["Build feasible candidates"]
  Candidates --> ETA["Routes API ETA enrichment"]
  ETA --> Allocate["Deterministic allocator"]
  Allocate --> Reserve["Apply reserve policy"]
  Reserve --> Preview["Batch planning board"]
  Preview --> Confirm["Confirm one case or full batch"]

Loading

Graph 2 is intentionally deterministic where it matters:

• AI may improve wording, explanations, or reevaluation suggestions.
• AI may not invent ETA, consume stock, override availability, or bypass constraints.

This avoids the common trap of "smart-looking" dispatch output that cannot be trusted operationally.

(back to top)

Project Structure

GDG/
├── api/
│   ├── app/
│   │   ├── api/routes/
│   │   ├── core/
│   │   ├── models/
│   │   ├── repositories/
│   │   └── services/
│   └── tests/
├── web/
│   ├── src/app/
│   ├── src/components/
│   ├── src/lib/
│   └── tests/
├── docs/
├── test_inputs/
├── .env.example
├── apphosting.yaml
└── README.md

Key areas:

• web/src/app: routed pages for imports, dispatch, cases, teams, resources, volunteers, and organization management.
• web/src/components: operator UI, maps, review workspace, and planning screens.
• web/src/lib: typed frontend API helper, formatters, and shared utilities.
• api/app/services: graph orchestration, extraction, matching, routing, geocoding, and duplicate logic.
• api/app/repositories: Firestore and in-memory persistence backends.
• docs: deployment and architecture notes.

(back to top)

Getting Started

Prerequisites

You will need:

• Node.js 20+
• npm
• Python 3.13+
• uv

For full cloud-backed functionality, you will also want:

• a Firebase project
• Firestore enabled
• Firebase Authentication enabled
• a Gemini API key
• a backend Google Maps key with Geocoding + Routes
• a frontend Google Maps JavaScript key

Installation

1. Clone the repository.

   git clone https://github.com/aditya9515/GDG.git
   cd GDG

2. Install the root helper package.

   npm install

3. Install frontend dependencies.

   npm --prefix web install

4. Install backend dependencies.

   uv sync --project api

Configuration

Use the provided examples as the source of truth:

• root example: .env.example
• backend example: api/.env.example

Typical setup:

• create api/.env
• create web/.env.local

Important variables:

Frontend

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000
NEXT_PUBLIC_ENABLE_DEMO_AUTH=false
NEXT_PUBLIC_FIREBASE_API_KEY=your-firebase-web-api-key
NEXT_PUBLIC_FIREBASE_APP_ID=your-firebase-app-id
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-browser-maps-key

Backend

APP_ENV=development
CORS_ORIGINS=["http://localhost:3000","http://127.0.0.1:3000"]
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
REPOSITORY_BACKEND=firestore
ALLOW_DEMO_AUTH=false
GOOGLE_MAPS_API_KEY=your-server-side-maps-key
GEMINI_API_KEY=your-gemini-key
AI_PROVIDER=gemini
GEMINI_ENABLED=true
GEMMA4_ENABLED=false

Optional local model mode:

AI_PROVIDER=ollama
GEMMA4_ENABLED=true
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=gemma4:e2b

Running Locally

Start the backend:

npm run dev:api

Start the frontend:

npm run dev:web

The app will be available at:

• frontend: http://localhost:3000
• backend: http://localhost:8000

Useful backend endpoints:

• /health
• /me
• /ai/status

(back to top)

Usage

Typical operator flow:

1. Sign in and select an organization.
2. Open Imports and upload a CSV, PDF, image, or paste text.
3. Review Graph 1 drafts, edit or reevaluate them, then confirm.
4. Check the Command Center for operational state, mapped assets, and processing history.
5. Open Dispatch and run Plan all open cases for batch Graph 2 planning.
6. Review assigned, partial, waiting, blocked, and unassigned cases.
7. Confirm one case or the full batch.

Useful screens:

• Imports: preview-first intake and commit
• Command Center: operational overview
• Cases: case registry and focused dispatch
• Dispatch: batch planning board and committed assignments
• Teams / Volunteers / Resources: operational asset management
• Organization: membership and destructive reset controls

(back to top)

Testing

Frontend:

npm --prefix web run test
npm --prefix web run build

Backend:

npm run test:api

Full local suite:

npm run test

Optional end-to-end smoke tests:

npm --prefix web run test:e2e

(back to top)

Deployment

This repository is set up around a split deployment model:

• Frontend: Firebase App Hosting
• Backend: FastAPI service on Cloud Run

Frontend

The included apphosting.yaml defines the public runtime variables expected by the Next.js app.

Required public values:

• NEXT_PUBLIC_API_BASE_URL
• NEXT_PUBLIC_ENABLE_DEMO_AUTH
• Firebase web config values
• NEXT_PUBLIC_GOOGLE_MAPS_API_KEY

Backend

Keep backend secrets private in your backend runtime or secret manager:

• GEMINI_API_KEY
• backend GOOGLE_MAPS_API_KEY
• Firebase project credentials or Application Default Credentials

Production defaults:

AI_PROVIDER=gemini
GEMINI_ENABLED=true
GEMMA4_ENABLED=false
REPOSITORY_BACKEND=firestore
ALLOW_DEMO_AUTH=false

Important deployment rule:

• frontend gets browser-safe NEXT_PUBLIC_* values only
• backend gets private model and maps secrets

For deployment details, see the docs in docs/, especially the Firebase App Hosting and Gemini deployment notes already included in this repo.

(back to top)

Roadmap

• Preview-first Graph 1 review workspace
• Full-context reevaluation for drafts and dispatch plans
• Batch Graph 2 planning as the primary dispatch workflow
• Gemini-first production configuration
• Monochrome SaaS-style frontend redesign
• richer analytics and operational reporting
• broader background processing for large imports
• deeper geospatial overlays and tracking
• more multilingual and low-connectivity workflows

See the open issues for future improvements and bug tracking.

(back to top)

Contributing

Contributions are welcome, especially around:

• emergency workflow design
• data intake quality
• planning trust and explainability
• deployment hardening
• testing and evaluation datasets

If you want to contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the relevant tests
5. Open a pull request

When changing operational logic, please prefer explainable and reviewable behavior over opaque automation.

(back to top)

Contact

Maintainer: Kosuru Venkata Sai Aditya

• Project repository: https://github.com/aditya9515/GDG
• Issues: https://github.com/aditya9515/GDG/issues

(back to top)