Aqivity (Activity Guardian)

AI-powered air-quality guidance for outdoor activities.

Activity Guardian combines hourly air-quality forecasts with AI-generated advice to help people make more informed decisions about activities such as walking, running, and cycling.

Features

• Location-based air-quality forecast using browser geolocation
• Hourly US AQI and readings for PM2.5, PM10, ozone, nitrogen dioxide, carbon monoxide, and sulphur dioxide
• Activity-specific recommendations generated by Gemma 3 12B IT through Amazon Bedrock Mantle
• Recommendation explanations and a suggested time based on forecast data
• Graceful handling when forecast data is available but AI recommendations fail

Architecture

React + Vite frontend
        |
        | HTTPS
        v
AWS Lambda (Node.js)
        |
        +---- Open-Meteo Air Quality API
        |
        +---- Amazon Bedrock Mantle
                    |
                    v
             Gemma 3 12B IT

Tech Stack

• Frontend: React, Vite, JavaScript, CSS
• Backend: Node.js, AWS Lambda, Lambda Function URL
• AI: Gemma 3 12B IT via Amazon Bedrock Mantle
• Air-quality data: Open-Meteo Air Quality API

Run the Frontend Locally

Requirements: Node.js and npm.

cd frontend
npm install
npm run dev

Vite prints the local development URL in the terminal.

Backend Configuration

The backend source is located at backend/index.mjs. It runs on AWS Lambda and exposes an HTTPS Function URL called by the frontend.

Configure these environment variables in Lambda:

• BEDROCK_API_KEY — Bedrock Mantle API key
• BEDROCK_MODEL_ID — google.gemma-3-12b-it
• BEDROCK_BASE_URL — https://bedrock-mantle.ap-south-1.api.aws/v1

The backend fetches forecast data from Open-Meteo and requests an activity-specific recommendation from Gemma. Keep the API key on the backend; never put it in frontend code or commit it to Git.

Data and Limitations

• Open-Meteo provides modelled forecast data. It is not guaranteed to represent a nearby physical monitoring station or official CPCB measurements.
• Recommendations depend on forecast availability and AI output. They are informational, not medical advice, and do not guarantee an activity is safe.
• If browser requests fail, check that the deployed Vercel origin is allowed by the Lambda Function URL's CORS configuration.

Security

Do not commit API keys, .env files, AWS credentials, or other secrets. Keep node_modules/ and generated build output (dist/) out of version control.

Future Improvements

• Include official monitoring-station data where available
• Improve recommendation validation and accessibility
• Add richer forecast comparisons and user preferences