How rexo77/aqi-to-cigarettes works
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: App.js App · StateManager.js StateManager · SearchComponent.js Search · DataManager.js DataManager
Components 18
Browser Shell
Static entry points, styles, and offline support.
- index.html · Browser page shell that loads the app, styles, and assets.
index.html - styles.css · Primary presentation layer for the static front-end.
styles.css - sw.js · Offline and caching support for the browser app.
sw.js
UI
User-facing search, results, and visualization components.
- Search · City lookup and autocomplete input boundary.
src/components/SearchComponent.js - Results · Textual AQI, cigarette-equivalent, and health summary output.
src/components/ResultsComponent.js - Visualization · Visual presentation for the cigarette-equivalent result.
src/components/VisualizationComponent.js
Core
Shared component, event, and state infrastructure.
- Component · Reusable component abstraction for app UI pieces.
src/core/Component.js - EventBus · Decoupled messaging between modules and components.
src/core/EventBus.js - StateManager · Shared application state for city, AQI, and computed output.
src/core/StateManager.js
Logic
Data access, search, calculation, and rendering modules.
- DataManager · Fetches geocoding and air-quality data from external sources.
src/modules/DataManager.js - SmartSearch · Autocomplete and city disambiguation layer.
src/modules/SmartSearch.js - AQICalculator · Converts AQI or PM2.5 inputs into cigarette-equivalent values.
src/modules/AQICalculator.js - CanvasRenderer · Canvas-based renderer for the visual metaphor output.
src/modules/CanvasRenderer.js
Runtimes
Alternative app bootstraps and worker execution.
- main.js · Modular entry point that starts the main app runtime.
src/main.js - App · Coordinates search, data flow, state updates, and presentation.
src/App.js - simple-app · Alternate or simplified application entry path.
src/simple-app.js - script.js · Top-level script for a non-modular or older runtime path.
script.js - AQI Worker · Background execution for AQI-to-cigarette calculations.
src/workers/aqi-calculator-worker.js
Connections 25
- 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.