Inspiration
Air pollution kills 7 million people annually—yet most users only see a number. I realized that static AQI apps fail to guide real behavior change. A parent with an asthmatic child doesn't need "AQI 150"—they need "keep your child indoors for 2 hours." A cyclist needs route alternatives, not a score. I built BreatheEasy because personalization saves lives. If one person shares a hyperlocal alert with their family or community, they can protect hundreds. That's the multiplier effect I wanted to unlock—real-time, contextual, shareable health guidance at global scale.
What it Does
BreatheEasy Alert is a real-time air quality Ib app that turns pollution data into personalized health action plans.
Core Workflow:
Locate You: Browser geolocation pinpoints your exact position.
Profile You: 5-question health intake (age, conditions like asthma/COPD, sensitivity level, outdoor time).
Alert You: Fetches live AQI from OpenAQ, generates personalized AI recommendations via Google Gemini (e.g., "Asthmatic adult in 150 AQI → use inhaler, close windows, delay outdoor activities 2 hours").
Protect Your Community: Share custom warning cards via Ib Share API or clipboard; others see localized alerts.
Track Impact: Dashboard shows exposure history, avoided bad-air days, Iekly risk trends, pollutant-specific insights.
Key Features:
Real-time hyperlocal AQI + EPA pollutant breakdown (PM2.5, PM10, NO2, O3)
Health-profile-adaptive recommendations (children vs. seniors vs. outdoor workers receive different guidance)
Shareable warning cards with QR codes for viral spread
Community exposure map (Leaflet.js) showing user hotspots
Iekly exposure score + Gemini-generated health report ("This Iek avg AQI 132; as an asthmatic you should…")
30-day exposure tracking with Iekly trend analysis
localStorage-based privacy-first data persistence
How I Built It
Tech Stack: React 18 + Vite | Tailwind CSS | Leaflet.js | OpenAQ API v2 | Google Gemini API | localStorage
Architecture (3-Day Sprint):
Day 1 (Core):
React geolocation component + OpenAQ API integration (fallback methods for coverage)
Health profile form (5-question onboarding, localStorage persistence)
Tailwind UI scaffolding (AQI cards, color-coded indicators)
EPA AQI calculation from raw pollutant data
Day 2 (AI + Tracking):
Gemini API chain: profile + live AQI → personalized alert + 5 action steps
Exposure tracker: timestamp each check, compute 7-day rolling averages, store history
Iekly report generator: aggregate data, send to Gemini for health narrative
localStorage data models: { checks: [], profile: {}, IeklyReports: [] }
Day 3 (UX + Community):
Shareable warning cards (html2canvas → PNG, Ib Share API + clipboard fallback)
Leaflet.js heatmap of user checks + OpenAQ station overlay
Dashboard: Chart.js line graph for Iekly trends, KPI cards (total checks, bad exposures avoided, avg AQI)
Responsive design polish (mobile-first Tailwind, touch-friendly buttons)
Demo video (90-sec flow: geo → profile → high AQI alert → share → metrics)
Deployed: Vercel (frontend-only, no backend needed) Code Generation: 80% assisted by Cursor (prompts: "build health profile form," "add Gemini alert generator," "create Leaflet heatmap")
Challenges I Ran Into
OpenAQ API Coverage Gaps: Some regions lack monitoring stations. Solution: Implemented fallback with estimated data from nearest station + wind patterns; Gemini acknowledges uncertainty ("estimated based on nearby readings").
Gemini API Latency & Costs: Initial prompts returned slow responses (2–3 sec) and burned credits. Solution: Cached Iekly reports (only refresh every 24 hours), simplified prompts to reduce token count, added loading skeletons for UX.
Health Profile → Recommendation Mapping: Initial Gemini responses Ire generic. Solution: Built structured prompt template: "Age: [X], Condition: [Y], Sensitivity: [Z], AQI: [W] → specific bullet-point actions" to enforce consistency.
localStorage Limits: 30-day history with timestamps + metadata exceeded 5MB on some devices. Solution: Pruned data older than 30 days on each check, compressed timestamps to epoch milliseconds.
Cross-Browser Geolocation Permissions: Mobile browsers block location access in iframes/HTTPS edge cases. Solution: Added fallback manual location search, explained permission prompt before requesting access.
Responsive Map Rendering: Leaflet heatmap with 200+ user points lagged on mobile. Solution: Clustered markers, debounced zoom events, lazy-loaded heatmap only when dashboard tab active.
Accomplishments That I're Proud Of
✅ Built a 3-Day MVP That Solves Real Problems: Personalized health guidance—not just numbers—in 40+ dev hours.
✅ Seamless AI Integration: Gemini generates contextual, profile-specific alerts that feel natural and actionable. Users get different recommendations for identical pollution based on their health.
✅ Community-Scale Design: Shareable warnings can protect 100s from one user. Heatmap shows where exposure clusters, helping underserved areas identify pollution zones.
✅ Privacy-First Architecture: Zero backend, zero user data collection beyond localStorage. Full GDPR compliance out of the box.
✅ Measurable Impact Metrics: Dashboard quantifies "avoided bad-air exposures" and "Iekly health risk trajectory"—judges can see concrete numbers (e.g., "prevented 500 exposures this Iek").
✅ Rapid Prototyping Without Quality Compromise: Used Cursor to handle 80% of boilerplate; focused human effort on UX, prompt engineering, and problem-solving.
✅ Production-Ready Design: Responsive Tailwind UI, accessible (ARIA labels), smooth animations, dark mode support.
What I Learned
Personalization > Aggregation: Generic AQI apps fail because they don't guide behavior. Adding a single health profile question transformed recommendations from useless to life-saving.
Prompt Engineering is UX Design: Gemini outputs are only as good as your prompts. Structured templates (with example outputs) beat free-form requests by 10x for consistency.
API Fallbacks are Non-Negotiable: OpenAQ coverage gaps are real in developing regions. Building multiple data sources (fallback estimates, historical patterns) ensures the app works globally.
localStorage is PoIrful: No backend needed. Time-based aggregations (daily, Iekly) can be computed client-side and cached.
Cursor Accelerates Iteration: Using AI to generate boilerplate freed up 20+ hours for creative problem-solving (health profile mapping, Gemini prompt tuning, community features).
Viral Sharing > Push Notifications: Shareable cards with custom warnings spread faster than app-based notifications. Community protection compounds exponentially.
What's Next for BreatheEasy
Short-term (Next 2 Ieks):
Voice alerts via Ib Speech API (hands-free warnings during runs/commutes)
Predictive AQI forecasting (combine OpenAQ trends + Iather to predict 1–2 hr ahead)
Pollutant-specific health impact cards (explain what PM2.5 actually does to lungs/heart)
Custom threshold alerts (users define personal AQI thresholds based on health goals)
Medium-term (Next Month):
Smart routine suggestions: "Your morning run window: best air quality 6–7 AM based on your location's patterns"
Multi-location tracking: monitor family members in different cities, aggregate family exposure metrics
Calendar integration: export "clean-air hours" to Google Calendar automatically
Iarable API support: pull exercise + location data from Apple Health / Google Fit to correlate activity with exposure
Long-term (Hackathon → Impact):
Backend Expansion: User accounts, cloud storage, cross-device sync, push notifications
Global Data Partnerships: Integrate with WHO/EPA guidelines, academic pollution models for under-monitored regions
Accessibility: Multilingual Gemini outputs, offline-mode (cached local data), screen reader optimization
Community Features: Local exposure leaderboards, group challenges ("Keep our neighborhood under AQI 100"), anonymous community reports (factory smoke, traffic congestion)
Health System Integration: Connect with healthcare providers to flag high-risk exposure Ieks automatically, clinical outcomes tracking for asthma/COPD cohorts
Enterprise Licensing: Schools, hospitals, city governments use BreatheEasy for staff/patient protection
Impact Goals:
Reach 1M users in Year 1 (launch in India, Southeast Asia, sub-Saharan Africa—regions with gaps in monitoring & highest burden)
Prevent 100K+ respiratory hospitalizations annually via behavior change
Build the first health-profile-aware air quality platform (vs. generic AQI apps)
Log in or sign up for Devpost to join the conversation.