# shub1504/waypoint- architecture

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

- Interactive diagram: https://gitdiagram.com/shub1504/waypoint-
- Repository: https://github.com/shub1504/waypoint-

## Overview

Waypoint is a travel-disruption concierge: travellers register trips and preferences, then disruptions trigger replacement searches, budget checks and either automated or human-approved decisions, payment handling and notifications. The graph includes the documented live-data, chat, journey-booking and planning capabilities. The sampled backend entry point and frontend establish key API/UI relationships; several domain modules were not sampled, so their internal call paths are omitted where the evidence does not establish them.

Main entry points: [`backend/app/main.py`](https://github.com/shub1504/waypoint-/blob/main/backend/app/main.py) (REST API), [`frontend/App.jsx`](https://github.com/shub1504/waypoint-/blob/main/frontend/App.jsx) (Waypoint interface), [`backend/app/agent.py`](https://github.com/shub1504/waypoint-/blob/main/backend/app/agent.py) (Disruption agent), [`backend/app/chat.py`](https://github.com/shub1504/waypoint-/blob/main/backend/app/chat.py) (Chat services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Traveller experience"]
  node_ui["Waypoint interface<br/>[App.jsx]"]
  node_home["Trips and home<br/>[Home.jsx]"]
  node_explore["Explore alternatives<br/>[Explore.jsx]"]
  node_chatui["Concierge chat<br/>[Chat.jsx]"]
  node_profile["Profile and payments<br/>[Profile.jsx]"]
  node_journeyui["Start journey<br/>[StartJourney.jsx]"]
end

subgraph group_operations["Disruption operations"]
  node_api["REST API<br/>[main.py]"]
  node_disruption["Disruption agent<br/>[agent.py]"]
  node_guardrail["Budget guardrail<br/>[guardrail.py]"]
  node_alternatives["Alternative search<br/>[explore.py]"]
  node_journey["Journey booking<br/>[journey.py]"]
  node_cancel["Cancel and refund<br/>[cancel.py]"]
  node_chat["Chat services<br/>[chat.py]"]
  node_router["Intent router<br/>[router.py]"]
end

subgraph group_data["Persistence and integrations"]
  node_live["Live travel data<br/>[live_providers.py]"]
  node_eventbus["Disruption event bus<br/>[bus.py]"]
  node_database[("Waypoint database<br/>[models.py]")]
  node_paypal["PayPal payments<br/>[payments.py]"]
end

subgraph group_planning["AI travel planning"]
  node_langgraph["Planning workflow<br/>[graph.py]"]
  node_research["Travel research<br/>[research.py]"]
  node_approval["Human approval<br/>[approval.py]"]
  node_triptools["Travel search tools"]
end

node_traveller(("Traveller"))
node_paypalservice["PayPal sandbox"]
node_railradar["RailRadar"]
node_hasdata["HasData"]
node_gemini["Gemini"]
node_travelleralerts["Push, SMS, email"]

node_traveller -->|"uses"| node_ui
node_ui -->|"renders"| node_home
node_ui -->|"renders"| node_explore
node_ui -->|"renders"| node_chatui
node_ui -->|"renders"| node_profile
node_journeyui -->|"requests"| node_api
node_ui -->|"calls"| node_api
node_api -->|"dispatches"| node_disruption
node_api -->|"routes"| node_alternatives
node_api -->|"routes"| node_journey
node_api -->|"calls"| node_cancel
node_api -->|"routes"| node_chat
node_chat -->|"classifies"| node_router
node_disruption -->|"checks ceiling"| node_guardrail
node_disruption -->|"finds options"| node_alternatives
node_disruption -->|"charges"| node_paypal
node_disruption -->|"notifies"| node_travelleralerts
node_api -->|"consumes events"| node_eventbus
node_eventbus -->|"delivers events"| node_disruption
node_api -->|"reads and writes"| node_database
node_paypal -->|"uses"| node_paypalservice
node_live -->|"fetches schedules"| node_railradar
node_live -->|"fetches flights"| node_hasdata
node_chat -->|"searches travel data"| node_live
node_api -->|"mounts routes"| node_langgraph
node_langgraph -->|"runs node"| node_research
node_research -->|"searches options"| node_triptools
node_research -->|"plans research"| node_gemini
node_langgraph -->|"awaits approval"| node_approval

click node_ui "https://github.com/shub1504/waypoint-/blob/main/frontend/App.jsx"
click node_home "https://github.com/shub1504/waypoint-/blob/main/frontend/components/Home.jsx"
click node_explore "https://github.com/shub1504/waypoint-/blob/main/frontend/components/Explore.jsx"
click node_chatui "https://github.com/shub1504/waypoint-/blob/main/frontend/components/Chat.jsx"
click node_profile "https://github.com/shub1504/waypoint-/blob/main/frontend/components/Profile.jsx"
click node_journeyui "https://github.com/shub1504/waypoint-/blob/main/frontend/src/components/StartJourney.jsx"
click node_api "https://github.com/shub1504/waypoint-/blob/main/backend/app/main.py"
click node_disruption "https://github.com/shub1504/waypoint-/blob/main/backend/app/agent.py"
click node_guardrail "https://github.com/shub1504/waypoint-/blob/main/backend/app/guardrail.py"
click node_alternatives "https://github.com/shub1504/waypoint-/blob/main/backend/app/explore.py"
click node_journey "https://github.com/shub1504/waypoint-/blob/main/backend/app/journey.py"
click node_cancel "https://github.com/shub1504/waypoint-/blob/main/backend/app/cancel.py"
click node_chat "https://github.com/shub1504/waypoint-/blob/main/backend/app/chat.py"
click node_router "https://github.com/shub1504/waypoint-/blob/main/backend/app/router.py"
click node_live "https://github.com/shub1504/waypoint-/blob/main/backend/app/live_providers.py"
click node_eventbus "https://github.com/shub1504/waypoint-/blob/main/backend/app/bus.py"
click node_database "https://github.com/shub1504/waypoint-/blob/main/backend/app/models.py"
click node_paypal "https://github.com/shub1504/waypoint-/blob/main/backend/app/payments.py"
click node_langgraph "https://github.com/shub1504/waypoint-/blob/main/backend/travel_agent_langgraph_complete/app/graph.py"
click node_research "https://github.com/shub1504/waypoint-/blob/main/backend/travel_agent_langgraph_complete/app/nodes/research.py"
click node_approval "https://github.com/shub1504/waypoint-/blob/main/backend/travel_agent_langgraph_complete/app/nodes/approval.py"
click node_triptools "https://github.com/shub1504/waypoint-/tree/main/backend/travel_agent_langgraph_complete/app/tools"

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_ui,node_home,node_explore,node_chatui,node_profile,node_journeyui toneBlue
class node_api,node_disruption,node_guardrail,node_alternatives,node_journey,node_cancel,node_chat,node_router toneAmber
class node_live,node_eventbus,node_database,node_paypal toneMint
class node_langgraph,node_research,node_approval,node_triptools toneRose
class node_traveller,node_paypalservice,node_railradar,node_hasdata,node_gemini,node_travelleralerts toneIndigo
```

## Components

### Traveller experience

- [Waypoint interface](https://github.com/shub1504/waypoint-/blob/main/frontend/App.jsx): `frontend/App.jsx`
- [Trips and home](https://github.com/shub1504/waypoint-/blob/main/frontend/components/Home.jsx): `frontend/components/Home.jsx`
- [Explore alternatives](https://github.com/shub1504/waypoint-/blob/main/frontend/components/Explore.jsx): `frontend/components/Explore.jsx`
- [Concierge chat](https://github.com/shub1504/waypoint-/blob/main/frontend/components/Chat.jsx): `frontend/components/Chat.jsx`
- [Profile and payments](https://github.com/shub1504/waypoint-/blob/main/frontend/components/Profile.jsx): `frontend/components/Profile.jsx`
- [Start journey](https://github.com/shub1504/waypoint-/blob/main/frontend/src/components/StartJourney.jsx): `frontend/src/components/StartJourney.jsx`

### Disruption operations

- [REST API](https://github.com/shub1504/waypoint-/blob/main/backend/app/main.py): `backend/app/main.py`
- [Disruption agent](https://github.com/shub1504/waypoint-/blob/main/backend/app/agent.py): `backend/app/agent.py`
- [Budget guardrail](https://github.com/shub1504/waypoint-/blob/main/backend/app/guardrail.py): `backend/app/guardrail.py`
- [Alternative search](https://github.com/shub1504/waypoint-/blob/main/backend/app/explore.py): `backend/app/explore.py`
- [Journey booking](https://github.com/shub1504/waypoint-/blob/main/backend/app/journey.py): `backend/app/journey.py`
- [Cancel and refund](https://github.com/shub1504/waypoint-/blob/main/backend/app/cancel.py): `backend/app/cancel.py`
- [Chat services](https://github.com/shub1504/waypoint-/blob/main/backend/app/chat.py): `backend/app/chat.py`
- [Intent router](https://github.com/shub1504/waypoint-/blob/main/backend/app/router.py): `backend/app/router.py`

### Persistence and integrations

- [Live travel data](https://github.com/shub1504/waypoint-/blob/main/backend/app/live_providers.py): `backend/app/live_providers.py`
- [Disruption event bus](https://github.com/shub1504/waypoint-/blob/main/backend/app/bus.py): `backend/app/bus.py`
- [Waypoint database](https://github.com/shub1504/waypoint-/blob/main/backend/app/models.py): `backend/app/models.py`
- [PayPal payments](https://github.com/shub1504/waypoint-/blob/main/backend/app/payments.py): `backend/app/payments.py`

### AI travel planning

- [Planning workflow](https://github.com/shub1504/waypoint-/blob/main/backend/travel_agent_langgraph_complete/app/graph.py): `backend/travel_agent_langgraph_complete/app/graph.py`
- [Travel research](https://github.com/shub1504/waypoint-/blob/main/backend/travel_agent_langgraph_complete/app/nodes/research.py): `backend/travel_agent_langgraph_complete/app/nodes/research.py`
- [Human approval](https://github.com/shub1504/waypoint-/blob/main/backend/travel_agent_langgraph_complete/app/nodes/approval.py): `backend/travel_agent_langgraph_complete/app/nodes/approval.py`
- [Travel search tools](https://github.com/shub1504/waypoint-/tree/main/backend/travel_agent_langgraph_complete/app/tools): `backend/travel_agent_langgraph_complete/app/tools`

### Other components

- **Traveller**
- **PayPal sandbox**
- **RailRadar**
- **HasData**
- **Gemini**
- **Push, SMS, email**

## Connections

- Traveller → Waypoint interface: uses (evidence: `README.md`)
- Waypoint interface → Trips and home: renders (evidence: `frontend/App.jsx`)
- Waypoint interface → Explore alternatives: renders (evidence: `frontend/App.jsx`)
- Waypoint interface → Concierge chat: renders (evidence: `frontend/App.jsx`)
- Waypoint interface → Profile and payments: renders (evidence: `frontend/App.jsx`)
- Start journey → REST API: requests
- Waypoint interface → REST API: calls (evidence: `README.md`)
- REST API → Disruption agent: dispatches (evidence: `backend/app/main.py`)
- REST API → Alternative search: routes (evidence: `backend/app/main.py`)
- REST API → Journey booking: routes (evidence: `backend/app/main.py`)
- REST API → Cancel and refund: calls (evidence: `backend/app/main.py`)
- REST API → Chat services: routes (evidence: `backend/app/main.py`)
- Chat services → Intent router: classifies (evidence: `backend/app/router.py`)
- Disruption agent → Budget guardrail: checks ceiling (evidence: `README.md`)
- Disruption agent → Alternative search: finds options (evidence: `README.md`)
- Disruption agent → PayPal payments: charges (evidence: `README.md`)
- Disruption agent → Push, SMS, email: notifies (evidence: `README.md`)
- REST API → Disruption event bus: consumes events (evidence: `backend/app/main.py`)
- Disruption event bus → Disruption agent: delivers events (evidence: `README.md`)
- REST API → Waypoint database: reads and writes (evidence: `backend/app/main.py`)
- PayPal payments → PayPal sandbox: uses (evidence: `README.md`)
- Live travel data → RailRadar: fetches schedules (evidence: `README.md`)
- Live travel data → HasData: fetches flights (evidence: `README.md`)
- Chat services → Live travel data: searches travel data (evidence: `README.md`)
- REST API → Planning workflow: mounts routes (evidence: `backend/app/main.py`)
- Planning workflow → Travel research: runs node (evidence: `backend/travel_agent_langgraph_complete/app/graph.py`)
- Travel research → Travel search tools: searches options (evidence: `backend/travel_agent_langgraph_complete/app/nodes/research.py`)
- Travel research → Gemini: plans research (evidence: `backend/travel_agent_langgraph_complete/app/nodes/research.py`)
- Planning workflow → Human approval: awaits approval (evidence: `backend/travel_agent_langgraph_complete/app/graph.py`)
