# victoraraujo01/claude-flights architecture

> Architecture diagram of the GitHub repository victoraraujo01/claude-flights, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victoraraujo01/claude-flights
- Repository: https://github.com/victoraraujo01/claude-flights

## Overview

claude-flights is a Claude Code skill for managing a trip watchlist and searching Google Flights. Users describe trip changes or request price checks through the `/flights` command; the skill manages `trips.json` and invokes the Python search script. The script expands flexible date windows, queries flight options, and emits structured JSON for the skill to present as a report. The graph includes the documented detail-search capability; source excerpts show query and result-processing behavior but do not expose every CLI branch.

Main entry points: [`search_flights.py`](https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py) (Search CLI), [`.claude/skills/flights/SKILL.md`](https://github.com/victoraraujo01/claude-flights/blob/main/.claude/skills/flights/SKILL.md) (Flights skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skill["Skill and watchlist"]
  node_flight_skill["Flights skill<br/>[SKILL.md]"]
  node_watchlist[("Trip watchlist")]
end

subgraph group_search["Flight search"]
  node_cli["Search CLI<br/>[search_flights.py]"]
  node_trip_loader["Trip loader<br/>[search_flights.py]"]
  node_date_expansion["Date combinations<br/>[search_flights.py]"]
  node_flight_query["Flight querying<br/>[search_flights.py]"]
  node_result_processing["Result processing<br/>[search_flights.py]"]
end

subgraph group_services["External services"]
  node_fast_flights["fast-flights"]
  node_google_flights["Google Flights"]
end

node_traveler(("Traveler"))
node_claude(("Claude Code"))

node_traveler -->|"uses command"| node_claude
node_claude -->|"discovers skill"| node_flight_skill
node_flight_skill -->|"manages trips"| node_watchlist
node_flight_skill -->|"runs search"| node_cli
node_cli -->|"loads trips"| node_trip_loader
node_trip_loader -->|"reads trips"| node_watchlist
node_cli -->|"searches trip dates"| node_date_expansion
node_cli -->|"queries combinations"| node_flight_query
node_flight_query -->|"queries flights"| node_fast_flights
node_fast_flights -->|"fetches flight data"| node_google_flights
node_cli -->|"aggregates results"| node_result_processing
node_result_processing -->|"provides JSON report"| node_flight_skill

click node_flight_skill "https://github.com/victoraraujo01/claude-flights/blob/main/.claude/skills/flights/SKILL.md"
click node_cli "https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py"
click node_trip_loader "https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py"
click node_date_expansion "https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py"
click node_flight_query "https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py"
click node_result_processing "https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.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_flight_skill,node_watchlist toneBlue
class node_cli,node_trip_loader,node_date_expansion,node_flight_query,node_result_processing toneAmber
class node_fast_flights,node_google_flights toneMint
class node_traveler,node_claude toneIndigo
```

## Components

### Skill and watchlist

- [Flights skill](https://github.com/victoraraujo01/claude-flights/blob/main/.claude/skills/flights/SKILL.md): `.claude/skills/flights/SKILL.md`
- **Trip watchlist**

### Flight search

- [Search CLI](https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py): `search_flights.py`
- [Trip loader](https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py): `search_flights.py`
- [Date combinations](https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py): `search_flights.py`
- [Flight querying](https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py): `search_flights.py`
- [Result processing](https://github.com/victoraraujo01/claude-flights/blob/main/search_flights.py): `search_flights.py`

### External services

- **fast-flights**
- **Google Flights**

### Other components

- **Traveler**
- **Claude Code**

## Connections

- Traveler → Claude Code: uses command (evidence: `README.md`)
- Claude Code → Flights skill: discovers skill (evidence: `README.md`)
- Flights skill → Trip watchlist: manages trips (evidence: `README.md`)
- Flights skill → Search CLI: runs search (evidence: `README.md`)
- Search CLI → Trip loader: loads trips (evidence: `search_flights.py`)
- Trip loader → Trip watchlist: reads trips (evidence: `search_flights.py`)
- Search CLI → Date combinations: searches trip dates (evidence: `search_flights.py`)
- Search CLI → Flight querying: queries combinations (evidence: `search_flights.py`)
- Flight querying → fast-flights: queries flights (evidence: `README.md`)
- fast-flights → Google Flights: fetches flight data (evidence: `README.md`)
- Search CLI → Result processing: aggregates results (evidence: `search_flights.py`)
- Result processing → Flights skill: provides JSON report (evidence: `README.md`)
