AidMap

Inspiration

I built AidMap after following worsening news cycles where people on the ground were still asking on social media for shelter, water, or medical help hours after official situation reports came out. I was frustrated that the simplest question, "Where is the nearest safe, relevant resource right now?", was still answered by scrolling through feeds or PDFs. I wanted something:

Fast, device friendly, and bandwidth light.
Open, free-tier sustainable (no vendor lock or surprise bills).
Simple enough for rapid hackathon iteration yet extensible for real-world pilots.

What it does

AidMap lets someone open a map and immediately see nearby crisis aid resources (shelters, food, medical, water, supplies). Users can:

View clustered markers (auto expands as you zoom).
Filter by resource type and disaster category.
Apply distance + sorting (nearest, newest, alphabetical).
Add new resources (with geolocation capture) after authenticating.
Soft delete their own entries (preserving data integrity + audit potential).
Fall back to a mock dataset if the live database is unavailable (demo/offline mode).

The UI emphasizes quick triage: minimal chrome, strong contrast, keyboard accessibility, and resilience when Firebase config/env vars are missing.

How I built it

Stack decisions

React (Create React App) for speed and familiarity.
Tailwind CSS for rapid, consistent dark UI styling.
Leaflet + react-leaflet for open-source mapping (no paid tile APIs) with OpenStreetMap tiles.
Firebase Realtime Database + Email/Password Auth for real-time sync and straightforward auth upgrade path.
Supercluster for performant client-side clustering.

Data model Each resource stores: id, type, disaster categories, coordinates, name, description, created timestamp, owner UID, and a status field (pending|approved|deleted) supporting moderation & soft deletion.

Filtering & distance I used a memoized filter pipeline (type → disaster tags → moderation status → distance slice → sort). Distance uses the Haversine formula: [ d = 2R \cdot \arcsin\Bigg( \sqrt{ \sin^2\Big(\frac{\varphi_2-\varphi_1}{2}\Big) + \cos\varphi_1 \cos\varphi_2 \sin^2\Big(\frac{\lambda_2-\lambda_1}{2}\Big) } } \Bigg) ] where (R) is Earth radius, (\varphi) latitude (radians), and (\lambda) longitude.

Resilience If Firebase env variables are absent (common in forks or first-time deploys), initialization is gracefully skipped and a deterministic mock dataset loads—preventing the dreaded white-screen failure. Soft delete gracefully falls back when permission rules reject a hard delete.

State & performance

Central orchestration in App.jsx with tight effect guards to avoid unnecessary listeners.
LocalStorage for filter presets (low-friction personalization without user profile complexity).
Cluster recalculation scoped to resource or viewport changes; distance sorting isolated from clustering.

Challenges I ran into

White screen on deploy: Missing environment variables originally caused runtime crashes. I refactored Firebase bootstrap to short-circuit safely and surface warnings.
ESLint gating builds: Unused variables in iterative refactors broke production builds (Vercel). Keeping a strict lint pass CI mentality helped catch them early.
Balancing mock vs live data: Needed a clear logical boundary so mock data never pollutes production. I solved this with an explicit mock augmentation layer only executed when live listener is absent or returns sparse results.
Deletion semantics: Direct deletes can fail under tighter rules. Implemented soft delete fallback (status = deleted) to preserve UX while respecting security.
Cluster performance vs accuracy: Ensuring distance sorting didn’t fight with cluster rendering required separating display grouping (clusters) from logical ordering (sorted list & drawer).
Auth upgrade path: Avoided anonymous auth to keep auditability; surfaced clear error messages to reduce user friction.

Accomplishments that I'm proud of

A clean, minimal interface that still packs real-time, clustering, filtering, and resilience layers.
Zero-cost infra footprint (open tiles + free-tier DB + no proprietary maps).
Guardrails preventing brittle first-deploy failures (mock fallback, conditional initialization).
Extensible moderation model baked in early (status field) without overengineering an admin UI yet.
Consistent accessibility groundwork (focus rings, semantic structure) from the start.

What I learned

(I’m still writing in first person; this header mirrors hackathon template wording.) I reinforced that “resilience-first” saves enormous debugging time later—treat every external system (auth, DB, geolocation) as conditionally available. I also re-learned the value of designing data state transitions (pending → approved → deleted) early so features like moderation, offline queueing, or analytics can grow organically. Finally, clustering + distance interplay reminded me to decouple computational concerns: compute once, reuse many times.

What’s next for AidMap

Planned evolutions:

Offline-first & PWA: queued writes with background sync when connectivity returns.
Moderation dashboard & role-based approvals (promote trusted curators).
Report/Flag flow with lightweight reputation signals.
Multi-language localization & right-to-left layout testing.
Enhanced accessibility: screen reader map summaries, cluster keyboard traversal, focus trapping in drawers.
Admin analytics (resource density hotspots, freshness decay scoring).
Geofenced push/email alerts for new nearby critical resources (privacy-aware opt-in).
Data provenance markers ("community-sourced", "verified") with visual badges.
Export & interoperability: GeoJSON download + simple ingestion API.
Disaster timeline layering (phases vs resources over time) for situational awareness.

Closing reflection

I started to solve a clarity gap during chaotic moments. AidMap’s current footprint is intentionally lightweight, but its architecture is positioned for a trustworthy, extensible aid discovery network. Every added feature will keep the same constraints: open, rapid, resilient, respectful of user attention.