# rexo77/aqi-to-cigarettes architecture

> Architecture diagram of the GitHub repository rexo77/aqi-to-cigarettes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rexo77/aqi-to-cigarettes
- Repository: https://github.com/rexo77/aqi-to-cigarettes

## Overview

1. **Overall shape**
   - This is a **client-side AQI calculator** that runs entirely in the browser.
   - The app’s purpose is to turn a city’s air-quality data into a more relatable output: **“equivalent cigarettes smoked per day.”**

2. **Browser entry and hosting**
   - `index.html` is the page shell that loads the app, styles, and static assets.
   - The repository is structured like a **static front-end app** rather than a server-backed system; deployment is likely a static host such as GitHub Pages.

3. **Primary UI layer**
   - The UI is split into three main components under `src/components/`:
     - `SearchComponent` for city lookup and autocomplete
     - `ResultsComponent` for AQI, cigarette-equivalent, and health summary output
     - `VisualizationComponent` for the visual representation of the cigarette-equivalent result
   - These are the user-facing boundaries where input is captured and results are rendered.

4. **Application composition**
   - `src/App.js` is the likely orchestration layer that wires the components together.
   - `src/main.js` appears to be the bootstrap entry point for the modular version of the app.
   - There is also `src/simple-app.js` and a top-level `script.js`, which suggests the repo contains either an older simplified entry or an alternate runtime path alongside the modular `src/` architecture.

5. **Core application framework**
   - The `src/core/` folder provides reusable infrastructure:
     - `Component.js` likely defines a base component abstraction
     - `EventBus.js` handles decoupled communication between modules/components
     - `StateManager.js` centralizes shared app state
   - This creates a **unidirectional-ish flow** where user actions update state, and state changes notify interested parts of the UI.

6. **Data and external API boundary**
   - `src/modules/DataManager.js` is the boundary between the app and external data sources.
   - The README shows the app depends on **OpenWeatherMap Geocoding API** and **Air Pollution API**.
   - Data flow is typically:
     - user searches for a city
     - geocoding resolves the location
     - air-quality data is fetched for that location
     - the result is fed back into the app state and views

7. **Search and disambiguation subsystem**
   - `src/modules/SmartSearch.js` likely powers real-time autocomplete and city disambiguation.
   - This sits between the raw user input and the geocoding lookup, helping the app handle global city names and multiple matches cleanly.
   - In an architecture diagram, this is the “search intelligence” layer before network fetches happen.

8. **AQI computation boundary**
   - `src/modules/AQICalculator.js` converts AQI/PM2.5 inputs into cigarette-equivalent values and related health interpretation.
   - The presence of `src/workers/aqi-calculator-worker.js` shows this calculation can be offloaded to a **Web Worker**, keeping heavier processing off the main UI thread.
   - That worker boundary is important for responsiveness when calculations or transformations become expensive.

9. **Visualization/rendering subsystem**
   - `src/modules/CanvasRenderer.js` and `VisualizationComponent` indicate a canvas-based visual output rather than only DOM text.
   - The renderer is the final presentation layer for the “cigarettes” metaphor, likely translating computed values into animations, icons, or progress-style graphics.
   - This is separate from the textual results so the diagram should show a dedicated rendering path.

10. **State and event flow**
   - The architecture is centered on shared state plus events:
     - input changes originate in `SearchComponent`
     - `EventBus` propagates actions
     - `StateManager` stores the current city, AQI data, units/theme preferences, and computed output
     - `ResultsComponent` and `VisualizationComponent` re-render from state updates
   - This reduces direct coupling between search, fetch, computation, and rendering.

11. **Offline and lifecycle support**
   - `sw.js` indicates a **service worker** is used for offline or cached behavior.
   - Combined with the README’s mention of offline functionality for previously searched cities, the app has a persistence/cache boundary beyond the live API calls.
   - That means the browser can reuse prior assets or results when network access is limited.

12. **Static assets and presentation**
   - `styles.css`, `favicon/`, and `favicon/site.webmanifest` handle the visual shell and PWA-like polish.
   - The README mentions theme switching and responsive behavior, so styling is a significant part of the user experience but remains separate from the data and computation pipeline.

13. **End-to-end data path**
   - The main runtime path is:
     - user enters a city in the search UI
     - smart search suggests and resolves a location
     - data manager fetches AQI/air-pollution data from OpenWeatherMap
     - AQI calculator computes cigarette-equivalent output, possibly in a worker
     - state manager stores the result
     - results and visualization components render the updated output
   - This is the core flow to capture in any architecture diagram.

14. **Important architectural boundary summary**
   - The repo cleanly separates **UI**, **state/event coordination**, **data access**, **calculation**, **visualization**, and **offline support**.
   - The main external dependency is OpenWeatherMap; everything else runs in-browser with no backend service in the tree.

Main entry points: [`src/App.js`](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/App.js) (App), [`src/core/StateManager.js`](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/StateManager.js) (StateManager), [`src/components/SearchComponent.js`](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/SearchComponent.js) (Search), [`src/modules/DataManager.js`](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/DataManager.js) (DataManager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Browser Shell"]
  node_index["index.html<br/>shell page<br/>[index.html]"]
  node_styles["styles.css<br/>style sheet<br/>[styles.css]"]
  node_sw["sw.js<br/>service worker<br/>[sw.js]"]
end

subgraph group_ui["UI"]
  node_search["Search<br/>ui component<br/>[SearchComponent.js]"]
  node_results["Results<br/>ui component"]
  node_viz["Visualization<br/>ui component"]
end

subgraph group_core["Core"]
  node_base["Component<br/>base class<br/>[Component.js]"]
  node_bus["EventBus<br/>event hub<br/>[EventBus.js]"]
  node_state["StateManager<br/>state store<br/>[StateManager.js]"]
end

subgraph group_logic["Logic"]
  node_data["DataManager<br/>api boundary<br/>[DataManager.js]"]
  node_smart["SmartSearch<br/>search logic<br/>[SmartSearch.js]"]
  node_calc["AQICalculator<br/>[AQICalculator.js]"]
  node_canvas["CanvasRenderer<br/>[CanvasRenderer.js]"]
end

subgraph group_runtime["Runtimes"]
  node_main["main.js<br/>bootstrap<br/>[main.js]"]
  node_app["App<br/>orchestrator<br/>[App.js]"]
  node_simple["simple-app<br/>alt runtime<br/>[simple-app.js]"]
  node_legacy["script.js<br/>legacy entry<br/>[script.js]"]
  node_worker{{"AQI Worker<br/>web worker"}}
end

node_index -->|"loads"| node_main
node_index -->|"styles"| node_styles
node_index -->|"registers"| node_sw
node_main -->|"bootstraps"| node_app
node_legacy -->|"uses"| node_simple
node_app -->|"composes"| node_search
node_app -->|"composes"| node_results
node_app -->|"composes"| node_viz
node_app -->|"coordinates"| node_data
node_app -->|"owns"| node_state
node_app -->|"signals"| node_bus
node_search -->|"suggests"| node_smart
node_search -->|"publishes"| node_bus
node_smart -->|"resolves"| node_data
node_data -->|"updates"| node_state
node_data -->|"feeds"| node_calc
node_calc -->|"offloads"| node_worker
node_worker -->|"returns"| node_state
node_state -->|"renders"| node_results
node_state -->|"renders"| node_viz
node_viz -->|"draws"| node_canvas
node_base -->|"extends"| node_search
node_base -->|"extends"| node_results
node_base -->|"extends"| node_viz
node_bus -->|"notifies"| node_state

click node_index "https://github.com/rexo77/aqi-to-cigarettes/blob/main/index.html"
click node_styles "https://github.com/rexo77/aqi-to-cigarettes/blob/main/styles.css"
click node_sw "https://github.com/rexo77/aqi-to-cigarettes/blob/main/sw.js"
click node_main "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/main.js"
click node_app "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/App.js"
click node_simple "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/simple-app.js"
click node_legacy "https://github.com/rexo77/aqi-to-cigarettes/blob/main/script.js"
click node_base "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/Component.js"
click node_bus "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/EventBus.js"
click node_state "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/StateManager.js"
click node_search "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/SearchComponent.js"
click node_results "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/ResultsComponent.js"
click node_viz "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/VisualizationComponent.js"
click node_data "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/DataManager.js"
click node_smart "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/SmartSearch.js"
click node_calc "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/AQICalculator.js"
click node_canvas "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/CanvasRenderer.js"
click node_worker "https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/workers/aqi-calculator-worker.js"

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_index,node_styles,node_sw toneBlue
class node_search,node_results,node_viz toneAmber
class node_base,node_bus,node_state toneMint
class node_data,node_smart,node_calc,node_canvas toneRose
class node_main,node_app,node_simple,node_legacy,node_worker toneIndigo
```

## Components

### Browser Shell

Static entry points, styles, and offline support.

- [index.html](https://github.com/rexo77/aqi-to-cigarettes/blob/main/index.html): shell page · Browser page shell that loads the app, styles, and assets. · `index.html`
- [styles.css](https://github.com/rexo77/aqi-to-cigarettes/blob/main/styles.css): style sheet · Primary presentation layer for the static front-end. · `styles.css`
- [sw.js](https://github.com/rexo77/aqi-to-cigarettes/blob/main/sw.js): service worker · Offline and caching support for the browser app. · `sw.js`

### UI

User-facing search, results, and visualization components.

- [Search](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/SearchComponent.js): ui component · City lookup and autocomplete input boundary. · `src/components/SearchComponent.js`
- [Results](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/ResultsComponent.js): ui component · Textual AQI, cigarette-equivalent, and health summary output. · `src/components/ResultsComponent.js`
- [Visualization](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/components/VisualizationComponent.js): ui component · Visual presentation for the cigarette-equivalent result. · `src/components/VisualizationComponent.js`

### Core

Shared component, event, and state infrastructure.

- [Component](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/Component.js): base class · Reusable component abstraction for app UI pieces. · `src/core/Component.js`
- [EventBus](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/EventBus.js): event hub · Decoupled messaging between modules and components. · `src/core/EventBus.js`
- [StateManager](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/core/StateManager.js): state store · Shared application state for city, AQI, and computed output. · `src/core/StateManager.js`

### Logic

Data access, search, calculation, and rendering modules.

- [DataManager](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/DataManager.js): api boundary · Fetches geocoding and air-quality data from external sources. · `src/modules/DataManager.js`
- [SmartSearch](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/SmartSearch.js): search logic · Autocomplete and city disambiguation layer. · `src/modules/SmartSearch.js`
- [AQICalculator](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/AQICalculator.js): calculator · Converts AQI or PM2.5 inputs into cigarette-equivalent values. · `src/modules/AQICalculator.js`
- [CanvasRenderer](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/modules/CanvasRenderer.js): renderer · Canvas-based renderer for the visual metaphor output. · `src/modules/CanvasRenderer.js`

### Runtimes

Alternative app bootstraps and worker execution.

- [main.js](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/main.js): bootstrap · Modular entry point that starts the main app runtime. · `src/main.js`
- [App](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/App.js): orchestrator · Coordinates search, data flow, state updates, and presentation. · `src/App.js`
- [simple-app](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/simple-app.js): alt runtime · Alternate or simplified application entry path. · `src/simple-app.js`
- [script.js](https://github.com/rexo77/aqi-to-cigarettes/blob/main/script.js): legacy entry · Top-level script for a non-modular or older runtime path. · `script.js`
- [AQI Worker](https://github.com/rexo77/aqi-to-cigarettes/blob/main/src/workers/aqi-calculator-worker.js): web worker · Background execution for AQI-to-cigarette calculations. · `src/workers/aqi-calculator-worker.js`

## Connections

- index.html → main.js: loads · Browser shell loads the modular app entry.
- index.html → styles.css: styles · Page shell includes the primary stylesheet.
- index.html → sw.js: registers · Static host can register the service worker for offline support.
- main.js → App: bootstraps · Main entry starts the application orchestrator.
- script.js → simple-app: uses · Legacy script path points at the simplified runtime.
- App → Search: composes · App wires in the search UI boundary.
- App → Results: composes · App wires in the results UI boundary.
- App → Visualization: composes · App wires in the visualization UI boundary.
- App → DataManager: coordinates · App orchestrates data fetching and downstream updates.
- App → StateManager: owns · App relies on shared state for coordination.
- App → EventBus: signals · App uses the event bus for decoupled communication.
- Search → SmartSearch: suggests · Search component uses smart search for autocomplete and disambiguation.
- Search → EventBus: publishes · User input events are emitted through the event bus.
- SmartSearch → DataManager: resolves · Search logic feeds resolved location queries into data access.
- DataManager → StateManager: updates · Fetched geocoding and air-quality data are stored in shared state.
- DataManager → AQICalculator: feeds · Air-quality data is passed into the AQI conversion layer.
- AQICalculator → AQI Worker: offloads · Heavy calculation can run in a web worker.
- AQI Worker → StateManager: returns · Worker results are committed back into application state.
- StateManager → Results: renders · Results component reacts to state changes.
- StateManager → Visualization: renders · Visualization component reacts to state changes.
- Visualization → CanvasRenderer: draws · Visualization delegates graphical output to the canvas renderer.
- Component → Search: extends · Search component builds on the shared component abstraction.
- Component → Results: extends · Results component builds on the shared component abstraction.
- Component → Visualization: extends · Visualization component builds on the shared component abstraction.
- EventBus → StateManager: notifies · State changes are propagated through events.
