# adeeb144/weathergpt architecture

> Architecture diagram of the GitHub repository adeeb144/weathergpt, 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/adeeb144/weathergpt
- Repository: https://github.com/adeeb144/weathergpt

## Overview

WeatherGPT is a Flutter weather assistant backed by a FastAPI service. Users can ask conversational weather questions by text or voice, view severe alerts, and explore historical climate trends; location and language support enhance those flows. The graph follows documented capabilities and the sampled backend routes. Flutter-to-provider/service wiring and the internal details of the AI agent and weather tools were not sampled, so those links reflect documented responsibilities and omit uncertain internal calls.

Main entry points: [`backend/main.py`](https://github.com/adeeb144/weathergpt/blob/main/backend/main.py) (FastAPI routes), [`app/lib/services/api_service.dart`](https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/api_service.dart) (API service), [`app/lib/screens/chat_screen.dart`](https://github.com/adeeb144/weathergpt/blob/main/app/lib/screens/chat_screen.dart) (Chat screen), [`app/lib/providers/chat_provider.dart`](https://github.com/adeeb144/weathergpt/blob/main/app/lib/providers/chat_provider.dart) (Chat state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter experience"]
  node_chat["Chat screen<br/>[chat_screen.dart]"]
  node_chat_state["Chat state<br/>[chat_provider.dart]"]
  node_message["Message model<br/>[message.dart]"]
  node_api_client["API service<br/>[api_service.dart]"]
  node_voice["Voice service<br/>[voice_service.dart]"]
  node_location["Location service"]
  node_alerts_ui["Alerts screen<br/>[alerts_screen.dart]"]
  node_climate_ui["Climate charts"]
end

subgraph group_server["Weather backend"]
  node_backend_api["FastAPI routes<br/>[main.py]"]
  node_agent["AI agent<br/>[agent.py]"]
  node_weather_tools["Weather tools<br/>[tools.py]"]
end

subgraph group_integrations["External capabilities"]
  node_gemini{{"Google Gemini"}}
  node_open_meteo{{"Open-Meteo"}}
  node_device_speech{{"Device speech"}}
  node_device_location{{"Device location"}}
end

node_user(("User"))

node_user -->|"asks weather"| node_chat
node_user -->|"views alerts"| node_alerts_ui
node_user -->|"views trends"| node_climate_ui
node_chat -->|"updates"| node_chat_state
node_chat_state -->|"uses"| node_message
node_chat_state -->|"sends chat"| node_api_client
node_chat -.->|"uses voice"| node_voice
node_voice -.->|"recognizes and speaks"| node_device_speech
node_location -.->|"gets coordinates"| node_device_location
node_alerts_ui -->|"requests alerts"| node_api_client
node_climate_ui -->|"requests climate"| node_api_client
node_api_client -->|"HTTP requests"| node_backend_api
node_backend_api -->|"runs chat agent"| node_agent
node_agent -->|"AI function calling"| node_gemini
node_agent -->|"uses weather tools"| node_weather_tools
node_backend_api -->|"gets alerts and geocodes"| node_weather_tools
node_backend_api -->|"fetches climate archive"| node_open_meteo
node_weather_tools -->|"fetches weather data"| node_open_meteo

click node_chat "https://github.com/adeeb144/weathergpt/blob/main/app/lib/screens/chat_screen.dart"
click node_chat_state "https://github.com/adeeb144/weathergpt/blob/main/app/lib/providers/chat_provider.dart"
click node_message "https://github.com/adeeb144/weathergpt/blob/main/app/lib/models/message.dart"
click node_api_client "https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/api_service.dart"
click node_voice "https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/voice_service.dart"
click node_location "https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/location_service.dart"
click node_alerts_ui "https://github.com/adeeb144/weathergpt/blob/main/app/lib/screens/alerts_screen.dart"
click node_climate_ui "https://github.com/adeeb144/weathergpt/blob/main/app/lib/widgets/climate_dialog.dart"
click node_backend_api "https://github.com/adeeb144/weathergpt/blob/main/backend/main.py"
click node_agent "https://github.com/adeeb144/weathergpt/blob/main/backend/agent.py"
click node_weather_tools "https://github.com/adeeb144/weathergpt/blob/main/backend/tools.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_chat,node_chat_state,node_message,node_api_client,node_voice,node_location,node_alerts_ui,node_climate_ui,node_user toneBlue
class node_backend_api,node_agent,node_weather_tools toneAmber
class node_gemini,node_open_meteo,node_device_speech,node_device_location toneMint
```

## Components

### Flutter experience

- [Chat screen](https://github.com/adeeb144/weathergpt/blob/main/app/lib/screens/chat_screen.dart): `app/lib/screens/chat_screen.dart`
- [Chat state](https://github.com/adeeb144/weathergpt/blob/main/app/lib/providers/chat_provider.dart): `app/lib/providers/chat_provider.dart`
- [Message model](https://github.com/adeeb144/weathergpt/blob/main/app/lib/models/message.dart): `app/lib/models/message.dart`
- [API service](https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/api_service.dart): `app/lib/services/api_service.dart`
- [Voice service](https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/voice_service.dart): `app/lib/services/voice_service.dart`
- [Location service](https://github.com/adeeb144/weathergpt/blob/main/app/lib/services/location_service.dart): `app/lib/services/location_service.dart`
- [Alerts screen](https://github.com/adeeb144/weathergpt/blob/main/app/lib/screens/alerts_screen.dart): `app/lib/screens/alerts_screen.dart`
- [Climate charts](https://github.com/adeeb144/weathergpt/blob/main/app/lib/widgets/climate_dialog.dart): `app/lib/widgets/climate_dialog.dart`

### Weather backend

- [FastAPI routes](https://github.com/adeeb144/weathergpt/blob/main/backend/main.py): `backend/main.py`
- [AI agent](https://github.com/adeeb144/weathergpt/blob/main/backend/agent.py): `backend/agent.py`
- [Weather tools](https://github.com/adeeb144/weathergpt/blob/main/backend/tools.py): `backend/tools.py`

### External capabilities

- **Google Gemini**
- **Open-Meteo**
- **Device speech**
- **Device location**

### Other components

- **User**

## Connections

- User → Chat screen: asks weather
- User → Alerts screen: views alerts
- User → Climate charts: views trends
- Chat screen → Chat state: updates
- Chat state → Message model: uses
- Chat state → API service: sends chat
- Chat screen → Voice service: uses voice
- Voice service → Device speech: recognizes and speaks
- Location service → Device location: gets coordinates
- Alerts screen → API service: requests alerts
- Climate charts → API service: requests climate
- API service → FastAPI routes: HTTP requests
- FastAPI routes → AI agent: runs chat agent
- AI agent → Google Gemini: AI function calling
- AI agent → Weather tools: uses weather tools
- FastAPI routes → Weather tools: gets alerts and geocodes
- FastAPI routes → Open-Meteo: fetches climate archive
- Weather tools → Open-Meteo: fetches weather data