Home Original page

GitHub - harsharajkumar/BridgeAI: Realtime mutual-aid dispatch platform with emergency prioritization, OTP handoff verification, and charity fallback for unused offers. A slightly simpler one: Realtime help-dispatch platform connecting requesters, helpers, and ops with OTP verification and charity fallback.

BridgeAI is a realtime mutual-aid dispatch platform built for urgent community response.

It connects:

  • people asking for help
  • nearby helpers and volunteers
  • an operations view that can watch the network live

The project combines intake, prioritization, matching, tracking, OTP handoff verification, and charity fallback for unused offers in one system.

Why BridgeAI

In real community response, three things often break at the same time:

  • requests arrive through different channels and lose context
  • urgent cases do not always rise fast enough
  • good offers and donations can expire without ever creating impact

BridgeAI is designed to make those flows feel clearer and more accountable, closer to a live delivery network than a static form submission.

What Is Built

Request side

  • guided request submission from mobile and web
  • category-based intake with plain-language descriptions
  • live progress and history
  • OTP-based handoff verification for completion

Helper side

  • live queue of open requests
  • accept / skip flow
  • active assignment state
  • arrived -> verify OTP -> complete flow
  • browser-based helper console for local testing

Ops side

  • live stats
  • request feed
  • map and status visibility
  • demo scenario runner

Intelligence and routing

  • emergency keyword classifier that boosts urgent requests
  • realtime updates through Socket.IO
  • request and helper history tied to accounts

Donation / charity flow

  • offer expiry windows
  • auto-route to a named charity if unclaimed
  • closing donor messages

App Flow

First-time flow

  1. Open the app
  2. See the onboarding slides
  3. Choose a lane:
    • I need help
    • I can help
    • Ops
  4. Create an account or sign in
  5. Enter the lane-specific experience

Requester flow

  1. Choose a need category
  2. Describe the request in plain language
  3. Submit the request
  4. Watch the request move through matching
  5. See when help is assigned
  6. Track arrival in the app
  7. Share the OTP with the helper at handoff
  8. See the request marked completed
  9. Review the request later in account history

Helper flow

  1. Sign in to the helper lane or helper console
  2. Review the open queue
  3. Accept or skip a request
  4. Move into the active assignment view
  5. Mark arrival when reaching the requester
  6. Ask the requester for the OTP
  7. Enter the OTP to verify the handoff
  8. Complete the assignment
  9. See the completed item in helper history

Ops flow

  1. Open the operations view
  2. Watch live requests enter the system
  3. See matching and status changes in realtime
  4. Monitor stats and activity feed
  5. Run the demo scenario when presenting the product

Offer / charity flow

  1. Create an offer
  2. Set an expiry window
  3. Enable auto-route to charity
  4. If a person claims it, the normal handoff flow continues
  5. If nobody claims it in time, the offer routes to a named charity
  6. The donor still receives a closing message so the story ends with impact

Repo Structure

bridgeai/
├── client/   # React web app
├── mobile/   # Expo React Native app
├── server/   # Express API, Socket.IO, auth, Twilio, matching logic
├── docs/     # Presentation assets
└── scripts/  # PowerPoint generator and repo scripts

Server modules

  • server/src/agent: classification, matching, orchestration, messaging logic
  • server/src/auth: JWT, Google identity handling, auth middleware
  • server/src/db: schema and Postgres query layer
  • server/src/routes: auth, submit, requests, offers, stats, demo, helper console
  • server/src/socket: realtime events

Mobile modules

  • mobile/src/navigation: auth gating and route structure
  • mobile/src/screens: onboarding, login, request, citizen, helper, demo, ops
  • mobile/src/components: reusable UI, helper panels, history, dashboard blocks
  • mobile/src/api: backend clients
  • mobile/src/store: auth, theme, stats, map, activity state

Tech Stack

  • Frontend web: React
  • Mobile: Expo + React Native + TypeScript
  • Backend: Express + TypeScript
  • Database: PostgreSQL
  • Realtime: Socket.IO
  • Messaging: Twilio
  • AI extraction: Anthropic SDK + keyword fallback
  • Auth: email/password + Google sign-in
  • State: Zustand

Quick Start

1. Install dependencies

2. Configure environment variables

Create a root .env from .env.example:

Create a mobile env file:

cp mobile/.env.example mobile/.env

3. Start the backend

npm run dev --workspace=server

Backend URLs:

  • API health: http://localhost:3001/api/health
  • helper console: http://localhost:3001/helper
  • backend home: http://localhost:3001/

4. Start the mobile app

For Android emulator:

Or run server + mobile together:

5. Start the web app

That runs:

  • server
  • client

Environment Variables

Root .env

See .env.example for the full template.

Important values:

DATABASE_URL=postgresql://localhost:5432/bridgeai
ANTHROPIC_API_KEY=your_key_here
TWILIO_ACCOUNT_SID=your_sid_here
TWILIO_AUTH_TOKEN=your_token_here
TWILIO_PHONE_NUMBER=+1234567890
JWT_SECRET=bridgeai_demo_secret
PORT=3001
CLIENT_URL=http://localhost:5173
GOOGLE_WEB_CLIENT_ID=your_google_web_client_id.apps.googleusercontent.com

Mobile mobile/.env

EXPO_PUBLIC_API_URL=http://localhost:3001/api
EXPO_PUBLIC_GOOGLE_EXPO_CLIENT_ID=your_google_expo_client_id
EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID=your_google_android_client_id
EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=your_google_ios_client_id
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=your_google_web_client_id

Android Emulator Notes

For Android emulator, localhost inside the app will not point at your Mac.

Use:

EXPO_PUBLIC_API_URL=http://10.0.2.2:3001/api

Recommended local flow:

  1. Start the server
  2. Boot the Android emulator
  3. Run npm run mobile:start
  4. Press a in the Expo terminal

Google Sign-In

BridgeAI supports Google auth on:

  • mobile login
  • helper console web login

Minimum setup:

  1. Create a Google Cloud project
  2. Configure the OAuth consent screen
  3. Add yourself as a test user
  4. Create:
    • a Web OAuth client
    • an Android OAuth client
  5. Put the client IDs into:
    • .env
    • mobile/.env

The helper console uses:

The mobile app uses:

EXPO_PUBLIC_GOOGLE_EXPO_CLIENT_ID=...
EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID=...
EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=...
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=...

Database

The backend uses PostgreSQL and syncs additive schema updates on boot.

If you want to fully reapply the schema:

Helper Console

The local browser helper surface is available at:

http://localhost:3001/helper

Use it to:

  • sign in as a helper
  • review open requests
  • accept a request
  • mark arrival
  • verify OTP
  • complete the handoff
  • create quick test requests for demo use

Demo Accounts

For quick local testing, demo fallback login is available:

This is useful for local testing only.

Core Flow

A typical end-to-end run looks like this:

  1. A requester submits a need from mobile, web, or message input
  2. BridgeAI classifies urgency and need
  3. The request enters the helper queue
  4. A helper accepts it
  5. The requester sees tracking updates
  6. The helper arrives
  7. The requester shares the OTP
  8. The helper verifies the OTP and completes the handoff
  9. The event appears in history and ops stats

Main Scripts

Root

npm run dev
npm run build
npm run db:reset
npm run dev:mobile
npm run mobile:start
npm run mobile:android
npm run mobile:ios
npm run mobile:web
npm run mobile:typecheck
npm run presentation:build

Server

npm run dev --workspace=server
npm run build --workspace=server
npm run db:reset --workspace=server

Mobile

npm run start --workspace=mobile
npm run start:clear --workspace=mobile
npm run android --workspace=mobile
npm run ios --workspace=mobile
npm run web --workspace=mobile
npm run typecheck --workspace=mobile

Presentation Deck

The repo includes an editable PowerPoint deck:

docs/presentation/BridgeAI-hackathon-deck.pptx

You can regenerate it with:

npm run presentation:build

The generator lives at:

scripts/generate-presentation.mjs

Current Caveats

  • full remote push notifications are not available in Expo Go; use a development build for real push behavior
  • Google sign-in depends on correct OAuth client IDs in local env files
  • the value of the system depends on reliable helper availability and trust, not just routing logic
  • Twilio and Anthropic features require valid credentials to test their full paths

Project Positioning

BridgeAI is strongest when presented as:

  • a calm requester experience
  • a fast helper dispatch experience
  • a live operations view
  • a charity fallback for unused offers

That combination makes the project more than a form app or a dashboard. It becomes a response network.