# vikas9892/weather-agent architecture

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

- Interactive diagram: https://gitdiagram.com/vikas9892/weather-agent
- Repository: https://github.com/vikas9892/weather-agent

## Overview

Outdoor Safety Agent accepts a chat query, carries session context, resolves the location, retrieves live weather, evaluates deterministic SOP policies, resolves conflicts, applies a safety gate, generates an explanation, and validates it before returning the result. The graph preserves the README’s documented fallback branches and separates weather, policy, safety, and response responsibilities. Workflow relationships are cited to the README; source-index evidence supports the internal calls shown. Unsampled implementation details are not inferred.

Main entry points: [`app/graph/graph.py`](https://github.com/vikas9892/weather-agent/blob/main/app/graph/graph.py) (LangGraph workflow), [`app/weather/gateway.py`](https://github.com/vikas9892/weather-agent/blob/main/app/weather/gateway.py) (Weather gateway), [`app/graph/nodes/policy.py`](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/policy.py) (SOP matching), [`app/llm/gateway.py`](https://github.com/vikas9892/weather-agent/blob/main/app/llm/gateway.py) (LLM gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Chat and orchestration"]
  node_chat["Chat API<br/>[chat.py]"]
  node_workflow["LangGraph workflow<br/>[graph.py]"]
  node_state["Workflow state<br/>[state.py]"]
  node_session[("Session memory<br/>[session.py]")]
  node_intent["Query understanding<br/>[understand.py]"]
end

subgraph group_weather["Weather telemetry"]
  node_location["Location resolution<br/>[weather.py]"]
  node_weather_node["Weather retrieval<br/>[weather.py]"]
  node_weather_gateway["Weather gateway<br/>[gateway.py]"]
  node_weather_models["Weather data model<br/>[models.py]"]
  node_openmeteo["Open-Meteo provider<br/>[open_meteo.py]"]
  node_other_weather["Fallback providers<br/>[open_weather.py]"]
end

subgraph group_policy["SOP policy engine"]
  node_policy_node["SOP matching<br/>[policy.py]"]
  node_registry[("Policy registry<br/>[registry.py]")]
  node_evaluator["Rule evaluator<br/>[evaluator.py]"]
  node_resolver["Conflict resolver<br/>[resolver.py]"]
end

subgraph group_safety["Safety and response"]
  node_safety_node["Generation gate<br/>[safety.py]"]
  node_gate["Safety gate<br/>[gate.py]"]
  node_response_node["Response generation<br/>[response.py]"]
  node_llm["LLM gateway<br/>[gateway.py]"]
  node_validator["Response validator<br/>[validator.py]"]
end

subgraph group_integrations["External interfaces"]
  node_weather_service["Weather services"]
  node_mcp_tools["MCP weather tools<br/>[tools.py]"]
  node_mcp_server["MCP weather server<br/>[server.py]"]
  node_llm_service["LLM provider"]
end

node_user(("User"))

node_user -->|"submits query"| node_chat
node_chat -->|"starts workflow"| node_workflow
node_workflow -->|"loads and persists"| node_session
node_workflow -->|"runs"| node_intent
node_intent -->|"interprets query"| node_llm
node_workflow -->|"resolves location"| node_location
node_workflow -->|"fetches weather"| node_weather_node
node_weather_node -->|"requests weather"| node_weather_gateway
node_weather_gateway -->|"queries primary"| node_openmeteo
node_weather_gateway -.->|"uses fallback"| node_other_weather
node_weather_gateway -->|"queries provider"| node_weather_service
node_workflow -->|"matches SOPs"| node_policy_node
node_policy_node -->|"selects policies"| node_registry
node_registry -.->|"provides rules for"| node_evaluator
node_policy_node -->|"evaluates conditions"| node_evaluator
node_workflow -->|"resolves conflicts"| node_resolver
node_workflow -->|"checks generation"| node_safety_node
node_safety_node -->|"evaluates evidence"| node_gate
node_workflow -->|"generates response"| node_response_node
node_response_node -->|"requests explanation"| node_llm
node_llm -->|"calls model"| node_llm_service
node_workflow -->|"audits response"| node_validator
node_workflow -->|"propagates state"| node_state
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"uses gateway"| node_weather_gateway

click node_chat "https://github.com/vikas9892/weather-agent/blob/main/app/api/chat.py"
click node_workflow "https://github.com/vikas9892/weather-agent/blob/main/app/graph/graph.py"
click node_state "https://github.com/vikas9892/weather-agent/blob/main/app/graph/state.py"
click node_session "https://github.com/vikas9892/weather-agent/blob/main/app/memory/session.py"
click node_intent "https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/understand.py"
click node_location "https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/weather.py"
click node_weather_node "https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/weather.py"
click node_weather_gateway "https://github.com/vikas9892/weather-agent/blob/main/app/weather/gateway.py"
click node_weather_models "https://github.com/vikas9892/weather-agent/blob/main/app/weather/models.py"
click node_openmeteo "https://github.com/vikas9892/weather-agent/blob/main/app/weather/providers/open_meteo.py"
click node_other_weather "https://github.com/vikas9892/weather-agent/blob/main/app/weather/providers/open_weather.py"
click node_policy_node "https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/policy.py"
click node_registry "https://github.com/vikas9892/weather-agent/blob/main/app/policy/registry.py"
click node_evaluator "https://github.com/vikas9892/weather-agent/blob/main/app/policy/evaluator.py"
click node_resolver "https://github.com/vikas9892/weather-agent/blob/main/app/policy/resolver.py"
click node_safety_node "https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/safety.py"
click node_gate "https://github.com/vikas9892/weather-agent/blob/main/app/safety/gate.py"
click node_response_node "https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/response.py"
click node_llm "https://github.com/vikas9892/weather-agent/blob/main/app/llm/gateway.py"
click node_validator "https://github.com/vikas9892/weather-agent/blob/main/app/safety/validator.py"
click node_mcp_tools "https://github.com/vikas9892/weather-agent/blob/main/mcp/weather_server/tools.py"
click node_mcp_server "https://github.com/vikas9892/weather-agent/blob/main/mcp/weather_server/server.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_workflow,node_state,node_session,node_intent,node_user toneBlue
class node_location,node_weather_node,node_weather_gateway,node_weather_models,node_openmeteo,node_other_weather toneAmber
class node_policy_node,node_registry,node_evaluator,node_resolver toneMint
class node_safety_node,node_gate,node_response_node,node_llm,node_validator toneRose
class node_weather_service,node_mcp_tools,node_mcp_server,node_llm_service toneIndigo
```

## Components

### Chat and orchestration

- [Chat API](https://github.com/vikas9892/weather-agent/blob/main/app/api/chat.py): `app/api/chat.py`
- [LangGraph workflow](https://github.com/vikas9892/weather-agent/blob/main/app/graph/graph.py): `app/graph/graph.py`
- [Workflow state](https://github.com/vikas9892/weather-agent/blob/main/app/graph/state.py): `app/graph/state.py`
- [Session memory](https://github.com/vikas9892/weather-agent/blob/main/app/memory/session.py): `app/memory/session.py`
- [Query understanding](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/understand.py): `app/graph/nodes/understand.py`

### Weather telemetry

- [Location resolution](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/weather.py): `app/graph/nodes/weather.py`
- [Weather retrieval](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/weather.py): `app/graph/nodes/weather.py`
- [Weather gateway](https://github.com/vikas9892/weather-agent/blob/main/app/weather/gateway.py): `app/weather/gateway.py`
- [Weather data model](https://github.com/vikas9892/weather-agent/blob/main/app/weather/models.py): `app/weather/models.py`
- [Open-Meteo provider](https://github.com/vikas9892/weather-agent/blob/main/app/weather/providers/open_meteo.py): `app/weather/providers/open_meteo.py`
- [Fallback providers](https://github.com/vikas9892/weather-agent/blob/main/app/weather/providers/open_weather.py): `app/weather/providers/open_weather.py`

### SOP policy engine

- [SOP matching](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/policy.py): `app/graph/nodes/policy.py`
- [Policy registry](https://github.com/vikas9892/weather-agent/blob/main/app/policy/registry.py): `app/policy/registry.py`
- [Rule evaluator](https://github.com/vikas9892/weather-agent/blob/main/app/policy/evaluator.py): `app/policy/evaluator.py`
- [Conflict resolver](https://github.com/vikas9892/weather-agent/blob/main/app/policy/resolver.py): `app/policy/resolver.py`

### Safety and response

- [Generation gate](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/safety.py): `app/graph/nodes/safety.py`
- [Safety gate](https://github.com/vikas9892/weather-agent/blob/main/app/safety/gate.py): `app/safety/gate.py`
- [Response generation](https://github.com/vikas9892/weather-agent/blob/main/app/graph/nodes/response.py): `app/graph/nodes/response.py`
- [LLM gateway](https://github.com/vikas9892/weather-agent/blob/main/app/llm/gateway.py): `app/llm/gateway.py`
- [Response validator](https://github.com/vikas9892/weather-agent/blob/main/app/safety/validator.py): `app/safety/validator.py`

### External interfaces

- **Weather services**
- [MCP weather tools](https://github.com/vikas9892/weather-agent/blob/main/mcp/weather_server/tools.py): `mcp/weather_server/tools.py`
- [MCP weather server](https://github.com/vikas9892/weather-agent/blob/main/mcp/weather_server/server.py): `mcp/weather_server/server.py`
- **LLM provider**

### Other components

- **User**

## Connections

- User → Chat API: submits query
- Chat API → LangGraph workflow: starts workflow (evidence: `app/api/chat.py`)
- LangGraph workflow → Session memory: loads and persists (evidence: `app/graph/graph.py`)
- LangGraph workflow → Query understanding: runs (evidence: `app/graph/graph.py`)
- Query understanding → LLM gateway: interprets query (evidence: `app/graph/nodes/understand.py`)
- LangGraph workflow → Location resolution: resolves location (evidence: `app/graph/graph.py`)
- LangGraph workflow → Weather retrieval: fetches weather (evidence: `app/graph/graph.py`)
- Weather retrieval → Weather gateway: requests weather (evidence: `app/graph/nodes/weather.py`)
- Weather gateway → Open-Meteo provider: queries primary (evidence: `app/weather/gateway.py`)
- Weather gateway → Fallback providers: uses fallback (evidence: `app/weather/gateway.py`)
- Weather gateway → Weather services: queries provider
- LangGraph workflow → SOP matching: matches SOPs (evidence: `app/graph/graph.py`)
- SOP matching → Policy registry: selects policies (evidence: `app/graph/nodes/policy.py`)
- Policy registry → Rule evaluator: provides rules for
- SOP matching → Rule evaluator: evaluates conditions (evidence: `app/graph/nodes/policy.py`)
- LangGraph workflow → Conflict resolver: resolves conflicts (evidence: `app/graph/graph.py`)
- LangGraph workflow → Generation gate: checks generation (evidence: `app/graph/graph.py`)
- Generation gate → Safety gate: evaluates evidence (evidence: `app/graph/nodes/safety.py`)
- LangGraph workflow → Response generation: generates response (evidence: `app/graph/graph.py`)
- Response generation → LLM gateway: requests explanation (evidence: `app/graph/nodes/response.py`)
- LLM gateway → LLM provider: calls model
- LangGraph workflow → Response validator: audits response (evidence: `app/graph/graph.py`)
- LangGraph workflow → Workflow state: propagates state (evidence: `app/graph/graph.py`)
- MCP weather server → MCP weather tools: dispatches tools (evidence: `mcp/weather_server/server.py`)
- MCP weather tools → Weather gateway: uses gateway (evidence: `mcp/weather_server/tools.py`)
