A Flutter mobile application for real-time weather monitoring and air quality tracking — with AQI metrics, pollutant breakdowns, multi-day forecasts, and personalized health recommendations.
📦 Repository: github.com/DangHuuLong/Weather-App
Weather App is a Flutter application that combines live weather data and air quality index (AQI) information into a single mobile experience. Users are guided through an onboarding flow, authenticate via login, and land on a dashboard displaying current conditions, pollutant levels, hourly and 7-day forecasts, and AI-generated health recommendations based on live data.
The app integrates with WeatherAPI for weather data and WAQI for air quality data, using reverse geocoding to resolve human-readable location names from coordinates.
- 🌬️ Onboarding — Multi-slide intro experience focused on breathing quality, pollution tracking, and exposure control
- 🔐 Login — Email/password authentication with input validation
- 🏠 Home Dashboard — Current weather, AQI overview, and upcoming forecast UI with cached data support
- 📍 Location Details — Deep-dive view with pollutant metrics (O₃, PM10, NO₂, PM2.5, SO₂, CO), hourly weather, 7-day AQ forecast, 7-day weather forecast, and recommendation cards
- 📊 AQI Scale — Reference screen explaining AQI ranges and health categories
- 🗃️ Data Bank — Data request form UI routing to location detail views
- 👤 More — Profile and settings menu including Saved Locations, FAQ, Settings, About Us, Contact Us, and Logout
- 💾 Local Caching — Weather data and auth tokens stored locally via SharedPreferences
- 🔄 Reverse Geocoding — Derives street/location names from device coordinates
App Launch
└── Onboarding (multi-slide intro)
└── Login (email + password validation)
└── Root Page (bottom navigation)
├── 🏠 Home
│ └── Location Details
│ └── AQI Scale
├── 🗃️ Data Bank
└── 👤 More
After a successful login, the app navigates to the main shell with a bottom navigation bar. Auth tokens are persisted locally so returning sessions can be restored.
| Concern | Technology |
|---|---|
| Framework | Flutter |
| Language | Dart |
| State Management | provider + flutter_bloc |
| HTTP Client | dio |
| Local Storage | shared_preferences |
| Geocoding | geocoding |
| Code Generation | freezed + json_serializable |
| Weather Data | WeatherAPI |
| Air Quality Data | WAQI |
| Auth API | EscuelaJS |
The project follows a layered architecture separating data access, state, and UI concerns:
┌──────────────────────────────────┐
│ UI Layer │
│ (page/ — screens & widgets) │
└──────────────┬───────────────────┘
│
┌──────────────▼───────────────────┐
│ State Layer │
│ (providers/ + flutter_bloc) │
└──────────────┬───────────────────┘
│
┌──────────────▼───────────────────┐
│ Data Layer │
│ api/ · models/ · storage/ │
└──────────────┬───────────────────┘
│
┌──────────┴──────────┐
▼ ▼
WeatherAPI WAQI
(weather + forecast) (air quality)
api/— Remote service calls (WeatherAPI, WAQI, auth)models/— Typed data models, generated withfreezedandjson_serializablestorage/— Local persistence for tokens and cached weather dataproviders/— Lightweight app-level state usingproviderpage/— All screens and UI modules
weather_app/
├── lib/
│ ├── api/ # Remote API service classes
│ ├── models/ # Dart data models (freezed/json)
│ ├── page/
│ │ ├── aqi_scale/ # AQI scale reference screen
│ │ ├── data_bank/ # Data request form UI
│ │ ├── home/ # Home dashboard screen
│ │ ├── location_details/ # Detailed AQ + weather view
│ │ ├── login.dart # Login screen
│ │ ├── more.dart # Profile / settings menu
│ │ ├── on_boarding.dart # Onboarding slides
│ │ └── root_page.dart # Bottom nav shell
│ ├── providers/ # Provider-based app state
│ ├── storage/ # SharedPreferences helpers
│ └── main.dart # App entry point
├── assets/ # Images, icons, static files
├── android/
├── ios/
├── linux/
├── macos/
├── web/
├── windows/
├── test/
├── pubspec.yaml
└── README.md
Used to fetch current weather conditions, hourly forecasts, and 7-day weather forecasts based on location.
Used to fetch real-time AQI data and individual pollutant readings including O₃, PM10, NO₂, PM2.5, SO₂, and CO.
Reverse geocoding via the geocoding package resolves human-readable street and location names from device coordinates.
Login and token management is handled via the EscuelaJS public API.
⚠️ API keys and tokens are currently configured directly in the source code. Ensure valid credentials are in place before running the app against live services.
The app persists the following data locally using shared_preferences:
| Key | Contents |
|---|---|
| Access token | JWT access token from login |
| Refresh token | JWT refresh token |
| Cached weather | Latest weather response for the default location |
Cached weather data is used on the Home screen when fresh data is unavailable.
The project uses two complementary state management approaches:
provider— Lightweight app-level state such as auth status and shared UI stateflutter_bloc— Bloc/Cubit pattern for more structured state in specific screens
Not every screen is fully wired to Bloc in the current implementation; some screens use Provider or local state directly.
Multi-slide introduction to the app. Messaging covers breathing better, tracking air pollution, and managing exposure. Leads to the login screen.
Email and password form with validation. On success, navigates to the main app shell. Auth tokens are stored locally.
Displays current weather conditions and AQI for the current location. Shows a short forecast UI. Uses cached data when available and navigates to Location Details for a deeper view.
Note: The current implementation uses a default city configured in code.
The most data-dense screen. Shows:
- Current weather
- Pollutant breakdown: O₃, PM10, NO₂, PM2.5, SO₂, CO
- Hourly weather timeline
- 7-day air quality forecast
- 7-day weather forecast
- Recommendation cards generated from live weather and AQ data
Informational screen explaining AQI value ranges and their associated health categories.
Form-based UI for data requests. Current implementation is primarily UI-driven and routes to location detail views.
Profile and settings menu with the following items:
- Profile
- Saved Location
- FAQ
- Settings
- About Us
- Contact Us
- Logout
- Flutter SDK (stable channel recommended)
- Dart (included with Flutter)
- Android Studio, VS Code, or another Flutter-compatible IDE
- A connected device or emulator
# Clone the repository
git clone https://github.com/DangHuuLong/Weather-App.git
cd Weather-App
# Install dependencies
flutter pub getflutter runTo generate code for freezed and json_serializable models:
dart run build_runner build --delete-conflicting-outputs- The Home screen uses a default city value hard-coded in source. Dynamic location-based fetching may require additional permission and GPS configuration.
- API keys for WeatherAPI and WAQI are currently embedded in the source code. For any fork or deployment, replace these with your own valid credentials.
- The Data Bank screen is primarily UI-driven in the current state; a full backend data request flow has not been confirmed.
- Some More menu items (e.g. Saved Location, Settings, About Us) may be partially implemented.
- The project integrates both
providerandflutter_bloc; state management coverage varies across screens. - Live data depends on active and valid API subscriptions to WeatherAPI and WAQI.
Built with ❤️ by DangHuuLong using Flutter & Dart
Repository
A Flutter mobile application for real-time weather monitoring and air quality tracking — with AQI metrics, pollutant breakdowns, multi-day forecasts, and personalized health recommendations.
📦 Repository: github.com/DangHuuLong/Weather-App
Weather App is a Flutter application that combines live weather data and air quality index (AQI) information into a single mobile experience. Users are guided through an onboarding flow, authenticate via login, and land on a dashboard displaying current conditions, pollutant levels, hourly and 7-day forecasts, and AI-generated health recommendations based on live data.
The app integrates with WeatherAPI for weather data and WAQI for air quality data, using reverse geocoding to resolve human-readable location names from coordinates.
- 🌬️ Onboarding — Multi-slide intro experience focused on breathing quality, pollution tracking, and exposure control
- 🔐 Login — Email/password authentication with input validation
- 🏠 Home Dashboard — Current weather, AQI overview, and upcoming forecast UI with cached data support
- 📍 Location Details — Deep-dive view with pollutant metrics (O₃, PM10, NO₂, PM2.5, SO₂, CO), hourly weather, 7-day AQ forecast, 7-day weather forecast, and recommendation cards
- 📊 AQI Scale — Reference screen explaining AQI ranges and health categories
- 🗃️ Data Bank — Data request form UI routing to location detail views
- 👤 More — Profile and settings menu including Saved Locations, FAQ, Settings, About Us, Contact Us, and Logout
- 💾 Local Caching — Weather data and auth tokens stored locally via SharedPreferences
- 🔄 Reverse Geocoding — Derives street/location names from device coordinates
App Launch
└── Onboarding (multi-slide intro)
└── Login (email + password validation)
└── Root Page (bottom navigation)
├── 🏠 Home
│ └── Location Details
│ └── AQI Scale
├── 🗃️ Data Bank
└── 👤 More
After a successful login, the app navigates to the main shell with a bottom navigation bar. Auth tokens are persisted locally so returning sessions can be restored.
| Concern | Technology |
|---|---|
| Framework | Flutter |
| Language | Dart |
| State Management | provider + flutter_bloc |
| HTTP Client | dio |
| Local Storage | shared_preferences |
| Geocoding | geocoding |
| Code Generation | freezed + json_serializable |
| Weather Data | WeatherAPI |
| Air Quality Data | WAQI |
| Auth API | EscuelaJS |
The project follows a layered architecture separating data access, state, and UI concerns:
┌──────────────────────────────────┐
│ UI Layer │
│ (page/ — screens & widgets) │
└──────────────┬───────────────────┘
│
┌──────────────▼───────────────────┐
│ State Layer │
│ (providers/ + flutter_bloc) │
└──────────────┬───────────────────┘
│
┌──────────────▼───────────────────┐
│ Data Layer │
│ api/ · models/ · storage/ │
└──────────────┬───────────────────┘
│
┌──────────┴──────────┐
▼ ▼
WeatherAPI WAQI
(weather + forecast) (air quality)
api/— Remote service calls (WeatherAPI, WAQI, auth)models/— Typed data models, generated withfreezedandjson_serializablestorage/— Local persistence for tokens and cached weather dataproviders/— Lightweight app-level state usingproviderpage/— All screens and UI modules
weather_app/
├── lib/
│ ├── api/ # Remote API service classes
│ ├── models/ # Dart data models (freezed/json)
│ ├── page/
│ │ ├── aqi_scale/ # AQI scale reference screen
│ │ ├── data_bank/ # Data request form UI
│ │ ├── home/ # Home dashboard screen
│ │ ├── location_details/ # Detailed AQ + weather view
│ │ ├── login.dart # Login screen
│ │ ├── more.dart # Profile / settings menu
│ │ ├── on_boarding.dart # Onboarding slides
│ │ └── root_page.dart # Bottom nav shell
│ ├── providers/ # Provider-based app state
│ ├── storage/ # SharedPreferences helpers
│ └── main.dart # App entry point
├── assets/ # Images, icons, static files
├── android/
├── ios/
├── linux/
├── macos/
├── web/
├── windows/
├── test/
├── pubspec.yaml
└── README.md
Used to fetch current weather conditions, hourly forecasts, and 7-day weather forecasts based on location.
Used to fetch real-time AQI data and individual pollutant readings including O₃, PM10, NO₂, PM2.5, SO₂, and CO.
Reverse geocoding via the geocoding package resolves human-readable street and location names from device coordinates.
Login and token management is handled via the EscuelaJS public API.
⚠️ API keys and tokens are currently configured directly in the source code. Ensure valid credentials are in place before running the app against live services.
The app persists the following data locally using shared_preferences:
| Key | Contents |
|---|---|
| Access token | JWT access token from login |
| Refresh token | JWT refresh token |
| Cached weather | Latest weather response for the default location |
Cached weather data is used on the Home screen when fresh data is unavailable.
The project uses two complementary state management approaches:
provider— Lightweight app-level state such as auth status and shared UI stateflutter_bloc— Bloc/Cubit pattern for more structured state in specific screens
Not every screen is fully wired to Bloc in the current implementation; some screens use Provider or local state directly.
Multi-slide introduction to the app. Messaging covers breathing better, tracking air pollution, and managing exposure. Leads to the login screen.
Email and password form with validation. On success, navigates to the main app shell. Auth tokens are stored locally.
Displays current weather conditions and AQI for the current location. Shows a short forecast UI. Uses cached data when available and navigates to Location Details for a deeper view.
Note: The current implementation uses a default city configured in code.
The most data-dense screen. Shows:
- Current weather
- Pollutant breakdown: O₃, PM10, NO₂, PM2.5, SO₂, CO
- Hourly weather timeline
- 7-day air quality forecast
- 7-day weather forecast
- Recommendation cards generated from live weather and AQ data
Informational screen explaining AQI value ranges and their associated health categories.
Form-based UI for data requests. Current implementation is primarily UI-driven and routes to location detail views.
Profile and settings menu with the following items:
- Profile
- Saved Location
- FAQ
- Settings
- About Us
- Contact Us
- Logout
- Flutter SDK (stable channel recommended)
- Dart (included with Flutter)
- Android Studio, VS Code, or another Flutter-compatible IDE
- A connected device or emulator
# Clone the repository
git clone https://github.com/DangHuuLong/Weather-App.git
cd Weather-App
# Install dependencies
flutter pub getflutter runTo generate code for freezed and json_serializable models:
dart run build_runner build --delete-conflicting-outputs- The Home screen uses a default city value hard-coded in source. Dynamic location-based fetching may require additional permission and GPS configuration.
- API keys for WeatherAPI and WAQI are currently embedded in the source code. For any fork or deployment, replace these with your own valid credentials.
- The Data Bank screen is primarily UI-driven in the current state; a full backend data request flow has not been confirmed.
- Some More menu items (e.g. Saved Location, Settings, About Us) may be partially implemented.
- The project integrates both
providerandflutter_bloc; state management coverage varies across screens. - Live data depends on active and valid API subscriptions to WeatherAPI and WAQI.
Built with ❤️ by DangHuuLong using Flutter & Dart
Repository