# davfilsdev/aqi-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/davfilsdev/aqi-dashboard
- Repository: https://github.com/davfilsdev/aqi-dashboard

## Overview

AQI Warehouse Dashboard is a public air-quality analytics interface over a Neon/Postgres warehouse. Users filter and explore measurements, inspect overview and specialized visualizations, and export filtered rows; the Ask AI flow turns a question into validated, read-only SQL and returns rows with a summary. The graph reflects the sampled overview, explorer, export, and Ask AI wiring. Other major dashboard pages and chart families are represented from the README and tree; their detailed query wiring was not sampled.

Main entry points: [`app/page.tsx`](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/page.tsx) (Overview page), [`app/explorer/page.tsx`](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/explorer/page.tsx) (Explorer page), [`lib/ai.ts`](https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/ai.ts) (NL-to-SQL service), [`lib/queries.ts`](https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/queries.ts) (Warehouse queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Dashboard UI"]
  node_filterbar["Filter controls<br/>[FilterBar.tsx]"]
  node_charts["Charts and visuals"]
  node_mapview["AQI map<br/>[AqiMap.tsx]"]
  node_chat["Chat interface<br/>[ChatWindow.tsx]"]
end

subgraph group_analytics["Analytics Views"]
  node_overview["Overview page<br/>[page.tsx]"]
  node_trends["Trends page<br/>[page.tsx]"]
  node_cities["Cities pages"]
  node_correlations["Correlation page<br/>[page.tsx]"]
  node_map["Map page<br/>[page.tsx]"]
  node_explorer["Explorer page<br/>[page.tsx]"]
  node_askpage["Ask AI page<br/>[page.tsx]"]
end

subgraph group_server["Server Data Services"]
  node_exportroute["CSV export route<br/>[route.ts]"]
  node_askroute["Ask API route<br/>[route.ts]"]
  node_filters["Filter parsing<br/>[filters.ts]"]
  node_queries["Warehouse queries<br/>[queries.ts]"]
  node_db["DB connection<br/>[db.ts]"]
  node_ai["NL-to-SQL service<br/>[ai.ts]"]
end

subgraph group_integrations["External Systems"]
  node_neon[("Neon Postgres")]
  node_groq["Groq API"]
end

node_user(("Dashboard user"))

node_user -->|"opens dashboard"| node_overview
node_user -->|"opens trends"| node_trends
node_user -->|"browses cities"| node_cities
node_user -->|"views correlations"| node_correlations
node_user -->|"views map"| node_map
node_user -->|"explores records"| node_explorer
node_user -->|"asks question"| node_askpage
node_overview -->|"parses filters"| node_filters
node_overview -->|"loads metrics"| node_queries
node_overview -->|"renders summaries"| node_charts
node_explorer -->|"parses filters"| node_filters
node_explorer -->|"loads rows"| node_queries
node_explorer -->|"renders controls"| node_filterbar
node_trends -->|"renders trends"| node_charts
node_cities -->|"renders city data"| node_charts
node_correlations -->|"renders matrix"| node_charts
node_map -->|"renders map"| node_mapview
node_chat -->|"sends question"| node_askroute
node_askpage -->|"shows conversation"| node_chat
node_askroute -->|"generates and validates SQL"| node_ai
node_askroute -->|"requests summary"| node_ai
node_ai -->|"requests SQL and summary"| node_groq
node_ai -->|"runs validated query"| node_db
node_exportroute -->|"parses filters"| node_filters
node_exportroute -->|"loads export rows"| node_queries
node_queries -->|"executes queries"| node_db
node_db -->|"reads warehouse"| node_neon

click node_overview "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/page.tsx"
click node_trends "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/trends/page.tsx"
click node_cities "https://github.com/davfilsdev/aqi-dashboard/tree/main/app/cities"
click node_correlations "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/correlations/page.tsx"
click node_map "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/map/page.tsx"
click node_explorer "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/explorer/page.tsx"
click node_askpage "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/ask/page.tsx"
click node_filterbar "https://github.com/davfilsdev/aqi-dashboard/blob/main/components/filters/FilterBar.tsx"
click node_charts "https://github.com/davfilsdev/aqi-dashboard/tree/main/components/charts"
click node_mapview "https://github.com/davfilsdev/aqi-dashboard/blob/main/components/map/AqiMap.tsx"
click node_chat "https://github.com/davfilsdev/aqi-dashboard/blob/main/components/chat/ChatWindow.tsx"
click node_exportroute "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/api/export/route.ts"
click node_askroute "https://github.com/davfilsdev/aqi-dashboard/blob/main/app/api/ask/route.ts"
click node_filters "https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/filters.ts"
click node_queries "https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/queries.ts"
click node_db "https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/db.ts"
click node_ai "https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/ai.ts"

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_filterbar,node_charts,node_mapview,node_chat,node_user toneBlue
class node_overview,node_trends,node_cities,node_correlations,node_map,node_explorer,node_askpage toneAmber
class node_exportroute,node_askroute,node_filters,node_queries,node_db,node_ai toneMint
class node_neon,node_groq toneRose
```

## Components

### Dashboard UI

- [Filter controls](https://github.com/davfilsdev/aqi-dashboard/blob/main/components/filters/FilterBar.tsx): `components/filters/FilterBar.tsx`
- [Charts and visuals](https://github.com/davfilsdev/aqi-dashboard/tree/main/components/charts): `components/charts`
- [AQI map](https://github.com/davfilsdev/aqi-dashboard/blob/main/components/map/AqiMap.tsx): `components/map/AqiMap.tsx`
- [Chat interface](https://github.com/davfilsdev/aqi-dashboard/blob/main/components/chat/ChatWindow.tsx): `components/chat/ChatWindow.tsx`

### Analytics Views

- [Overview page](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/page.tsx): `app/page.tsx`
- [Trends page](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/trends/page.tsx): `app/trends/page.tsx`
- [Cities pages](https://github.com/davfilsdev/aqi-dashboard/tree/main/app/cities): `app/cities`
- [Correlation page](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/correlations/page.tsx): `app/correlations/page.tsx`
- [Map page](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/map/page.tsx): `app/map/page.tsx`
- [Explorer page](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/explorer/page.tsx): `app/explorer/page.tsx`
- [Ask AI page](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/ask/page.tsx): `app/ask/page.tsx`

### Server Data Services

- [CSV export route](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/api/export/route.ts): `app/api/export/route.ts`
- [Ask API route](https://github.com/davfilsdev/aqi-dashboard/blob/main/app/api/ask/route.ts): `app/api/ask/route.ts`
- [Filter parsing](https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/filters.ts): `lib/filters.ts`
- [Warehouse queries](https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/queries.ts): `lib/queries.ts`
- [DB connection](https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/db.ts): `lib/db.ts`
- [NL-to-SQL service](https://github.com/davfilsdev/aqi-dashboard/blob/main/lib/ai.ts): `lib/ai.ts`

### External Systems

- **Neon Postgres**
- **Groq API**

### Other components

- **Dashboard user**

## Connections

- Dashboard user → Overview page: opens dashboard
- Dashboard user → Trends page: opens trends
- Dashboard user → Cities pages: browses cities
- Dashboard user → Correlation page: views correlations
- Dashboard user → Map page: views map
- Dashboard user → Explorer page: explores records
- Dashboard user → Ask AI page: asks question
- Overview page → Filter parsing: parses filters
- Overview page → Warehouse queries: loads metrics
- Overview page → Charts and visuals: renders summaries
- Explorer page → Filter parsing: parses filters
- Explorer page → Warehouse queries: loads rows
- Explorer page → Filter controls: renders controls
- Trends page → Charts and visuals: renders trends
- Cities pages → Charts and visuals: renders city data
- Correlation page → Charts and visuals: renders matrix
- Map page → AQI map: renders map
- Chat interface → Ask API route: sends question
- Ask AI page → Chat interface: shows conversation
- Ask API route → NL-to-SQL service: generates and validates SQL
- Ask API route → NL-to-SQL service: requests summary
- NL-to-SQL service → Groq API: requests SQL and summary
- NL-to-SQL service → DB connection: runs validated query
- CSV export route → Filter parsing: parses filters
- CSV export route → Warehouse queries: loads export rows
- Warehouse queries → DB connection: executes queries
- DB connection → Neon Postgres: reads warehouse