# stealbird/voyara_travel_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/stealbird/voyara_travel_assistant
- Repository: https://github.com/stealbird/voyara_travel_assistant

## Overview

Voyara is a travel-planning web app: travelers enter trip preferences, the page requests a route-and-stay plan and day itineraries, then presents the trip with weather, nearby-place information, images, and an interactive map. The Next.js page orchestrates this workflow through a small HTTP client; a FastAPI service supplies planning and enrichment endpoints. The backend excerpt is partial, so some endpoint internals and wiring are not shown; the map’s external tile sources are visible in its source.

Main entry points: [`backend/main.py`](https://github.com/stealbird/voyara_travel_assistant/blob/main/backend/main.py) (Voyara API), [`app/page.tsx`](https://github.com/stealbird/voyara_travel_assistant/blob/main/app/page.tsx) (Trip planner UI), [`components/trip-map.tsx`](https://github.com/stealbird/voyara_travel_assistant/blob/main/components/trip-map.tsx) (Interactive map), [`lib/api.ts`](https://github.com/stealbird/voyara_travel_assistant/blob/main/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Trip experience"]
  node_trip_ui["Trip planner UI<br/>[page.tsx]"]
  node_trip_map["Interactive map<br/>[trip-map.tsx]"]
  node_button["UI button<br/>[button.tsx]"]
end

subgraph group_client["API client"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_service["Planning service"]
  node_voyara_api["Voyara API<br/>[main.py]"]
end

subgraph group_integrations["External data"]
  node_groq["Groq LLM"]
  node_openweather["OpenWeatherMap"]
  node_overpass["Overpass API"]
  node_wikimedia["Wikipedia / Commons"]
  node_map_tiles["Map tile services"]
end

node_traveler(("Traveler"))

node_traveler -->|"enters preferences"| node_trip_ui
node_trip_ui -->|"renders controls"| node_button
node_trip_ui -->|"requests trip data"| node_api_client
node_trip_ui -->|"renders map"| node_trip_map
node_api_client -->|"HTTP requests"| node_voyara_api
node_voyara_api -->|"generates plans"| node_groq
node_voyara_api -->|"fetches weather"| node_openweather
node_voyara_api -->|"queries nearby places"| node_overpass
node_voyara_api -->|"looks up photos"| node_wikimedia
node_trip_map -->|"loads map tiles"| node_map_tiles

click node_trip_ui "https://github.com/stealbird/voyara_travel_assistant/blob/main/app/page.tsx"
click node_trip_map "https://github.com/stealbird/voyara_travel_assistant/blob/main/components/trip-map.tsx"
click node_button "https://github.com/stealbird/voyara_travel_assistant/blob/main/components/ui/button.tsx"
click node_api_client "https://github.com/stealbird/voyara_travel_assistant/blob/main/lib/api.ts"
click node_voyara_api "https://github.com/stealbird/voyara_travel_assistant/blob/main/backend/main.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_trip_ui,node_trip_map,node_button toneBlue
class node_api_client toneAmber
class node_voyara_api toneMint
class node_groq,node_openweather,node_overpass,node_wikimedia,node_map_tiles toneRose
class node_traveler toneIndigo
```

## Components

### Trip experience

- [Trip planner UI](https://github.com/stealbird/voyara_travel_assistant/blob/main/app/page.tsx): `app/page.tsx`
- [Interactive map](https://github.com/stealbird/voyara_travel_assistant/blob/main/components/trip-map.tsx): `components/trip-map.tsx`
- [UI button](https://github.com/stealbird/voyara_travel_assistant/blob/main/components/ui/button.tsx): `components/ui/button.tsx`

### API client

- [API client](https://github.com/stealbird/voyara_travel_assistant/blob/main/lib/api.ts): `lib/api.ts`

### Planning service

- [Voyara API](https://github.com/stealbird/voyara_travel_assistant/blob/main/backend/main.py): `backend/main.py`

### External data

- **Groq LLM**
- **OpenWeatherMap**
- **Overpass API**
- **Wikipedia / Commons**
- **Map tile services**

### Other components

- **Traveler**

## Connections

- Traveler → Trip planner UI: enters preferences (evidence: `app/page.tsx`)
- Trip planner UI → UI button: renders controls (evidence: `app/page.tsx`)
- Trip planner UI → API client: requests trip data (evidence: `app/page.tsx`)
- Trip planner UI → Interactive map: renders map (evidence: `app/page.tsx`)
- API client → Voyara API: HTTP requests (evidence: `lib/api.ts`)
- Voyara API → Groq LLM: generates plans (evidence: `backend/main.py`)
- Voyara API → OpenWeatherMap: fetches weather (evidence: `backend/main.py`)
- Voyara API → Overpass API: queries nearby places (evidence: `backend/main.py`)
- Voyara API → Wikipedia / Commons: looks up photos (evidence: `backend/main.py`)
- Interactive map → Map tile services: loads map tiles (evidence: `components/trip-map.tsx`)
