Building BreatheRoute: An AI-Assisted Air Quality and Route Awareness Platform Using AWS
Explore how we built BreatheRoute, a location-aware air quality and route analysis platform using AWS, Node.js, React, Terraform, and Google Gemini. This article covers our architecture, implementation steps, debugging challenges, deployment approach, security decisions, and lessons learned.
Building BreatheRoute: An AI-Assisted Air Quality and Route Awareness Platform Using AWS
GitHub Repository: https://github.com/Universal-codeweb/BreatheRoute
1. Introduction
Air pollution is an environmental challenge that affects people across cities and countries. When planning a journey, people generally consider distance, traffic, and travel time, but air quality can also influence the quality of that journey.
BreatheRoute is an AI-assisted air quality and route awareness platform developed to explore how environmental information can be incorporated into route analysis.
The project brings together a React frontend, a Node.js backend, AWS cloud services, geographical AQI data, and Google Gemini-assisted analysis.
Our goal was not simply to build an interface. We wanted to understand how the application could store and retrieve environmental data, connect cloud services, process API requests, integrate AI, handle errors, and prepare for deployment.
This article documents our development journey, the architecture we implemented, the challenges we encountered, and the lessons we learned.
2. The Problem We Addressed
Air quality can vary from one geographical area to another. However, route planning and environmental information are often presented separately.
We wanted to explore a system that could combine these elements and help users consider environmental conditions when comparing routes.
BreatheRoute was designed to support different locations rather than being restricted conceptually to a single city. During the initial implementation, we used a defined area of Delhi to create and test our AQI grid.
Supporting a location in the application and having reliable AQI measurements for that location are two different requirements. The platform's geographical coverage ultimately depends on the availability of suitable environmental data.
3. Technology Stack
We organized the project into frontend, backend, cloud infrastructure, mapping, and AI components.
Frontend
- React for building the user interface.
- Vite for development and production builds.
- Tailwind CSS for styling.
- MapTiler for map visualization.
Backend
- Node.js for API handling and application logic.
- HTTP endpoints for retrieving AQI information and supporting route analysis.
- Google Gemini API for AI-assisted analysis.
AWS Services
- Amazon DynamoDB for AQI grid storage.
- AWS Lambda for serverless processing.
- Amazon API Gateway for HTTP access.
- Amazon EventBridge for scheduled refresh operations.
- AWS Systems Manager Parameter Store for credential management.
- Amazon EC2 and Nginx for the planned single-instance application hosting architecture.
- Terraform for infrastructure as code.
Each component has a distinct responsibility, making the application easier to test, troubleshoot, and extend.
4. Understanding the AWS Architecture
Amazon DynamoDB: Storing AQI Data
We created a DynamoDB table named
breatheroute-aqi to store AQI grid records for the Delhi demonstration area.The initial grid contained 625 cells, each representing a geographical portion of the selected area.
DynamoDB provided managed storage that could be accessed by the backend and Lambda functions without requiring us to maintain a separate database server.
AWS Lambda: Processing AQI Operations
We used Lambda functions for AQI-related operations, including grid initialization, retrieval, refreshing, and individual cell updates.
The functions included:
breatheroute-getAqiGridfor retrieving the AQI grid.- Grid-seeding logic for initializing demonstration records.
- Refresh logic for updating stored values.
- Individual-cell update logic for controlled testing.
Separating these operations made it easier to test the data workflow and investigate failures.
Amazon API Gateway: Exposing HTTP Endpoints
API Gateway provided HTTP access to the AQI functionality.
The existing API was configured in the
us-east-1 region. Its AQI endpoint allowed the application to request grid data through an HTTP interface instead of accessing DynamoDB directly from the browser.This separation helped maintain a clear boundary between the frontend and cloud data operations.
Amazon EventBridge: Scheduling Updates
We configured a scheduled refresh workflow using EventBridge.
The objective was to automate AQI-related updates instead of relying entirely on manual execution.
A scheduled refresh does not automatically make the underlying information real-time. The freshness and accuracy of the data still depend on the source and update process.
Google Gemini: AI-Assisted Analysis
Gemini was integrated into the backend to help analyze available route and environmental information.
It can assist in generating explanations and recommendations based on the information provided to it. The backend also includes fallback behavior for situations in which the AI service is unavailable or not configured.
Gemini is an analysis component, not an air quality monitoring service. Its recommendations depend on the quality and freshness of the underlying data.
AWS Systems Manager Parameter Store: Managing Secrets
We configured the Gemini API key in AWS Systems Manager Parameter Store using a
SecureString parameter:/breatheroute/gemini_api_keyThis keeps the credential separate from the application source code.
The deployment configuration is intended to allow the EC2 instance to retrieve the secret through IAM permissions rather than placing the key directly in the frontend or GitHub repository.
Terraform: Infrastructure as Code
Terraform was used to define and validate the planned hosting infrastructure.
Using infrastructure as code allowed us to review proposed resource changes before applying them. This was particularly important because the AWS account already contained Lambda functions, API Gateway resources, DynamoDB data, and scheduled operations that needed to be preserved.
5. How We Built BreatheRoute
Step 1: Developing the Frontend
We built the frontend with React, Vite, and Tailwind CSS.
The interface was designed to present geographical AQI information and support route-related functionality. MapTiler was used for map visualization.
We configured environment variables for the API URL, AWS region, mapping keys, map center, zoom level, and demonstration bounds.
For the intended single-host deployment, the frontend uses
/api as its API base path. Nginx can then forward API requests to the backend while serving the frontend files from the same host.Step 2: Creating the Delhi AQI Grid
We initialized a geographical AQI grid in DynamoDB for a defined area of Delhi.
The successful seeding response reported:
- 625 cells created.
- Latitude range: 28.6000–28.6500.
- Longitude range: 77.1900–77.2400.
This gave us a structured dataset for testing data retrieval, grid-based processing, and route analysis.
The grid represents demonstration data. It should not be interpreted as 625 independently verified live monitoring stations.
Step 3: Connecting Lambda and API Gateway
We connected the AQI retrieval functionality to API Gateway so that the application could access the data through an HTTP request.
We tested the endpoint and recorded a successful response containing 625 grid cells.
This step established the connection between the cloud data layer and the application's API workflow.
Step 4: Implementing Refresh and Update Operations
After the initial grid was seeded, we tested the refresh process and individual cell updates.
A subsequent refresh operation reported 625 cells updated successfully. We also tested an individual cell update to verify that the stored value could be changed.
These tests helped us validate the data workflow separately from the user interface.
Step 5: Connecting the Node.js Backend
The backend was configured to retrieve AQI data and support route-related processing.
For Delhi, the route workflow uses available grid values to enrich route information. The backend can also handle locations outside the initial demonstration area, where the implementation may use simulated estimates rather than verified AQI observations.
Keeping the data source explicit is important because simulated estimates must not be presented as measured environmental conditions.
Step 6: Integrating Gemini
We connected Google Gemini to the backend to assist with interpreting available information and generating route recommendations.
We also considered what should happen if the API key is missing or the external AI service cannot be reached. A fallback path allows the application to handle these cases without assuming that AI analysis always succeeds.
Step 7: Preparing the Hosting Infrastructure
We used Terraform to define the intended EC2 deployment.
The proposed hosting architecture includes:
- An Ubuntu EC2 instance.
- Nginx serving the production frontend.
- The Node.js backend running as a systemd service on port 3001.
- Nginx forwarding
/apirequests to the backend. - Systems Manager Session Manager for administrative access.
- IAM permissions for retrieving the required secret and accessing AQI data.
The recorded Terraform validation and planning process was used to review the infrastructure before deployment. The final deployed configuration should always be confirmed against the actual AWS resource state.
6. Errors We Encountered and How We Resolved Them
Debugging was an important part of this project. These issues taught us to investigate configuration, permissions, and cloud service behavior instead of assuming that every failure came from the application code.
Error 1: DynamoDB Resource Not Found
Problem: Lambda returned a
ResourceNotFoundException while attempting to access the DynamoDB table.Cause: The DynamoDB table and Lambda function were initially configured in different AWS regions.
Resolution: We aligned the relevant resource configuration to
us-east-1 and retried the grid-seeding operation.Result: The seeding operation subsequently succeeded and created 625 cells.
Lesson learned: AWS services are regional. Always verify the region used by the console, AWS CLI, Lambda configuration, and application code.
Error 2: Lambda Timeout During Refresh
Problem: An initial refresh test failed with a
Sandbox.Timedout error.Resolution: We investigated the execution and configuration, then repeated the refresh test after addressing the issues.
Result: A later refresh response reported that 625 cells had been updated successfully.
Lesson learned: Inspect execution logs, timeout configuration, and downstream service calls when a serverless function does not complete as expected.
Error 3: Frontend API Configuration
Problem: Frontend API requests needed to work in both development and production environments.
Resolution: We reviewed the environment variables and API configuration, then prepared
/api as the base path for the Nginx reverse-proxy architecture.Lesson learned: Vite embeds frontend environment values during the build process. Production configuration changes may require rebuilding the frontend before deployment.
Error 4: Database Authentication During Earlier Development
Problem: An earlier development test returned
MongoServerError: bad auth: Authentication failed.Investigation: We identified authentication and connection configuration as areas to verify.
Lesson learned: Check credentials, connection strings, database-user permissions, and network access before assuming the application logic is at fault.
This was an earlier development issue. The AQI storage design described here uses DynamoDB rather than MongoDB.
Error 5: Protecting the Gemini API Key
Problem: The backend needed access to an external AI API credential without exposing it in source code.
Resolution: We configured the key as a SecureString parameter in AWS Systems Manager Parameter Store and designed the application role to retrieve it through IAM permissions.
Lesson learned: Credentials should be managed separately from application code, and secret values must never be committed to Git or exposed in logs.
Error 6: Avoiding Unintended Infrastructure Changes
Problem: We needed to prepare the EC2 deployment without accidentally modifying or destroying existing AWS resources.
Resolution: We used Terraform formatting, validation, and planning before applying infrastructure changes.
The latest recorded pre-deployment plan showed seven resources to add, zero to change, and zero to destroy. That result represented a proposed change set, not proof that all seven resources had been created.
Lesson learned: Always inspect the current Terraform plan and confirm the resulting infrastructure state before declaring a deployment successful.
7. Deployment and Application Access
Application address provided for the project:
GitHub repository:
The intended application architecture uses Nginx to serve the frontend and forward API requests to the Node.js backend.
For this architecture, the expected endpoints include:
/api/healthfor backend health verification./api/aqi?region=delhifor the Delhi demonstration grid.
The endpoints must be tested against the actual running deployment before their availability is claimed.
One networking detail is worth noting:
100.55.15.141 belongs to the shared IPv4 address range 100.64.0.0/10, which is not globally routable on the public internet. If this address does not work from an external network, the actual EC2 Public IPv4 address or a configured public domain should be used instead.A stable public deployment should also use an appropriate HTTPS configuration.
8. Supporting Different Locations
BreatheRoute is intended to support location-aware environmental analysis rather than being limited to Delhi.
The initial Delhi grid was useful for validating the storage and retrieval workflow, but broader geographical coverage requires appropriate data for each requested location.
The application must distinguish among:
- AQI values retrieved from a configured data source.
- Demonstration or simulated estimates.
- AI-generated explanations and recommendations.
A location appearing on a map does not mean that verified AQI observations are available for that location. Similarly, refreshing a stored value does not establish that it is current or measured.
Future versions should integrate trusted AQI providers, apply geographical filtering, display source information, and show when the underlying data was last updated.
9. Security and Operational Considerations
Security was considered during deployment preparation.
The Gemini API key is stored separately in Parameter Store. The planned EC2 role uses IAM permissions to retrieve the required secret and access the AQI table.
The hosting design also uses Session Manager for administrative access rather than requiring public SSH access.
Before broader production use, the platform should be reviewed for:
- HTTPS and certificate configuration.
- Least-privilege IAM policies.
- Secure handling of API keys.
- Log redaction and monitoring.
- Dependency updates and vulnerability checks.
- Backup and recovery requirements.
- AWS cost monitoring.
A successful demonstration is not automatically a production-ready system. These controls are important parts of operating a cloud application responsibly.
10. What We Learned
Building BreatheRoute provided practical experience with:
- Developing a React-based frontend and Node.js backend.
- Integrating AWS Lambda with API Gateway.
- Storing geographical data in DynamoDB.
- Automating updates through EventBridge.
- Debugging regional configuration errors and Lambda timeouts.
- Integrating Google Gemini into backend application logic.
- Managing API credentials using Systems Manager Parameter Store.
- Preparing infrastructure with Terraform.
- Configuring a reverse proxy for frontend and backend communication.
- Distinguishing simulated environmental data from verified measurements.
One of our biggest lessons was that cloud development is an iterative process. A system becomes reliable through testing, troubleshooting, secure configuration, and validation—not simply by connecting services together.
11. Future Improvements
The next areas of improvement include:
- Integrating trusted AQI data sources for broader geographical coverage.
- Displaying source information and data freshness.
- Improving route comparisons with verified environmental measurements.
- Monitoring scheduled refresh operations and failures.
- Completing and validating the public hosting configuration.
- Adding HTTPS and a stable domain name.
- Expanding automated tests for the frontend, backend, and AWS integrations.
- Evaluating AI recommendations against reliable environmental data.
Conclusion
BreatheRoute demonstrates how AWS services, infrastructure as code, and AI-assisted analysis can be combined to explore environmentally aware route planning.
The project involved building the application, configuring cloud services, creating and retrieving AQI grid data, integrating Gemini, resolving configuration and timeout errors, and preparing the hosting architecture.
Beyond the features themselves, the experience reinforced three important principles: cloud resources must be configured consistently, credentials must be handled securely, and environmental recommendations must be transparent about their data sources.
BreatheRoute is a foundation for further development toward a location-aware environmental platform.
Explore the source code: https://github.com/Universal-codeweb/BreatheRoute
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article