# mahmudswe/airawarehub_frontend architecture

> Architecture diagram of the GitHub repository mahmudswe/airawarehub_frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahmudswe/airawarehub_frontend
- Repository: https://github.com/mahmudswe/airawarehub_frontend

## Overview

1. This is a single-page React application built with Vite. The runtime entry points are `src/main.jsx` and `src/App.jsx`, with routing centralized in `src/routes/routes.jsx`. There is no backend code in the repo, so the app appears to consume external APIs through its service layer.

2. The top-level architectural split is by responsibility:
   - `src/pages` contains route-level screens.
   - `src/components` contains reusable UI and feature widgets.
   - `src/services` contains API-facing logic.
   - `src/utils` contains cross-cutting helpers like axios setup, endpoint constants, and AQI color mapping.
   - `src/styles` and CSS files handle presentation.

3. The main user-facing flows seem centered on air-quality and city exploration. The page names suggest major screens for home, search, map viewing, city comparison, and socio-economic factors. `ErrorPage.jsx` is likely the route fallback or failure screen.

4. The map subsystem is isolated under `src/components/Map` with `MapWithRoutes.jsx`, and a corresponding `src/pages/MapView.jsx`. This indicates the map is a dedicated feature boundary rather than just a small widget. `src/services/map.service.js` likely supplies data for routes, locations, or map overlays.

5. The AQI subsystem is also clearly separated under `src/components/aqi`. `AqiCircularProgress.jsx`, `AqiHorizontalBar.jsx`, and `AirQualityDetails.jsx` suggest multiple visualizations for the same air-quality data. `src/utils/aqiColors.util.js` likely standardizes AQI-to-color rendering across the app.

6. Shared UI components in `src/components/shared` support cross-page reuse:
   - `Search.jsx` for querying cities or locations.
   - `CurrentLocation.jsx` for geolocation-driven context.
   - `CityComparisonTable.jsx` for side-by-side metrics.
   - `ToggleSwitch.jsx` for mode or filter toggles.
   - `Toastify.jsx` for user notifications.
   These are likely composed inside the page-level screens rather than owning their own routes.

7. Navigation and layout are handled separately from content. `src/components/nav` contains `navbar.jsx`, `SideNav.jsx`, and `SideNavToggleButton.jsx`, indicating the app uses a persistent nav shell with an expandable side menu. `src/components/loader/loadingOverlay.jsx` suggests an app-wide loading state overlay used during API requests or route transitions.

8. The service boundary is intentionally thin and centralized. `src/services/city.service.js` and `src/services/map.service.js` likely encapsulate request construction and response shaping, while `src/utils/axios.util.js` provides a configured HTTP client and `src/utils/endpoint.util.js` stores API endpoint definitions. This keeps network concerns out of React components.

9. Styling is a mix of utility-driven and custom CSS. The presence of `tailwind.config.js`, `postcss.config.js`, `src/index.css`, `src/App.css`, and `src/styles/styles.css` indicates Tailwind is part of the styling pipeline, with some app-specific overrides or shared styles layered on top.

10. The app is organized as a data-driven UI that likely follows this flow: route selection -> page component -> service call via axios utility -> data formatting/presentation in shared or feature components -> user feedback via loading overlay/toasts. That separation is important for an architecture diagram because it distinguishes navigation, data access, and visualization.

11. The external dependency surface appears to be limited to HTTP APIs and possibly browser geolocation/maps APIs. No state management library or backend integration layer is visible in the tree, so state is probably handled with React component state and props, with route-local orchestration rather than a global store.

12. For diagramming, the key boundaries to show are: routing shell, page-level screens, reusable UI widgets, feature-specific AQI and map modules, and the service/utils layer that mediates all remote data access. That structure is the main architectural shape of the repository.

Main entry points: [`src/App.jsx`](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/App.jsx) (App Shell), [`src/routes/routes.jsx`](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/routes/routes.jsx) (Routes), [`src/services/city.service.js`](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/services/city.service.js) (City Service), [`src/services/map.service.js`](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/services/map.service.js) (Map Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>bootstrap<br/>[main.jsx]"]
  node_app["App Shell<br/>react shell<br/>[App.jsx]"]
  node_routes["Routes<br/>route config<br/>[routes.jsx]"]
end

subgraph group_screens["Screens"]
  node_home["Home<br/>page<br/>[HomePage.jsx]"]
  node_search["Search<br/>page<br/>[SearchPage.jsx]"]
  node_mapview["Map View<br/>page<br/>[MapView.jsx]"]
  node_compare["Compare<br/>page<br/>[CityComparison.jsx]"]
  node_socio["Socioeconomic<br/>page"]
  node_error["Error Page<br/>[ErrorPage.jsx]"]
end

subgraph group_ui["UI Components"]
  node_nav["Nav Shell<br/>layout<br/>[navbar.jsx]"]
  node_sidenav["Side Nav<br/>layout<br/>[SideNav.jsx]"]
  node_sidenavtoggle["Nav Toggle<br/>control"]
  node_loader["Loading Overlay<br/>feedback<br/>[loadingOverlay.jsx]"]
  node_searchcomp["Search Widget<br/>shared widget<br/>[Search.jsx]"]
  node_location["Current Location<br/>shared widget"]
  node_comparison["Comparison Table<br/>shared widget"]
  node_toggle["Toggle Switch<br/>shared control<br/>[ToggleSwitch.jsx]"]
  node_toast["Toastify<br/>notification<br/>[Toastify.jsx]"]
  node_aqi["AQI Module<br/>feature module"]
  node_map["Map Module<br/>feature module"]
end

subgraph group_data["Data Layer"]
  node_aqicolors["AQI Colors<br/>[aqiColors.util.js]"]
  node_axios["Axios Client<br/>http util<br/>[axios.util.js]"]
  node_endpoints["Endpoints<br/>constants<br/>[endpoint.util.js]"]
  node_citysvc["City Service<br/>[city.service.js]"]
  node_mapsvc["Map Service<br/>[map.service.js]"]
end

subgraph group_styles["Styling"]
  node_appcss["App CSS<br/>style<br/>[App.css]"]
  node_globalcss["Global CSS<br/>style<br/>[index.css]"]
  node_sharedcss["Shared Styles<br/>[styles.css]"]
end

node_main -->|"mounts"| node_app
node_app -->|"uses"| node_routes
node_routes -->|"routes to"| node_home
node_routes -->|"routes to"| node_search
node_routes -->|"routes to"| node_mapview
node_routes -->|"routes to"| node_compare
node_routes -->|"routes to"| node_socio
node_routes -.->|"fallback"| node_error
node_app -->|"shell"| node_nav
node_nav -->|"contains"| node_sidenav
node_nav -->|"controls"| node_sidenavtoggle
node_app -.->|"overlays"| node_loader
node_search -->|"uses"| node_searchcomp
node_search -->|"uses"| node_location
node_compare -->|"uses"| node_comparison
node_home -->|"uses"| node_aqi
node_mapview -->|"uses"| node_map
node_aqi -->|"formats"| node_aqicolors
node_aqi -.->|"pairs with"| node_loader
node_map -->|"loads data"| node_mapsvc
node_citysvc -->|"requests via"| node_axios
node_mapsvc -->|"requests via"| node_axios
node_citysvc -->|"targets"| node_endpoints
node_mapsvc -->|"targets"| node_endpoints
node_app -.->|"styles"| node_appcss
node_app -.->|"styles"| node_globalcss
node_app -.->|"styles"| node_sharedcss
node_mapview -->|"fetches"| node_mapsvc
node_home -->|"fetches"| node_citysvc
node_compare -->|"fetches"| node_citysvc

click node_main "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/main.jsx"
click node_app "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/App.jsx"
click node_routes "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/routes/routes.jsx"
click node_home "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/HomePage.jsx"
click node_search "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/SearchPage.jsx"
click node_mapview "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/MapView.jsx"
click node_compare "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/CityComparison.jsx"
click node_socio "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/CountrySocioEconomicFactor.jsx"
click node_error "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/ErrorPage.jsx"
click node_nav "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/nav/navbar.jsx"
click node_sidenav "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/nav/SideNav.jsx"
click node_sidenavtoggle "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/nav/SideNavToggleButton.jsx"
click node_loader "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/loader/loadingOverlay.jsx"
click node_searchcomp "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/Search.jsx"
click node_location "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/CurrentLocation.jsx"
click node_comparison "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/CityComparisonTable.jsx"
click node_toggle "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/ToggleSwitch.jsx"
click node_toast "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/Toastify.jsx"
click node_aqicolors "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/utils/aqiColors.util.js"
click node_axios "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/utils/axios.util.js"
click node_endpoints "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/utils/endpoint.util.js"
click node_citysvc "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/services/city.service.js"
click node_mapsvc "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/services/map.service.js"
click node_appcss "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/App.css"
click node_globalcss "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/index.css"
click node_sharedcss "https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/styles/styles.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_routes toneBlue
class node_home,node_search,node_mapview,node_compare,node_socio,node_error toneAmber
class node_nav,node_sidenav,node_sidenavtoggle,node_loader,node_searchcomp,node_location,node_comparison,node_toggle,node_toast,node_aqi,node_map toneMint
class node_aqicolors,node_axios,node_endpoints,node_citysvc,node_mapsvc toneRose
class node_appcss,node_globalcss,node_sharedcss toneIndigo
```

## Components

### Runtime

App bootstrap and route composition

- [Main](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/main.jsx): bootstrap · Vite entry that mounts the React app · `src/main.jsx`
- [App Shell](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/App.jsx): react shell · Root application component · `src/App.jsx`
- [Routes](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/routes/routes.jsx): route config · Central route definitions and navigation mapping · `src/routes/routes.jsx`

### Screens

Route-level pages

- [Home](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/HomePage.jsx): page · Primary landing screen · `src/pages/HomePage.jsx`
- [Search](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/SearchPage.jsx): page · Search-focused screen for cities or locations · `src/pages/SearchPage.jsx`
- [Map View](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/MapView.jsx): page · Dedicated map exploration screen · `src/pages/MapView.jsx`
- [Compare](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/CityComparison.jsx): page · City comparison screen · `src/pages/CityComparison.jsx`
- [Socioeconomic](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/CountrySocioEconomicFactor.jsx): page · Country-level socioeconomic factors screen · `src/pages/CountrySocioEconomicFactor.jsx`
- [Error Page](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/pages/ErrorPage.jsx): page · Route fallback or failure screen · `src/pages/ErrorPage.jsx`

### UI Components

Reusable layout and feature widgets

- [Nav Shell](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/nav/navbar.jsx): layout · Persistent navigation and side menu · `src/components/nav/navbar.jsx`
- [Side Nav](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/nav/SideNav.jsx): layout · Expandable side navigation panel · `src/components/nav/SideNav.jsx`
- [Nav Toggle](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/nav/SideNavToggleButton.jsx): control · Button for opening and closing the side nav · `src/components/nav/SideNavToggleButton.jsx`
- [Loading Overlay](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/loader/loadingOverlay.jsx): feedback · App-wide loading state overlay · `src/components/loader/loadingOverlay.jsx`
- [Search Widget](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/Search.jsx): shared widget · Reusable search input and query control · `src/components/shared/Search.jsx`
- [Current Location](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/CurrentLocation.jsx): shared widget · Geolocation-driven context component · `src/components/shared/CurrentLocation.jsx`
- [Comparison Table](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/CityComparisonTable.jsx): shared widget · Side-by-side city metric table · `src/components/shared/CityComparisonTable.jsx`
- [Toggle Switch](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/ToggleSwitch.jsx): shared control · Reusable mode or filter toggle · `src/components/shared/ToggleSwitch.jsx`
- [Toastify](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/components/shared/Toastify.jsx): notification · User notification component · `src/components/shared/Toastify.jsx`
- **AQI Module**: feature module · Air-quality presentation components
- **Map Module**: feature module · Map-specific visualization and route rendering

### Data Layer

API access and shared utilities

- [AQI Colors](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/utils/aqiColors.util.js): utility · AQI-to-color mapping helper · `src/utils/aqiColors.util.js`
- [Axios Client](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/utils/axios.util.js): http util · Configured HTTP client for API calls · `src/utils/axios.util.js`
- [Endpoints](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/utils/endpoint.util.js): constants · API endpoint definitions · `src/utils/endpoint.util.js`
- [City Service](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/services/city.service.js): service · City data request and shaping layer · `src/services/city.service.js`
- [Map Service](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/services/map.service.js): service · Map data request and shaping layer · `src/services/map.service.js`

### Styling

Global and app-wide styles

- [App CSS](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/App.css): style · App-level stylesheet · `src/App.css`
- [Global CSS](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/index.css): style · Base stylesheet and global resets · `src/index.css`
- [Shared Styles](https://github.com/mahmudswe/airawarehub_frontend/blob/main/src/styles/styles.css): style · Project-wide custom styles · `src/styles/styles.css`

## Connections

- Main → App Shell: mounts · Bootstraps the root React tree
- App Shell → Routes: uses · Delegates screen selection to route config
- Routes → Home: routes to · Route entry for the landing page
- Routes → Search: routes to · Route entry for search
- Routes → Map View: routes to · Route entry for map exploration
- Routes → Compare: routes to · Route entry for city comparison
- Routes → Socioeconomic: routes to · Route entry for socioeconomic factors
- Routes → Error Page: fallback · Catch-all or failure screen
- App Shell → Nav Shell: shell · Provides persistent navigation chrome
- Nav Shell → Side Nav: contains · Renders the side navigation panel
- Nav Shell → Nav Toggle: controls · Uses toggle button for nav state
- App Shell → Loading Overlay: overlays · Shows global loading feedback during async work
- Search → Search Widget: uses · Search page composes shared search widget
- Search → Current Location: uses · Search page can anchor results to current location
- Compare → Comparison Table: uses · Comparison page renders the shared table
- Home → AQI Module: uses · Landing content likely highlights AQI visuals
- Map View → Map Module: uses · Map page is built around the map module
- AQI Module → AQI Colors: formats · Standardizes AQI color presentation
- AQI Module → Loading Overlay: pairs with · AQI fetch/render flows can show loading state
- Map Module → Map Service: loads data · Map visuals depend on map service data
- City Service → Axios Client: requests via · City service uses shared HTTP client
- Map Service → Axios Client: requests via · Map service uses shared HTTP client
- City Service → Endpoints: targets · City service resolves API routes from constants
- Map Service → Endpoints: targets · Map service resolves API routes from constants
- App Shell → App CSS: styles · App-specific styling
- App Shell → Global CSS: styles · Global base styles
- App Shell → Shared Styles: styles · Shared custom styles
- Map View → Map Service: fetches · Map view likely triggers map data retrieval
- Home → City Service: fetches · Home screen likely pulls city and AQI data
- Compare → City Service: fetches · Comparison screen likely loads city metrics