Hackathon Solution: Good Health & Well-Being through AI-Driven Air Quality Intelligence

Urban residents in fast-developing Malaysian cities face growing health risks from worsening air quality and traffic congestion. Prolonged exposure to pollutants like PM2.5, NO₂, and CO contributes to respiratory illnesses, while congestion increases stress and accident risks. Despite available open datasets, city health planning often lacks real-time insights, leaving vulnerable communities exposed.

NafasLokal is an AI-driven solution that integrates air quality, traffic patterns, and health data to support better decision-making for healthier cities.

• Problem Statement
• Our Solution
• Key Features
• System Requirements
• Installation Guide
• Environment Configuration
• Running the Application
• Deployment Options
• Project Structure
• Tech Stack
• Data Integration
• API Documentation
• Troubleshooting
• Team
• License

• Air pollution health crisis: Malaysian cities experience hazardous air quality during haze season and peak traffic hours
• Lack of actionable insights: Raw pollution data exists but isn't translated into health-protective actions
• Vulnerable populations at risk: Children, elderly, asthma patients, and outdoor workers need timely, personalized alerts
• No incentive for behavior change: People lack motivation to choose healthier commute options

NafasLokal addresses these challenges through four integrated pillars:

• Live PM2.5, NO₂, CO, and O₃ data from DOE Malaysia, WAQI, and OpenAQ
• Location-based exposure scoring with health risk levels
• Interactive map with pollution heatmaps and station markers

• 24-hour pollutant forecasts using machine learning
• Personalized health scores based on exposure patterns
• Actionable recommendations (optimal exercise windows, route suggestions)
• Vulnerable group advisories with specific guidance

• Daily/weekly challenges encouraging healthier choices
• XP system, streaks, badges, and leaderboards
• Rewards for choosing public transit, avoiding peak pollution hours
• Community impact tracking

• Route recommendations based on real-time air quality
• Peak pollution hour alerts
• Transit vs. driving comparison for exposure levels
• Green corridor suggestions

# Clone the repository
git clone https://github.com/aimanzahar/air.git

# Navigate to project directory
cd air

# Install Node.js dependencies
npm install

# Or using npm ci for exact versions (recommended for production)
npm ci

# Copy the example environment file
# Windows (PowerShell):
Copy-Item .env.example .env.local

# Windows (Command Prompt):
copy .env.example .env.local

# Linux/macOS:
cp .env.example .env.local

Edit .env.local with your configuration. See Environment Configuration for details.

# Login to Convex (first time only)
npx convex login

# Initialize Convex project (first time only)
npx convex init

# Deploy Convex functions
npx convex deploy

Create a .env.local file in the root directory with the following variables:

# Convex Database
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
CONVEX_DEPLOY_KEY=convex_1a2b3c4d5e...

# AI Configuration
OPENAI_API_KEY=sk-your-openai-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4

# Application
NODE_ENV=development
PORT=3000

# Start development server with hot reload
npm run dev

The application will be available at http://localhost:3000

# Build the application
npm run build

# Start production server
npm start

# Build and start with Docker Compose
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

1. Push code to GitHub
2. Visit vercel.com and import your repository
3. Add environment variables in Vercel dashboard
4. Deploy automatically

See DEPLOYMENT.md for detailed Docker and Portainer deployment instructions.

# Quick Docker deployment
docker build -t nafaslokal .
docker run -p 3000:3000 --env-file .env.local nafaslokal

# On your server
git clone https://github.com/aimanzahar/air.git
cd air
npm ci
cp .env.example .env.local
# Edit .env.local with your values
npm run build
npm start

air/
├── convex/                    # Convex backend (real-time database)
│   ├── air/                   # Air quality module
│   │   ├── schema.ts          # Database schema definitions
│   │   ├── auth.ts            # Authentication functions
│   │   ├── passport.ts        # User profile functions
│   │   ├── healthProfile.ts   # Health profile functions
│   │   └── airQualityHistory.ts # Air quality data functions
│   └── _generated/            # Auto-generated Convex files
│
├── src/
│   ├── app/                   # Next.js App Router pages
│   │   ├── page.tsx           # Landing page
│   │   ├── dashboard/         # Main dashboard with air quality map
│   │   ├── ai-health/         # AI health predictions page
│   │   ├── gamification/      # BreathQuest gamification page
│   │   ├── register/          # User registration page
│   │   └── api/               # API routes
│   │       ├── ai-health/     # AI health endpoint
│   │       ├── air-quality/   # Air quality data endpoint
│   │       ├── chat/          # AI chatbot endpoint
│   │       ├── healthcare/    # Healthcare facilities endpoint
│   │       ├── waqi/          # WAQI API integration
│   │       ├── openaq/        # OpenAQ API integration
│   │       └── doe/           # DOE Malaysia API integration
│   │
│   ├── components/            # React components
│   │   ├── map/               # Map components (AirQualityMap, Heatmap)
│   │   ├── chat/              # Chat widget components
│   │   ├── health/            # Health profile components
│   │   ├── healthcare/        # Healthcare finder components
│   │   ├── analytics/         # Analytics & comparison charts
│   │   └── navigation/        # Navigation components
│   │
│   ├── contexts/              # React context providers
│   │   ├── AuthContext.tsx    # Authentication state
│   │   └── ChatContext.tsx    # Chat state management
│   │
│   ├── lib/                   # Utility libraries
│   │   ├── airQualityService.ts  # Air quality data fetching
│   │   ├── chatService.ts        # Chat API service
│   │   ├── healthcareService.ts  # Healthcare API service
│   │   └── locationService.ts    # Geolocation utilities
│   │
│   └── types/                 # TypeScript type definitions
│       ├── airQuality.ts      # Air quality types
│       └── chat.ts            # Chat types
│
├── docs/                      # Documentation
│   └── chatbot-architecture.md
│
├── scripts/                   # Deployment scripts
│   ├── start.sh               # Production start script
│   └── verify-convex.sh       # Convex verification
│
├── public/                    # Static assets
├── docker-compose.yml         # Docker Compose configuration
├── Dockerfile                 # Docker build configuration
├── DEPLOYMENT.md              # Deployment guide
└── package.json               # Project dependencies

{
  "next": "16.0.5",
  "react": "19.2.0",
  "convex": "^1.29.3",
  "openai": "^6.9.1",
  "leaflet": "^1.9.4",
  "recharts": "^3.5.1",
  "tailwindcss": "^4"
}

NafasLokal aggregates data from multiple authoritative sources:

The application uses Convex for real-time data:

Cause: Convex functions not deployed

Solution:

npx convex deploy

Cause: Missing environment variables

Solution: Ensure .env.local exists with proper values

Cause: Browser location permission denied

Solution: Allow location access or the map will use Kuala Lumpur as default

Cause: OpenAI API key not configured

Solution: Add valid OPENAI_API_KEY to .env.local

Cause: Insufficient memory for Next.js build

Solution:

# Increase Node.js memory limit
$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

1. Check the Convex Documentation
2. Review Next.js Documentation
3. Open an issue on GitHub

• Daily: Morning air checks, avoiding peak pollution
• Weekly: Clean route choices, public transit usage
• Achievements: Long-term health milestones

• XP points for healthy actions
• Streak bonuses for consistency
• Badges for achievements
• Leaderboard rankings

1. Daily Commuters - Route optimization for lower exposure
2. Parents - Protect children during outdoor activities
3. Elderly - Health alerts for sensitive individuals
4. Outdoor Workers - Mask and schedule recommendations
5. Health-Conscious Citizens - Track and improve air exposure

• Health Protection: Reduces respiratory illness risk through actionable alerts
• Behavior Change: Gamification drives adoption of healthier commute choices
• Community Data: Crowdsourced readings improve pollution mapping
• Vulnerable Support: Targeted advisories for at-risk populations
• Urban Planning: Data insights for city health policy decisions

Malaysia-first air wellness platform with clean, modern design

Real-time AQI dashboard with interactive map, exposure tracking, and AI chat

Personalized health scores with 24-hour pollutant forecasts

Gamified challenges with XP system, badges, and leaderboards

• Mobile app (React Native)
• Integration with wearables for personal exposure tracking
• Clinic proximity analysis for underserved areas
• Traffic density API integration
• Multi-city expansion (Penang, JB)

Built for Malaysia's urban health future.

MIT License

• DOE Malaysia for air quality data
• WAQI for global air quality index
• OpenAQ for open environmental data
• Convex for real-time database infrastructure
• OpenAI for AI/ML capabilities