# akshithkheeran-design/urban-air-quality-assistant2026 architecture

> Architecture diagram of the GitHub repository akshithkheeran-design/urban-air-quality-assistant2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshithkheeran-design/urban-air-quality-assistant2026
- Repository: https://github.com/akshithkheeran-design/urban-air-quality-assistant2026

## Overview

AURA is a family and community smog-defense web application. A user enters through the shared application shell, selects a capability, and receives household guidance, neighborhood intelligence, alerts, forecasts, or community-ledger actions. Its domain stages include routine planning, indoor-air interventions, clean alternatives, hazard reporting, and impact tracking; the GenAI assistant adds specialized-agent responses and consensus. The sampled files establish shell routing, shared state composition, routine generation, agent orchestration, and ledger integrity. Other page capabilities are documented in the README; their internal wiring is not inferred here.

Main entry points: [`src/App.jsx`](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/App.jsx) (Application Shell), [`src/services/aiService.js`](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/aiService.js) (AI Service), [`src/hooks/useCitizenLedgerState.js`](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/hooks/useCitizenLedgerState.js) (Ledger State), [`src/context/AppContext.jsx`](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/context/AppContext.jsx) (Shared App State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application Shell"]
  node_shell["Application Shell<br/>[App.jsx]"]
  node_nav["Navigation Metadata<br/>[navigation.js]"]
  node_state["Shared App State<br/>[AppContext.jsx]"]
end

subgraph group_guidance["Household Guidance"]
  node_household["Command Center<br/>[CommandCenter.jsx]"]
  node_routines["Daily Routines<br/>[DailyRoutines.jsx]"]
  node_routine_engine["Routine Engine<br/>[routineEngine.js]"]
  node_indoor["Indoor Air Hacks<br/>[IndoorAirHacks.jsx]"]
  node_alternatives["Clean Alternatives"]
  node_impact["Impact Calculator"]
end

subgraph group_situational["Air Intelligence"]
  node_map["Neighborhood Map<br/>[ThreatMap.jsx]"]
  node_alerts["Family Alerts<br/>[AlertCenter.jsx]"]
  node_forecast["30-Day Outlook<br/>[Forecast.jsx]"]
  node_air_data["Air &amp; Domain Data<br/>[wards.js]"]
end

subgraph group_community["Community &amp; Trust"]
  node_reports["Community Watch<br/>[CitizenReports.jsx]"]
  node_ledger_state["Ledger State"]
  node_crypto["Ledger Cryptography<br/>[crypto.js]"]
  node_audit["Impact Ledger<br/>[AuditTrail.jsx]"]
end

subgraph group_genai["Agent Intelligence"]
  node_agent_page["GenAI Assistant<br/>[AgentSystem.jsx]"]
  node_orchestration["Agent Orchestration"]
  node_ai_service["AI Service<br/>[aiService.js]"]
  node_proxy["Gemini Proxy<br/>[gemini.js]"]
  node_api_proxy["Gemini API Proxy<br/>[gemini.js]"]
  node_sanitize["Input Sanitization<br/>[sanitize.js]"]
end

node_resident(("Resident"))

node_resident -->|"uses"| node_shell
node_shell -->|"reads state"| node_state
node_shell -->|"routes pages"| node_nav
node_shell -->|"dispatches"| node_household
node_shell -->|"dispatches"| node_routines
node_shell -->|"dispatches"| node_indoor
node_shell -->|"dispatches"| node_alternatives
node_shell -->|"dispatches"| node_map
node_shell -->|"dispatches"| node_alerts
node_shell -->|"dispatches"| node_forecast
node_shell -->|"dispatches"| node_reports
node_shell -->|"dispatches"| node_audit
node_shell -->|"dispatches"| node_agent_page
node_state -->|"composes"| node_ledger_state
node_routines -->|"uses"| node_routine_engine
node_alternatives -.->|"calculates impact"| node_impact
node_reports -.->|"records reports"| node_ledger_state
node_ledger_state -->|"verifies hashes"| node_crypto
node_orchestration -->|"orchestrates"| node_ai_service
node_ai_service -->|"sanitizes input"| node_sanitize
node_ai_service -->|"requests inference"| node_proxy
node_ai_service -.->|"requests inference"| node_api_proxy
node_agent_page -.->|"runs agents"| node_orchestration

click node_shell "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/App.jsx"
click node_nav "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/constants/navigation.js"
click node_state "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/context/AppContext.jsx"
click node_household "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/CommandCenter.jsx"
click node_routines "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/DailyRoutines.jsx"
click node_routine_engine "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/routineEngine.js"
click node_indoor "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/IndoorAirHacks.jsx"
click node_alternatives "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/SustainableAlternatives.jsx"
click node_impact "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/impactCalculator.js"
click node_map "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/ThreatMap.jsx"
click node_alerts "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/AlertCenter.jsx"
click node_forecast "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/Forecast.jsx"
click node_air_data "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/data/wards.js"
click node_reports "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/CitizenReports.jsx"
click node_ledger_state "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/hooks/useCitizenLedgerState.js"
click node_crypto "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/utils/crypto.js"
click node_audit "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/AuditTrail.jsx"
click node_agent_page "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/AgentSystem.jsx"
click node_orchestration "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/hooks/useAgentOrchestration.js"
click node_ai_service "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/aiService.js"
click node_proxy "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/netlify/functions/gemini.js"
click node_api_proxy "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/api/gemini.js"
click node_sanitize "https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/utils/sanitize.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_shell,node_nav,node_state toneBlue
class node_household,node_routines,node_routine_engine,node_indoor,node_alternatives,node_impact toneAmber
class node_map,node_alerts,node_forecast,node_air_data toneMint
class node_reports,node_ledger_state,node_crypto,node_audit toneRose
class node_agent_page,node_orchestration,node_ai_service,node_proxy,node_api_proxy,node_sanitize,node_resident toneIndigo
```

## Components

### Application Shell

- [Application Shell](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/App.jsx): `src/App.jsx`
- [Navigation Metadata](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/constants/navigation.js): `src/constants/navigation.js`
- [Shared App State](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/context/AppContext.jsx): `src/context/AppContext.jsx`

### Household Guidance

- [Command Center](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/CommandCenter.jsx): `src/pages/CommandCenter.jsx`
- [Daily Routines](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/DailyRoutines.jsx): `src/pages/DailyRoutines.jsx`
- [Routine Engine](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/routineEngine.js): `src/services/routineEngine.js`
- [Indoor Air Hacks](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/IndoorAirHacks.jsx): `src/pages/IndoorAirHacks.jsx`
- [Clean Alternatives](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/SustainableAlternatives.jsx): `src/pages/SustainableAlternatives.jsx`
- [Impact Calculator](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/impactCalculator.js): `src/services/impactCalculator.js`

### Air Intelligence

- [Neighborhood Map](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/ThreatMap.jsx): `src/pages/ThreatMap.jsx`
- [Family Alerts](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/AlertCenter.jsx): `src/pages/AlertCenter.jsx`
- [30-Day Outlook](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/Forecast.jsx): `src/pages/Forecast.jsx`
- [Air & Domain Data](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/data/wards.js): `src/data/wards.js`

### Community & Trust

- [Community Watch](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/CitizenReports.jsx): `src/pages/CitizenReports.jsx`
- [Ledger State](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/hooks/useCitizenLedgerState.js): `src/hooks/useCitizenLedgerState.js`
- [Ledger Cryptography](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/utils/crypto.js): `src/utils/crypto.js`
- [Impact Ledger](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/AuditTrail.jsx): `src/pages/AuditTrail.jsx`

### Agent Intelligence

- [GenAI Assistant](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/pages/AgentSystem.jsx): `src/pages/AgentSystem.jsx`
- [Agent Orchestration](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/hooks/useAgentOrchestration.js): `src/hooks/useAgentOrchestration.js`
- [AI Service](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/services/aiService.js): `src/services/aiService.js`
- [Gemini Proxy](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/netlify/functions/gemini.js): `netlify/functions/gemini.js`
- [Gemini API Proxy](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/api/gemini.js): `api/gemini.js`
- [Input Sanitization](https://github.com/akshithkheeran-design/urban-air-quality-assistant2026/blob/main/src/utils/sanitize.js): `src/utils/sanitize.js`

### Other components

- **Resident**

## Connections

- Resident → Application Shell: uses (evidence: `src/App.jsx`)
- Application Shell → Shared App State: reads state (evidence: `src/App.jsx`)
- Application Shell → Navigation Metadata: routes pages (evidence: `src/App.jsx`)
- Application Shell → Command Center: dispatches (evidence: `src/App.jsx`)
- Application Shell → Daily Routines: dispatches (evidence: `src/App.jsx`)
- Application Shell → Indoor Air Hacks: dispatches (evidence: `src/App.jsx`)
- Application Shell → Clean Alternatives: dispatches (evidence: `src/App.jsx`)
- Application Shell → Neighborhood Map: dispatches (evidence: `src/App.jsx`)
- Application Shell → Family Alerts: dispatches (evidence: `src/App.jsx`)
- Application Shell → 30-Day Outlook: dispatches (evidence: `src/App.jsx`)
- Application Shell → Community Watch: dispatches (evidence: `src/App.jsx`)
- Application Shell → Impact Ledger: dispatches (evidence: `src/App.jsx`)
- Application Shell → GenAI Assistant: dispatches (evidence: `src/App.jsx`)
- Shared App State → Ledger State: composes (evidence: `src/context/AppContext.jsx`)
- Daily Routines → Routine Engine: uses (evidence: `src/pages/DailyRoutines.jsx`)
- Clean Alternatives → Impact Calculator: calculates impact
- Community Watch → Ledger State: records reports
- Ledger State → Ledger Cryptography: verifies hashes (evidence: `src/hooks/useCitizenLedgerState.js`)
- Agent Orchestration → AI Service: orchestrates (evidence: `src/hooks/useAgentOrchestration.js`)
- AI Service → Input Sanitization: sanitizes input (evidence: `src/services/aiService.js`)
- AI Service → Gemini Proxy: requests inference
- AI Service → Gemini API Proxy: requests inference
- GenAI Assistant → Agent Orchestration: runs agents
