# sarathchowdary05-commits/trailbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/sarathchowdary05-commits/trailbuddy
- Repository: https://github.com/sarathchowdary05-commits/trailbuddy

## Overview

TrailBuddy is a conversational trail-running advisor with CLI and web chat entry points. A user message reaches a stateful Claude-backed agent, which dispatches tools for trail-list lookup, live conditions, or a weather-aware recommendation; recommendations apply AQI skip rules and rank trails by time and shade fit. Both interfaces load configuration and the personal TOML trail list, while weather comes from Open-Meteo. The sampled source shows these runtime paths; the README describes capabilities consistently, though the static UI implementation was not sampled.

Main entry points: [`src/trailbuddy/web.py`](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/web.py) (Web chat API), [`src/trailbuddy/cli.py`](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/cli.py) (CLI chat), [`src/trailbuddy/agent.py`](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/agent.py) (Agent tools), [`src/trailbuddy/trails.py`](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/trails.py) (Trail loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Chat interfaces"]
  node_cli["CLI chat<br/>[cli.py]"]
  node_web["Web chat API<br/>[web.py]"]
  node_browser["Browser UI<br/>[index.html]"]
end

subgraph group_conversation["Conversation and tools"]
  node_agent["Chat agent<br/>[agent.py]"]
  node_tools["Agent tools<br/>[agent.py]"]
end

subgraph group_domain["Trail and conditions"]
  node_trail_loader["Trail loader<br/>[trails.py]"]
  node_trail_file["Personal trail list<br/>[trails.toml]"]
  node_weather["Weather client<br/>[weather.py]"]
  node_recommend["Trail scoring<br/>[recommend.py]"]
  node_models["Domain data<br/>[models.py]"]
end

subgraph group_configuration["Configuration"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_runner(("Runner"))
node_claude["Anthropic Claude"]
node_open_meteo["Open-Meteo"]

node_runner -->|"starts CLI"| node_cli
node_runner -->|"opens web chat"| node_web
node_browser -->|"sends messages"| node_web
node_cli -->|"loads settings"| node_settings
node_web -->|"loads settings"| node_settings
node_cli -->|"loads trails"| node_trail_loader
node_web -->|"loads trails"| node_trail_loader
node_trail_loader -->|"reads TOML"| node_trail_file
node_cli -->|"sends chat"| node_agent
node_web -->|"creates session agent"| node_agent
node_agent -->|"runs tool chat"| node_claude
node_claude -->|"dispatches calls"| node_tools
node_tools -->|"fetches conditions"| node_weather
node_tools -->|"scores options"| node_recommend
node_tools -->|"uses trail and condition data"| node_models
node_recommend -->|"returns recommendation data"| node_models
node_weather -->|"requests forecast and air quality"| node_open_meteo
node_open_meteo -->|"returns readings"| node_weather

click node_cli "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/cli.py"
click node_web "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/web.py"
click node_browser "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/static/index.html"
click node_agent "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/agent.py"
click node_tools "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/agent.py"
click node_settings "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/config.py"
click node_trail_loader "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/trails.py"
click node_trail_file "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/trails.toml"
click node_weather "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/weather.py"
click node_recommend "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/recommend.py"
click node_models "https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/models.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_cli,node_web,node_browser toneBlue
class node_agent,node_tools toneAmber
class node_trail_loader,node_trail_file,node_weather,node_recommend,node_models toneMint
class node_settings toneRose
class node_runner,node_claude,node_open_meteo toneIndigo
```

## Components

### Chat interfaces

- [CLI chat](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/cli.py): `src/trailbuddy/cli.py`
- [Web chat API](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/web.py): `src/trailbuddy/web.py`
- [Browser UI](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/static/index.html): `src/trailbuddy/static/index.html`

### Conversation and tools

- [Chat agent](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/agent.py): `src/trailbuddy/agent.py`
- [Agent tools](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/agent.py): `src/trailbuddy/agent.py`

### Trail and conditions

- [Trail loader](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/trails.py): `src/trailbuddy/trails.py`
- [Personal trail list](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/trails.toml): `trails.toml`
- [Weather client](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/weather.py): `src/trailbuddy/weather.py`
- [Trail scoring](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/recommend.py): `src/trailbuddy/recommend.py`
- [Domain data](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/models.py): `src/trailbuddy/models.py`

### Configuration

- [Runtime settings](https://github.com/sarathchowdary05-commits/trailbuddy/blob/main/src/trailbuddy/config.py): `src/trailbuddy/config.py`

### Other components

- **Runner**
- **Anthropic Claude**
- **Open-Meteo**

## Connections

- Runner → CLI chat: starts CLI
- Runner → Web chat API: opens web chat
- Browser UI → Web chat API: sends messages
- CLI chat → Runtime settings: loads settings
- Web chat API → Runtime settings: loads settings
- CLI chat → Trail loader: loads trails
- Web chat API → Trail loader: loads trails
- Trail loader → Personal trail list: reads TOML
- CLI chat → Chat agent: sends chat
- Web chat API → Chat agent: creates session agent
- Chat agent → Anthropic Claude: runs tool chat
- Anthropic Claude → Agent tools: dispatches calls
- Agent tools → Weather client: fetches conditions
- Agent tools → Trail scoring: scores options
- Agent tools → Domain data: uses trail and condition data
- Trail scoring → Domain data: returns recommendation data
- Weather client → Open-Meteo: requests forecast and air quality
- Open-Meteo → Weather client: returns readings