HelpingHive provides a real-time map for needs, offers, and resources while giving officials a live dashboard with verified data and insights for faster, smarter disaster response.

• Overview
• Screenshots
• Features
• Architecture
• Getting Started
• Configuration (env)
• Data & Seeding
• API
• Deployment
• Troubleshooting
• License

HelpingHive is a lightweight web app that connects people who need help with neighbors who can offer help. It highlights official resources (shelters, food/supply) alongside community pins.

Map UI
HelpingHive AI Agent	Real‑time Need/Offer Pin Posting
Real‑time Pin Updates	Local Pin Visuals

• Modern, minimal map UI with a bottom pill bar (Layers · + Add · Tools · Chat)
• Pins
  • Need = teardrop; urgency (Low/Med/High) in yellow/orange/red
  • Offer = hexagon; green
  • Category initial rendered on the marker face for fast scanning
• Legend (top‑right) with a compact urgency key plus Shelter and Food icons
• Overlays: Flood (ArcGIS/WMS), Metro bus routes, Food deserts
• Reference layers: Shelters (ArcGIS + local fallback), Food/Supply (ArcGIS + CSV + local)
• HelpHive chat window (server‑assisted): clickable results that focus and highlight on map

• Frontend: static web/ (Alpine.js + Leaflet + Tailwind CDN)
• Backend: FastAPI (Python 3.11), server‑side proxies for ArcGIS/WMS
• DB: Postgres (psycopg3) for community pins/comments
• Hosting: Railway (Nixpacks), configured via Procfile and railway.toml

1. Requirements
   • Python 3.11
   • A Postgres database (e.g., Neon)
2. Create .env in the repo root:

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DB
MAPTILER_KEY=your_maptiler_key

# Optional external feeds / overlays
HOUSTON_311_URL=...
FLOOD_WMS_URL=...
FLOOD_WMS_LAYERS=0
FLOOD_ARCGIS_URL=...
FLOOD_ARCGIS_LAYERS=0

# Shelters (ArcGIS)
# Either point to a layer URL …/FeatureServer/1  OR a direct …/FeatureServer/1/query URL
SHELTERS_URL=...
# If using base …/FeatureServer, set the layer index here
# SHELTERS_LAYER=1

# Food sites (ArcGIS table or GeoJSON)
FOOD_SITES_URL=...

3. Install dependencies

pip install -r requirements.txt

4. Run locally

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

5. Open http://localhost:8000

Seed demo pins into Postgres:

python scripts/seed.py

Windows users: the script automatically switches to a compatible event loop policy.

Remove seeded data later:

delete from pins where author_anon_id like 'seed-%';

Shelters (ArcGIS)

• Supports both layer URLs and direct /query URLs.
• Server‑side conversion to WGS84 lat/lng; cached for 300s.
• Bypass cache for testing: GET /api/shelters?nocache=true.

• GET /api/pins — list community pins
• POST /api/pins — create pin
• GET /api/shelters — official/community shelters (ArcGIS + local)
• GET /api/food — food/supply sites (ArcGIS + local + CSV)
• GET /api/311 — optional 311 feed (proxy)
• POST /api/assist/qna — HelpHive assistant

• Connect the repository and deploy (Nixpacks).
• Set env vars (DATABASE_URL, MAPTILER_KEY, optional overlays and feeds).
• Start command:

uvicorn app.main:app --host 0.0.0.0 --port $PORT

• Shelters not loading?
  • Verify SHELTERS_URL returns features in a browser.
  • Test server: /api/shelters?nocache=true.
  • If using base …/FeatureServer, add SHELTERS_LAYER.
• Stale assets/icons?
  • Hard refresh (Ctrl+F5). If using a service worker, enable “Bypass for network” in DevTools.

The HelpingHive Team