Air Quality Trends Analysis Project
Full-stack air quality analytics platform built with FastAPI, React, and MySQL. Aggregates multi-source PM2.5/PM10 data, performs multi-city comparison and time-series forecasting (SARIMAX), and integrates an LLM-based planning agent with tiered access, secure APIs, and PDF reporting.
Installation
npx air-quality-trends-analysis-projectAsk AI about Air Quality Trends Analysis Project
Powered by Claude Β· Grounded in docs
I know everything about Air Quality Trends Analysis Project. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π AirSense β Multi-Agentic Air Quality Trends Analysis System
AirSense is a full-stack air quality monitoring and analytics platform designed to transform fragmented environmental data into actionable insights.
The system aggregates multi-source PM2.5 and PM10 data, performs comparative analytics, delivers AI-powered forecasts, and enables natural-language analytics through an LLM-based planning agent.
This project was developed as a collaborative group project at SLIIT for the Information Retrieval and Web Analytics (IT3041) module.

π Key Features

π Multi-Source Data Aggregation
- Scrapes hourly air quality data from Open-Meteo, OpenAQ, IQAir, and WAQI
- Applies weighted aggregation with outlier trimming to ensure reliable data
- Persists clean, aggregated time-series data in MySQL
π Advanced Analytics
- Multi-city comparison with KPIs (mean, min, max PM levels)
- Best vs worst city ranking
- Part-to-whole and trend-based analysis
π AI-Powered Forecasting
- Time-series forecasting using SARIMAX
- Confidence intervals and backtesting (MAE, RMSE)
- Single-city and multi-city prediction support
π€ LLM-Based Planning Agent (Enterprise Tier)
- Natural-language queries converted into executable analysis plans
- Uses a critic-based reflection pattern to ensure security and capability limits
- Transparent execution traces for explainability
π Security & Tiered Access
- JWT-based authentication with bcrypt password hashing
- Subscription tiers: Free, Pro, Enterprise
- Plan-based enforcement of data windows, city limits, and forecast horizons
π§Ύ Professional Reporting
- Auto-generated PDF reports with charts and KPI tables
- Server-side rendering using ReportLab
π§± System Architecture
AirSense follows a four-layer architecture:
- Presentation Layer β React SPA with interactive charts
- Application Layer β FastAPI backend with modular routers
- Data Layer β MySQL + SQLAlchemy ORM
- Intelligent Agent Layer β LLM planner with MCP-style tool orchestration
This architecture enables scalability, security, and clear separation of concerns :contentReference[oaicite:1]{index=1}.
π οΈ Tech Stack
- Frontend: React, Tailwind CSS, Recharts
- Backend: FastAPI (Python), Uvicorn
- Database: MySQL, SQLAlchemy
- AI / Analytics: SARIMAX, LLM (Ollama / Gemma), Agent Planning
- Security: JWT, bcrypt
- Reporting: ReportLab (PDF generation)
π§ Responsible AI Practices
- Fairness: Multi-source aggregation to reduce sensor bias
- Explainability: Interpretable SARIMAX models + execution traces
- Transparency: Visible data sources, KPIs, and agent steps
- Privacy: No personal location tracking; secure credential handling







π₯ Team & Leadership
Team Leader & Full-Stack Integration Architect:
Hirusha D G A D (IT23183018)
Key contributions include:
- AI forecasting engine & backtesting
- LLM agent design and orchestration
- Authentication & tier enforcement
- System-wide integration and documentation leadership
(Full contribution breakdown available in the final report) :contentReference[oaicite:2]{index=2}.
π― Academic Context
- Institution: Sri Lanka Institute of Information Technology (SLIIT)
- Module: IT3041 β Information Retrieval and Web Analytics
- Year: 2025
- Project Type: Group Project (Industry-oriented system)
π Future Enhancements
- Real-time alerts for pollution thresholds
- Additional data sources & ML models
- Extended agent reasoning capabilities
- Cloud deployment and CI/CD pipelines
π License
This project is released for academic and learning purposes.
