# bhavithra0304/smarttrip architecture

> Architecture diagram of the GitHub repository bhavithra0304/smarttrip, 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/bhavithra0304/smarttrip
- Repository: https://github.com/bhavithra0304/smarttrip

## Overview

PlanNgo is an AI travel-planning application. Users sign in, submit a trip request or chat query, and receive a coordinated itinerary with budget, weather, recommendations, events, safety, crowd, and route information; trips and favorites can be saved and revisited. The frontend also exposes dashboards, analytics, profile, and settings capabilities. The graph follows documented imports and calls where available; several API, agent, and page implementations are unsampled, so their links rely on SOURCE INDEX references rather than inspected call details.

Main entry points: [`backend/agents/master_agent.py`](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/master_agent.py) (Trip coordinator), [`backend/main.py`](https://github.com/bhavithra0304/smarttrip/blob/main/backend/main.py) (FastAPI app), [`backend/api/trips.py`](https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/trips.py) (Trips API), [`backend/rag/retriever.py`](https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/retriever.py) (Knowledge retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Travel frontend"]
  node_webapp["App and routes<br/>[App.jsx]"]
  node_tripui["Trip pages"]
  node_chatui["Chat widget<br/>[ChatWidget.jsx]"]
  node_tripcontext["Trip context<br/>[TripContext.jsx]"]
  node_tripservice["Trip API client<br/>[tripService.js]"]
  node_authcontext["Auth context<br/>[AuthContext.jsx]"]
  node_authservice["Auth API client<br/>[authService.js]"]
end

subgraph group_api["API and identity"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_authapi["Authentication API<br/>[auth.py]"]
  node_tripapi["Trips API<br/>[trips.py]"]
  node_chatapi["Chat API<br/>[chat.py]"]
  node_userapi["User API<br/>[user.py]"]
  node_settingsapi["Settings API<br/>[settings.py]"]
end

subgraph group_planning["Trip intelligence"]
  node_master["Trip coordinator<br/>[master_agent.py]"]
  node_planner["Itinerary planner<br/>[planner_agent.py]"]
  node_budget["Budget optimizer<br/>[budget_agent.py]"]
  node_weatheragent["Weather agent<br/>[weather_agent.py]"]
  node_recommend["Recommendations"]
  node_eventsagent["Local events"]
  node_safetyagent["Safety analysis<br/>[safety_agent.py]"]
  node_crowdagent["Crowd analysis<br/>[crowd_agent.py]"]
  node_navigation["Route planning"]
  node_booking["Booking agent<br/>[booking_agent.py]"]
end

subgraph group_knowledge["Travel knowledge"]
  node_rag["Knowledge retrieval<br/>[retriever.py]"]
  node_ingest["Knowledge ingestion<br/>[ingest.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
end

subgraph group_persistence["User and trip data"]
  node_database[("SQL database<br/>[connection.py]")]
  node_userdata["User records<br/>[user.py]"]
  node_tripdata["Trips and favorites<br/>[trip.py]"]
end

subgraph group_integrations["External services"]
  node_llm{{"Groq language model"}}
  node_weatherext{{"Open-Meteo"}}
  node_travelapis{{"Travel data APIs"}}
end

node_traveler(("Traveler"))

node_traveler -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_tripui
node_tripui -.->|"uses"| node_tripcontext
node_tripcontext -->|"calls"| node_tripservice
node_tripui -.->|"requests trips"| node_tripservice
node_chatui -->|"sends queries"| node_tripservice
node_webapp -->|"provides auth"| node_authcontext
node_authcontext -->|"calls"| node_authservice
node_tripservice -->|"HTTP requests"| node_backend
node_authservice -.->|"HTTP requests"| node_backend
node_backend -->|"registers router"| node_authapi
node_backend -->|"registers router"| node_tripapi
node_backend -->|"registers router"| node_chatapi
node_backend -->|"registers router"| node_userapi
node_backend -->|"registers router"| node_settingsapi
node_authapi -->|"gets sessions"| node_database
node_authapi -->|"reads and updates"| node_userdata
node_tripapi -->|"generates trips"| node_master
node_tripapi -->|"uses sessions"| node_database
node_tripapi -->|"stores trip data"| node_tripdata
node_chatapi -->|"coordinates planning"| node_master
node_chatapi -->|"queries knowledge"| node_rag
node_userapi -->|"uses sessions"| node_database
node_userapi -->|"reads user data"| node_userdata
node_master -->|"dispatches"| node_planner
node_master -->|"dispatches"| node_budget
node_master -->|"dispatches"| node_weatheragent
node_master -->|"dispatches"| node_recommend
node_master -->|"dispatches"| node_eventsagent
node_master -->|"dispatches"| node_safetyagent
node_master -->|"dispatches"| node_crowdagent
node_master -->|"dispatches"| node_navigation
node_recommend -->|"retrieves guides"| node_rag
node_rag -->|"initializes collection"| node_ingest
node_ingest -->|"embeds documents"| node_embeddings
node_rag -->|"embeds queries"| node_embeddings
node_master -.->|"parses requests"| node_llm
node_master -.->|"coordinates forecasts"| node_weatherext
node_planner -.->|"searches places"| node_travelapis
node_navigation -.->|"computes routes"| node_travelapis
node_budget -.->|"converts currency"| node_travelapis
node_eventsagent -.->|"finds events"| node_travelapis
node_weatheragent -.->|"fetches forecasts"| node_weatherext

click node_webapp "https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/App.jsx"
click node_tripui "https://github.com/bhavithra0304/smarttrip/tree/main/frontend/src/pages"
click node_chatui "https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/components/ChatWidget.jsx"
click node_tripcontext "https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/context/TripContext.jsx"
click node_tripservice "https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/services/tripService.js"
click node_authcontext "https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/context/AuthContext.jsx"
click node_authservice "https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/services/authService.js"
click node_backend "https://github.com/bhavithra0304/smarttrip/blob/main/backend/main.py"
click node_authapi "https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/auth.py"
click node_tripapi "https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/trips.py"
click node_chatapi "https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/chat.py"
click node_userapi "https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/user.py"
click node_settingsapi "https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/settings.py"
click node_master "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/master_agent.py"
click node_planner "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/planner_agent.py"
click node_budget "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/budget_agent.py"
click node_weatheragent "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/weather_agent.py"
click node_recommend "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/recommendation_agent.py"
click node_eventsagent "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/local_events_agent.py"
click node_safetyagent "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/safety_agent.py"
click node_crowdagent "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/crowd_agent.py"
click node_navigation "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/navigation_agent.py"
click node_booking "https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/booking_agent.py"
click node_rag "https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/retriever.py"
click node_ingest "https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/ingest.py"
click node_embeddings "https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/embeddings.py"
click node_database "https://github.com/bhavithra0304/smarttrip/blob/main/backend/database/connection.py"
click node_userdata "https://github.com/bhavithra0304/smarttrip/blob/main/backend/models/user.py"
click node_tripdata "https://github.com/bhavithra0304/smarttrip/blob/main/backend/models/trip.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_webapp,node_tripui,node_chatui,node_tripcontext,node_tripservice,node_authcontext,node_authservice toneBlue
class node_backend,node_authapi,node_tripapi,node_chatapi,node_userapi,node_settingsapi toneAmber
class node_master,node_planner,node_budget,node_weatheragent,node_recommend,node_eventsagent,node_safetyagent,node_crowdagent,node_navigation,node_booking toneMint
class node_rag,node_ingest,node_embeddings toneRose
class node_database,node_userdata,node_tripdata,node_traveler toneIndigo
class node_llm,node_weatherext,node_travelapis toneTeal
```

## Components

### Travel frontend

- [App and routes](https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Trip pages](https://github.com/bhavithra0304/smarttrip/tree/main/frontend/src/pages): `frontend/src/pages`
- [Chat widget](https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/components/ChatWidget.jsx): `frontend/src/components/ChatWidget.jsx`
- [Trip context](https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/context/TripContext.jsx): `frontend/src/context/TripContext.jsx`
- [Trip API client](https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/services/tripService.js): `frontend/src/services/tripService.js`
- [Auth context](https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Auth API client](https://github.com/bhavithra0304/smarttrip/blob/main/frontend/src/services/authService.js): `frontend/src/services/authService.js`

### API and identity

- [FastAPI app](https://github.com/bhavithra0304/smarttrip/blob/main/backend/main.py): `backend/main.py`
- [Authentication API](https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Trips API](https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/trips.py): `backend/api/trips.py`
- [Chat API](https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/chat.py): `backend/api/chat.py`
- [User API](https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/user.py): `backend/api/user.py`
- [Settings API](https://github.com/bhavithra0304/smarttrip/blob/main/backend/api/settings.py): `backend/api/settings.py`

### Trip intelligence

- [Trip coordinator](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/master_agent.py): `backend/agents/master_agent.py`
- [Itinerary planner](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/planner_agent.py): `backend/agents/planner_agent.py`
- [Budget optimizer](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/budget_agent.py): `backend/agents/budget_agent.py`
- [Weather agent](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/weather_agent.py): `backend/agents/weather_agent.py`
- [Recommendations](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/recommendation_agent.py): `backend/agents/recommendation_agent.py`
- [Local events](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/local_events_agent.py): `backend/agents/local_events_agent.py`
- [Safety analysis](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/safety_agent.py): `backend/agents/safety_agent.py`
- [Crowd analysis](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/crowd_agent.py): `backend/agents/crowd_agent.py`
- [Route planning](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/navigation_agent.py): `backend/agents/navigation_agent.py`
- [Booking agent](https://github.com/bhavithra0304/smarttrip/blob/main/backend/agents/booking_agent.py): `backend/agents/booking_agent.py`

### Travel knowledge

- [Knowledge retrieval](https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Knowledge ingestion](https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/ingest.py): `backend/rag/ingest.py`
- [Text embeddings](https://github.com/bhavithra0304/smarttrip/blob/main/backend/rag/embeddings.py): `backend/rag/embeddings.py`

### User and trip data

- [SQL database](https://github.com/bhavithra0304/smarttrip/blob/main/backend/database/connection.py): `backend/database/connection.py`
- [User records](https://github.com/bhavithra0304/smarttrip/blob/main/backend/models/user.py): `backend/models/user.py`
- [Trips and favorites](https://github.com/bhavithra0304/smarttrip/blob/main/backend/models/trip.py): `backend/models/trip.py`

### External services

- **Groq language model**
- **Open-Meteo**
- **Travel data APIs**

### Other components

- **Traveler**

## Connections

- Traveler → App and routes: uses (evidence: `frontend/src/App.jsx`)
- App and routes → Trip pages: routes to (evidence: `frontend/src/App.jsx`)
- Trip pages → Trip context: uses
- Trip context → Trip API client: calls (evidence: `frontend/src/context/TripContext.jsx`)
- Trip pages → Trip API client: requests trips
- Chat widget → Trip API client: sends queries (evidence: `frontend/src/components/ChatWidget.jsx`)
- App and routes → Auth context: provides auth (evidence: `frontend/src/App.jsx`)
- Auth context → Auth API client: calls (evidence: `frontend/src/context/AuthContext.jsx`)
- Trip API client → FastAPI app: HTTP requests (evidence: `frontend/src/services/tripService.js`)
- Auth API client → FastAPI app: HTTP requests
- FastAPI app → Authentication API: registers router (evidence: `backend/main.py`)
- FastAPI app → Trips API: registers router (evidence: `backend/main.py`)
- FastAPI app → Chat API: registers router (evidence: `backend/main.py`)
- FastAPI app → User API: registers router (evidence: `backend/main.py`)
- FastAPI app → Settings API: registers router (evidence: `backend/main.py`)
- Authentication API → SQL database: gets sessions (evidence: `backend/api/auth.py`)
- Authentication API → User records: reads and updates (evidence: `backend/api/auth.py`)
- Trips API → Trip coordinator: generates trips (evidence: `backend/api/trips.py`)
- Trips API → SQL database: uses sessions (evidence: `backend/api/trips.py`)
- Trips API → Trips and favorites: stores trip data (evidence: `backend/api/trips.py`)
- Chat API → Trip coordinator: coordinates planning (evidence: `backend/api/chat.py`)
- Chat API → Knowledge retrieval: queries knowledge (evidence: `backend/api/chat.py`)
- User API → SQL database: uses sessions (evidence: `backend/api/user.py`)
- User API → User records: reads user data (evidence: `backend/api/user.py`)
- Trip coordinator → Itinerary planner: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Budget optimizer: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Weather agent: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Recommendations: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Local events: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Safety analysis: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Crowd analysis: dispatches (evidence: `backend/agents/master_agent.py`)
- Trip coordinator → Route planning: dispatches (evidence: `backend/agents/master_agent.py`)
- Recommendations → Knowledge retrieval: retrieves guides (evidence: `backend/agents/recommendation_agent.py`)
- Knowledge retrieval → Knowledge ingestion: initializes collection (evidence: `backend/rag/retriever.py`)
- Knowledge ingestion → Text embeddings: embeds documents (evidence: `backend/rag/ingest.py`)
- Knowledge retrieval → Text embeddings: embeds queries (evidence: `backend/rag/retriever.py`)
- Trip coordinator → Groq language model: parses requests
- Trip coordinator → Open-Meteo: coordinates forecasts
- Itinerary planner → Travel data APIs: searches places
- Route planning → Travel data APIs: computes routes
- Budget optimizer → Travel data APIs: converts currency
- Local events → Travel data APIs: finds events
- Weather agent → Open-Meteo: fetches forecasts
