# tpatel1208/talking-to-air architecture

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

- Interactive diagram: https://gitdiagram.com/tpatel1208/talking-to-air
- Repository: https://github.com/tpatel1208/talking-to-air

## Overview

Talking to Air is a conversational atmospheric-data application: users ask questions in a React chat, the backend streams a supervisor-routed response, and satellite or EPA ground-sensor workflows produce visualizations and analysis. The product also supports discovery, variable guidance, long-running jobs, exports, provenance, and persistent sessions. The README documents the main routing and product branches; source-index references and excerpts support selected internal links. Several API routes and feature implementations were not sampled, so their internal wiring is not inferred.

Main entry points: [`Backend/tta_backend/services/chat_stream_service.py`](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/chat_stream_service.py) (Chat orchestration), [`Frontend/src/App.jsx`](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/App.jsx) (Application shell), [`Backend/tta_backend/agents/supervisor_agent.py`](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/supervisor_agent.py) (Supervisor agent), [`Backend/tta_backend/tools/satellite_tools/retrieval_tools.py`](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/tools/satellite_tools/retrieval_tools.py) (Satellite tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web_app["Application shell<br/>[App.jsx]"]
  node_chat_ui["Chat interface<br/>[Chat.jsx]"]
  node_chat_hook["Chat and SSE client<br/>[useChat.js]"]
  node_discovery_ui["Discovery client<br/>[useDiscovery.js]"]
  node_jobs_ui["Jobs client<br/>[useJobs.js]"]
  node_output_ui["Results panels<br/>[OutputPanel.jsx]"]
end

subgraph group_conversation["Conversation and routing"]
  node_backend_api["FastAPI backend<br/>[api.py]"]
  node_chat_stream["Chat orchestration"]
  node_supervisor["Supervisor agent"]
  node_satellite_agent["Satellite agent<br/>[earthdata_agent.py]"]
  node_ground_agent["Ground-sensor agent"]
end

subgraph group_data["Data workflows"]
  node_satellite_tools["Satellite tools<br/>[retrieval_tools.py]"]
  node_earthdata_mcp["Earthdata MCP client<br/>[client.py]"]
  node_aggregation["Data aggregation"]
  node_discovery_service["Dataset discovery"]
  node_epa_service["EPA sensor tools<br/>[epa_aqs_tools.py]"]
end

subgraph group_results["Results and persistence"]
  node_plotting["Maps and plots<br/>[plotting.py]"]
  node_exports["Data exports<br/>[export_service.py]"]
  node_session_store[("Session history")]
  node_artifact_store["Artifact storage<br/>[artifact_store.py]"]
end

subgraph group_platform["Runtime infrastructure"]
  node_db[("PostgreSQL<br/>[db.py]")]
  node_settings["Runtime settings<br/>[settings.py]"]
end

node_researcher(("Researcher"))
node_mcp_service{{"Earthdata retrieval MCP"}}
node_epa_api{{"EPA AQS API"}}
node_llm_provider{{"Language-model provider"}}

node_researcher -->|"asks questions"| node_web_app
node_web_app -->|"renders"| node_chat_ui
node_web_app -->|"uses"| node_chat_hook
node_web_app -->|"uses"| node_discovery_ui
node_web_app -->|"uses"| node_jobs_ui
node_web_app -->|"renders"| node_output_ui
node_chat_hook -->|"streams chat"| node_backend_api
node_backend_api -.->|"routes chat"| node_chat_stream
node_chat_stream -->|"routes query"| node_supervisor
node_supervisor -->|"dispatches"| node_satellite_agent
node_supervisor -->|"dispatches"| node_ground_agent
node_satellite_agent -.->|"uses tools"| node_satellite_tools
node_satellite_tools -->|"parses results"| node_earthdata_mcp
node_earthdata_mcp -->|"retrieves data"| node_mcp_service
node_satellite_tools -->|"uses"| node_aggregation
node_ground_agent -->|"queries"| node_epa_service
node_epa_service -->|"requests observations"| node_epa_api
node_chat_stream -.->|"dispatches discovery"| node_discovery_service
node_chat_stream -->|"stores artifacts"| node_artifact_store
node_chat_stream -.->|"creates charts"| node_plotting
node_chat_stream -.->|"persists history"| node_session_store
node_session_store -->|"reads and writes"| node_db
node_artifact_store -.->|"indexes artifacts"| node_db
node_output_ui -->|"requests export"| node_exports
node_chat_stream -->|"runs agents"| node_llm_provider
node_chat_stream -->|"reads settings"| node_settings

click node_web_app "https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/App.jsx"
click node_chat_ui "https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/components/Chat.jsx"
click node_chat_hook "https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/hooks/useChat.js"
click node_discovery_ui "https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/hooks/useDiscovery.js"
click node_jobs_ui "https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/hooks/useJobs.js"
click node_output_ui "https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/components/OutputPanel.jsx"
click node_backend_api "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/api.py"
click node_chat_stream "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/chat_stream_service.py"
click node_supervisor "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/supervisor_agent.py"
click node_satellite_agent "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/earthdata_agent.py"
click node_ground_agent "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/ground_sensor_agent.py"
click node_satellite_tools "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/tools/satellite_tools/retrieval_tools.py"
click node_earthdata_mcp "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/earthdata_mcp/client.py"
click node_aggregation "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/preprocessing/aggregation_service.py"
click node_discovery_service "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/discovery_service.py"
click node_epa_service "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/tools/ground_sensor_tools/epa_aqs_tools.py"
click node_plotting "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/utils/plotting.py"
click node_exports "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/export_service.py"
click node_session_store "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/repositories/session_repository.py"
click node_artifact_store "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/artifact_store.py"
click node_db "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/utils/db.py"
click node_settings "https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/config/settings.py"

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_web_app,node_chat_ui,node_chat_hook,node_discovery_ui,node_jobs_ui,node_output_ui toneBlue
class node_backend_api,node_chat_stream,node_supervisor,node_satellite_agent,node_ground_agent toneAmber
class node_satellite_tools,node_earthdata_mcp,node_aggregation,node_discovery_service,node_epa_service,node_epa_api toneMint
class node_plotting,node_exports,node_session_store,node_artifact_store toneRose
class node_db,node_settings,node_researcher,node_mcp_service,node_llm_provider toneIndigo
```

## Components

### Web application

- [Application shell](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/App.jsx): `Frontend/src/App.jsx`
- [Chat interface](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/components/Chat.jsx): `Frontend/src/components/Chat.jsx`
- [Chat and SSE client](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/hooks/useChat.js): `Frontend/src/hooks/useChat.js`
- [Discovery client](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/hooks/useDiscovery.js): `Frontend/src/hooks/useDiscovery.js`
- [Jobs client](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/hooks/useJobs.js): `Frontend/src/hooks/useJobs.js`
- [Results panels](https://github.com/tpatel1208/talking-to-air/blob/main/Frontend/src/components/OutputPanel.jsx): `Frontend/src/components/OutputPanel.jsx`

### Conversation and routing

- [FastAPI backend](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/api.py): `Backend/tta_backend/api.py`
- [Chat orchestration](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/chat_stream_service.py): `Backend/tta_backend/services/chat_stream_service.py`
- [Supervisor agent](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/supervisor_agent.py): `Backend/tta_backend/agents/supervisor_agent.py`
- [Satellite agent](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/earthdata_agent.py): `Backend/tta_backend/agents/earthdata_agent.py`
- [Ground-sensor agent](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/agents/ground_sensor_agent.py): `Backend/tta_backend/agents/ground_sensor_agent.py`

### Data workflows

- [Satellite tools](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/tools/satellite_tools/retrieval_tools.py): `Backend/tta_backend/tools/satellite_tools/retrieval_tools.py`
- [Earthdata MCP client](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/earthdata_mcp/client.py): `Backend/tta_backend/earthdata_mcp/client.py`
- [Data aggregation](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/preprocessing/aggregation_service.py): `Backend/tta_backend/preprocessing/aggregation_service.py`
- [Dataset discovery](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/discovery_service.py): `Backend/tta_backend/services/discovery_service.py`
- [EPA sensor tools](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/tools/ground_sensor_tools/epa_aqs_tools.py): `Backend/tta_backend/tools/ground_sensor_tools/epa_aqs_tools.py`

### Results and persistence

- [Maps and plots](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/utils/plotting.py): `Backend/tta_backend/utils/plotting.py`
- [Data exports](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/export_service.py): `Backend/tta_backend/services/export_service.py`
- [Session history](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/repositories/session_repository.py): `Backend/tta_backend/repositories/session_repository.py`
- [Artifact storage](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/services/artifact_store.py): `Backend/tta_backend/services/artifact_store.py`

### Runtime infrastructure

- [PostgreSQL](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/utils/db.py): `Backend/tta_backend/utils/db.py`
- [Runtime settings](https://github.com/tpatel1208/talking-to-air/blob/main/Backend/tta_backend/config/settings.py): `Backend/tta_backend/config/settings.py`

### Other components

- **Researcher**
- **Earthdata retrieval MCP**
- **EPA AQS API**
- **Language-model provider**

## Connections

- Researcher → Application shell: asks questions (evidence: `README.md`)
- Application shell → Chat interface: renders (evidence: `Frontend/src/App.jsx`)
- Application shell → Chat and SSE client: uses (evidence: `Frontend/src/App.jsx`)
- Application shell → Discovery client: uses (evidence: `Frontend/src/App.jsx`)
- Application shell → Jobs client: uses (evidence: `Frontend/src/App.jsx`)
- Application shell → Results panels: renders (evidence: `Frontend/src/App.jsx`)
- Chat and SSE client → FastAPI backend: streams chat (evidence: `README.md`)
- FastAPI backend → Chat orchestration: routes chat
- Chat orchestration → Supervisor agent: routes query (evidence: `README.md`)
- Supervisor agent → Satellite agent: dispatches (evidence: `README.md`)
- Supervisor agent → Ground-sensor agent: dispatches (evidence: `README.md`)
- Satellite agent → Satellite tools: uses tools
- Satellite tools → Earthdata MCP client: parses results (evidence: `Backend/tta_backend/tools/satellite_tools/retrieval_tools.py`)
- Earthdata MCP client → Earthdata retrieval MCP: retrieves data (evidence: `README.md`)
- Satellite tools → Data aggregation: uses (evidence: `Backend/tta_backend/tools/satellite_tools/retrieval_tools.py`)
- Ground-sensor agent → EPA sensor tools: queries (evidence: `README.md`)
- EPA sensor tools → EPA AQS API: requests observations (evidence: `README.md`)
- Chat orchestration → Dataset discovery: dispatches discovery
- Chat orchestration → Artifact storage: stores artifacts (evidence: `Backend/tta_backend/services/chat_stream_service.py`)
- Chat orchestration → Maps and plots: creates charts
- Chat orchestration → Session history: persists history
- Session history → PostgreSQL: reads and writes (evidence: `Backend/tta_backend/repositories/session_repository.py`)
- Artifact storage → PostgreSQL: indexes artifacts
- Results panels → Data exports: requests export (evidence: `README.md`)
- Chat orchestration → Language-model provider: runs agents (evidence: `README.md`)
- Chat orchestration → Runtime settings: reads settings (evidence: `Backend/tta_backend/services/chat_stream_service.py`)