# guptaastha1427/trip-planner architecture

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

- Interactive diagram: https://gitdiagram.com/guptaastha1427/trip-planner
- Repository: https://github.com/guptaastha1427/trip-planner

## Overview

This is a Streamlit trip-planning app with a separate demo travel portal and policy Q&A. The main user flow collects trip preferences, validates them, runs an itinerary agent using map data and Gemini, then displays and saves the result; users can also view maps, get trip details, and give feedback. Separate branches cover bookings, refunds, support, and policy search, with evaluation tooling for retrieval and answer quality. Some links reflect README documentation or SOURCE INDEX references rather than inspected call sites; those limits are noted in the evidence fields.

Main entry points: [`app.py`](https://github.com/guptaastha1427/trip-planner/blob/main/app.py) (Planner App), [`services/trip/agent.py`](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/agent.py) (Itinerary Agent), [`pages/portal/bookings_refunds.py`](https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/bookings_refunds.py) (Bookings & Refunds), [`services/trip/poi_search.py`](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/poi_search.py) (POI Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planner["Trip Planner"]
  node_app["Planner App<br/>[app.py]"]
  node_trip_agent["Itinerary Agent<br/>[agent.py]"]
  node_poi_search["POI Search<br/>[poi_search.py]"]
  node_trip_history[("Trip History<br/>[trip_history.py]")]
  node_feedback[("Trip Feedback<br/>[feedback.py]")]
  node_map_view["Map View<br/>[map_viz.py]"]
  node_geocoding["Geocoding<br/>[geocoding.py]"]
end

subgraph group_policy["Policy Q&amp;A"]
  node_policy_pages["Policy Pages<br/>[terms_policies.py]"]
  node_policy_rag["Policy RAG<br/>[website_rag.py]"]
  node_support_faq["Support Answers<br/>[support_faq.py]"]
  node_rag_chat_ui["Assistant UI<br/>[rag_chat_ui.py]"]
end

subgraph group_portal["Travel Portal"]
  node_support_page["Support Page<br/>[support.py]"]
  node_rag_auth[("Assistant Auth<br/>[rag_chat_auth.py]")]
  node_bookings_page["Bookings &amp; Refunds"]
  node_booking_rules["Booking &amp; Refund Logic<br/>[bookings.py]"]
  node_refund_eligibility["Refund Eligibility"]
  node_portal_store[("Portal State")]
  node_account_pages["Account &amp; Admin<br/>[account_status.py]"]
  node_portal_user["Portal User Context"]
end

subgraph group_shared["Shared Services"]
  node_validation["Input Validation<br/>[validation.py]"]
  node_http_client["HTTP Client<br/>[http_client.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["RAG Evaluation<br/>[ragas_pipeline.py]"]
  node_eval_embeddings["Eval Embeddings<br/>[real_embeddings.py]"]
  node_eval_retrieval["Eval Retrieval<br/>[terms_retrieval.py]"]
  node_eval_pipeline["Eval Orchestrator<br/>[run_pipeline.py]"]
end

node_traveler(("Traveler"))
node_osm{{"OpenStreetMap"}}
node_gemini{{"Gemini"}}

node_traveler -->|"enters"| node_app
node_app -->|"validates inputs"| node_validation
node_app -->|"runs itinerary"| node_trip_agent
node_trip_agent -->|"searches places"| node_poi_search
node_trip_agent -->|"validates places"| node_validation
node_poi_search -->|"resolves location"| node_geocoding
node_geocoding -->|"requests data"| node_http_client
node_poi_search -->|"requests places"| node_http_client
node_http_client -->|"queries"| node_osm
node_trip_agent -->|"generates itinerary"| node_gemini
node_app -->|"saves trips"| node_trip_history
node_app -->|"records feedback"| node_feedback
node_app -->|"renders map"| node_map_view
node_traveler -->|"opens policies"| node_policy_pages
node_policy_pages -.->|"searches policies"| node_policy_rag
node_traveler -->|"opens support"| node_support_page
node_support_page -.->|"answers questions"| node_support_faq
node_support_page -.->|"offers assistant"| node_rag_chat_ui
node_rag_chat_ui -->|"checks session"| node_rag_auth
node_policy_rag -->|"embeds and answers"| node_gemini
node_traveler -->|"manages bookings"| node_bookings_page
node_bookings_page -->|"loads booking logic"| node_booking_rules
node_bookings_page -->|"checks eligibility"| node_refund_eligibility
node_bookings_page -->|"reads and writes"| node_portal_store
node_traveler -->|"views account"| node_account_pages
node_account_pages -.->|"resolves customer"| node_portal_user
node_portal_user -->|"reads profiles"| node_portal_store
node_eval_pipeline -->|"runs evaluations"| node_eval_runner
node_eval_runner -->|"builds eval index"| node_eval_embeddings
node_eval_runner -->|"measures retrieval"| node_eval_retrieval
node_eval_retrieval -->|"uses retrieval logic"| node_policy_rag

click node_app "https://github.com/guptaastha1427/trip-planner/blob/main/app.py"
click node_trip_agent "https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/agent.py"
click node_poi_search "https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/poi_search.py"
click node_validation "https://github.com/guptaastha1427/trip-planner/blob/main/services/core/validation.py"
click node_trip_history "https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/trip_history.py"
click node_feedback "https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/feedback.py"
click node_map_view "https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/map_viz.py"
click node_geocoding "https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/geocoding.py"
click node_http_client "https://github.com/guptaastha1427/trip-planner/blob/main/services/core/http_client.py"
click node_policy_pages "https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/terms_policies.py"
click node_support_page "https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/support.py"
click node_policy_rag "https://github.com/guptaastha1427/trip-planner/blob/main/services/rag/website_rag.py"
click node_support_faq "https://github.com/guptaastha1427/trip-planner/blob/main/services/rag/support_faq.py"
click node_rag_chat_ui "https://github.com/guptaastha1427/trip-planner/blob/main/services/ui/rag_chat_ui.py"
click node_rag_auth "https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/rag_chat_auth.py"
click node_bookings_page "https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/bookings_refunds.py"
click node_booking_rules "https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/bookings.py"
click node_refund_eligibility "https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/refund_eligibility.py"
click node_portal_store "https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/customer_portal_store.py"
click node_account_pages "https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/account_status.py"
click node_portal_user "https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/portal_user_context.py"
click node_eval_runner "https://github.com/guptaastha1427/trip-planner/blob/main/eval/runners/ragas_pipeline.py"
click node_eval_embeddings "https://github.com/guptaastha1427/trip-planner/blob/main/eval/helpers/real_embeddings.py"
click node_eval_retrieval "https://github.com/guptaastha1427/trip-planner/blob/main/eval/helpers/terms_retrieval.py"
click node_eval_pipeline "https://github.com/guptaastha1427/trip-planner/blob/main/eval/run_pipeline.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_app,node_trip_agent,node_poi_search,node_trip_history,node_feedback,node_map_view,node_geocoding toneBlue
class node_policy_pages,node_policy_rag,node_support_faq,node_rag_chat_ui toneAmber
class node_support_page,node_rag_auth,node_bookings_page,node_booking_rules,node_refund_eligibility,node_portal_store,node_account_pages,node_portal_user toneMint
class node_validation,node_http_client toneRose
class node_eval_runner,node_eval_embeddings,node_eval_retrieval,node_eval_pipeline,node_traveler,node_osm,node_gemini toneIndigo
```

## Components

### Trip Planner

- [Planner App](https://github.com/guptaastha1427/trip-planner/blob/main/app.py): `app.py`
- [Itinerary Agent](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/agent.py): `services/trip/agent.py`
- [POI Search](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/poi_search.py): `services/trip/poi_search.py`
- [Trip History](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/trip_history.py): `services/trip/trip_history.py`
- [Trip Feedback](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/feedback.py): `services/trip/feedback.py`
- [Map View](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/map_viz.py): `services/trip/map_viz.py`
- [Geocoding](https://github.com/guptaastha1427/trip-planner/blob/main/services/trip/geocoding.py): `services/trip/geocoding.py`

### Policy Q&A

- [Policy Pages](https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/terms_policies.py): `pages/portal/terms_policies.py`
- [Policy RAG](https://github.com/guptaastha1427/trip-planner/blob/main/services/rag/website_rag.py): `services/rag/website_rag.py`
- [Support Answers](https://github.com/guptaastha1427/trip-planner/blob/main/services/rag/support_faq.py): `services/rag/support_faq.py`
- [Assistant UI](https://github.com/guptaastha1427/trip-planner/blob/main/services/ui/rag_chat_ui.py): `services/ui/rag_chat_ui.py`

### Travel Portal

- [Support Page](https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/support.py): `pages/portal/support.py`
- [Assistant Auth](https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/rag_chat_auth.py): `services/portal/rag_chat_auth.py`
- [Bookings & Refunds](https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/bookings_refunds.py): `pages/portal/bookings_refunds.py`
- [Booking & Refund Logic](https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/bookings.py): `services/portal/bookings.py`
- [Refund Eligibility](https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/refund_eligibility.py): `services/portal/refund_eligibility.py`
- [Portal State](https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/customer_portal_store.py): `services/portal/customer_portal_store.py`
- [Account & Admin](https://github.com/guptaastha1427/trip-planner/blob/main/pages/portal/account_status.py): `pages/portal/account_status.py`
- [Portal User Context](https://github.com/guptaastha1427/trip-planner/blob/main/services/portal/portal_user_context.py): `services/portal/portal_user_context.py`

### Shared Services

- [Input Validation](https://github.com/guptaastha1427/trip-planner/blob/main/services/core/validation.py): `services/core/validation.py`
- [HTTP Client](https://github.com/guptaastha1427/trip-planner/blob/main/services/core/http_client.py): `services/core/http_client.py`

### Evaluation

- [RAG Evaluation](https://github.com/guptaastha1427/trip-planner/blob/main/eval/runners/ragas_pipeline.py): `eval/runners/ragas_pipeline.py`
- [Eval Embeddings](https://github.com/guptaastha1427/trip-planner/blob/main/eval/helpers/real_embeddings.py): `eval/helpers/real_embeddings.py`
- [Eval Retrieval](https://github.com/guptaastha1427/trip-planner/blob/main/eval/helpers/terms_retrieval.py): `eval/helpers/terms_retrieval.py`
- [Eval Orchestrator](https://github.com/guptaastha1427/trip-planner/blob/main/eval/run_pipeline.py): `eval/run_pipeline.py`

### Other components

- **Traveler**
- **OpenStreetMap**
- **Gemini**

## Connections

- Traveler → Planner App: enters (evidence: `README.md`)
- Planner App → Input Validation: validates inputs (evidence: `app.py`)
- Planner App → Itinerary Agent: runs itinerary (evidence: `app.py`)
- Itinerary Agent → POI Search: searches places (evidence: `services/trip/agent.py`)
- Itinerary Agent → Input Validation: validates places (evidence: `services/trip/agent.py`)
- POI Search → Geocoding: resolves location (evidence: `services/trip/poi_search.py`)
- Geocoding → HTTP Client: requests data (evidence: `services/trip/geocoding.py`)
- POI Search → HTTP Client: requests places (evidence: `services/trip/poi_search.py`)
- HTTP Client → OpenStreetMap: queries (evidence: `services/core/http_client.py`)
- Itinerary Agent → Gemini: generates itinerary (evidence: `README.md`)
- Planner App → Trip History: saves trips (evidence: `app.py`)
- Planner App → Trip Feedback: records feedback (evidence: `README.md`)
- Planner App → Map View: renders map (evidence: `app.py`)
- Traveler → Policy Pages: opens policies (evidence: `README.md`)
- Policy Pages → Policy RAG: searches policies
- Traveler → Support Page: opens support (evidence: `README.md`)
- Support Page → Support Answers: answers questions
- Support Page → Assistant UI: offers assistant
- Assistant UI → Assistant Auth: checks session (evidence: `services/ui/rag_chat_ui.py`)
- Policy RAG → Gemini: embeds and answers (evidence: `README.md`)
- Traveler → Bookings & Refunds: manages bookings (evidence: `README.md`)
- Bookings & Refunds → Booking & Refund Logic: loads booking logic (evidence: `pages/portal/bookings_refunds.py`)
- Bookings & Refunds → Refund Eligibility: checks eligibility (evidence: `pages/portal/bookings_refunds.py`)
- Bookings & Refunds → Portal State: reads and writes (evidence: `pages/portal/bookings_refunds.py`)
- Traveler → Account & Admin: views account (evidence: `README.md`)
- Account & Admin → Portal User Context: resolves customer
- Portal User Context → Portal State: reads profiles (evidence: `services/portal/portal_user_context.py`)
- Eval Orchestrator → RAG Evaluation: runs evaluations (evidence: `eval/run_pipeline.py`)
- RAG Evaluation → Eval Embeddings: builds eval index (evidence: `eval/runners/ragas_pipeline.py`)
- RAG Evaluation → Eval Retrieval: measures retrieval (evidence: `eval/runners/ragas_pipeline.py`)
- Eval Retrieval → Policy RAG: uses retrieval logic (evidence: `eval/helpers/terms_retrieval.py`)
