OpenHelpMap — Capstone (Group 54)

An AI-assisted volunteer-donor coordination platform connecting people who need help with those who can provide it via an interactive map.

Getting Started

1. Prerequisites

You must have Node.js and Git installed.

node -v
git --version

2. Clone and Install

git clone https://github.com/Spacebarium/open-help-map.git
cd open-help-map
npm install

3. Environmental Variables

There are two .env files to separate local development from production: .env.development and .env.production. Grab the info from the Discord.

VITE_SUPABASE_URL="https://[dev/prod project id].supabase.co"
VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY="[dev/prod publishable key]"

4. Run the App

npm run dev

It will be available at http://localhost:5173

Tech Stack

• Frontend: React (Vite) + TypeScript
• Styling: CSS Modules (Scoped per component)
• Database: Supabase (PostgreSQL + PostGIS + pgvector)
• Backend: Supabase Edge Functions (Deno/TypeScript)
• Maps: Leaflet + React-Leaflet
• State: React Context + Custom Hooks

Project Structure

Path	Description
src/contexts/	Global Providers (AuthContext)
src/hooks/	Logic & Data Fetching (useRequests, useAuth)
src/layouts/	Page wrappers (AppLayout)
src/pages/	Full Screens (MapHome, Dashboard, Login)
src/services/	API Configuration (supabase.ts)
src/utils/	Helpers (mapUtils, mapIcons)
supabase/functions/	AI Backend (parse-request, embed-request)

Component Map

• Map Gadgets: src/components/map/

  • MapPin (red/blue markers)
  • LocationPicker (draggable pin for forms)
  • FilterBar (floating UI)
  • PinPopup (action bubble)

• Dashboard Tabs: src/components/dashboard/

  • ActivityTab (active missions/tasks/wtv)
  • RequestTab / OffersTab (management views)

AI Workflow

We will use Supabase Edge Functions for AI tasks

• Magic Form (parse-request):

  • User types "Flood help needed in Subang"
  • AI converts to JSON: { category: "rescue", urgency: "high" }

• Smart Matching:

  • For now, it's just some heuristic scoring like: `(Urgency * 10) - (Distance KM).
  • (future) Vector Search using embedding columns

Workflow Rules

1. Branching:

   • main is protected, don't pull-request to here, pr to dev
   • New feature: git checkout -b feat/dashboard-tabs
   • Bugfix: git checkout -b fix/map-crash

2. Styling:

   • Use CSS Modules (styles.module.css) co-located with components
   • No global CSS except for resets

3. Commits:

   • Be descriptive. "Fixed map pin bug" > "Fix"