# hpy137/tripstar architecture

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

- Interactive diagram: https://gitdiagram.com/hpy137/tripstar
- Repository: https://github.com/hpy137/tripstar

## Overview

TripStar is an AI travel-planning application: users submit trip dates, cities and preferences, then receive an asynchronously generated itinerary with budget, weather, lodging, route/map and attraction details. The backend enriches attraction recommendations from Xiaohongshu, coordinates map-provider lookups, generates the plan with an LLM, and derives a localized knowledge graph. The result view also supports itinerary-context chat, attraction photos and map visualization; preference memory is a separate optional capability. The README documents these branches, but several route and planner implementations were not sampled, so only documented orchestration links are shown.

Main entry points: [`backend/app/api/main.py`](https://github.com/hpy137/tripstar/blob/main/backend/app/api/main.py) (FastAPI app), [`frontend/src/services/api.ts`](https://github.com/hpy137/tripstar/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/agents/trip_planner_agent.py`](https://github.com/hpy137/tripstar/blob/main/backend/app/agents/trip_planner_agent.py) (Trip planner agent), [`backend/app/services/xhs_service.py`](https://github.com/hpy137/tripstar/blob/main/backend/app/services/xhs_service.py) (Xiaohongshu search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Trip interface"]
  node_landing["Trip setup<br/>[Landing.vue]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_result_view["Trip results<br/>[Result.vue]"]
  node_chat_ui["Trip chat<br/>[AIChat.vue]"]
  node_frontend_i18n["Localization<br/>[index.ts]"]
end

subgraph group_api["API layer"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_trip_routes["Trip tasks<br/>[trip.py]"]
  node_poi_routes["Attraction photos<br/>[poi.py]"]
  node_chat_routes["Chat endpoint<br/>[chat.py]"]
  node_map_routes["Map endpoint<br/>[map.py]"]
  node_settings_routes["Runtime settings<br/>[settings.py]"]
end

subgraph group_planning["Planning services"]
  node_planner["Trip planner agent"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_llm["LLM adapter<br/>[llm_service.py]"]
  node_knowledge_graph["Knowledge graph"]
end

subgraph group_integrations["External data"]
  node_xhs["Xiaohongshu search<br/>[xhs_service.py]"]
  node_map_dispatcher["Map dispatcher<br/>[map_dispatcher.py]"]
  node_amap["AMap service<br/>[amap_service.py]"]
  node_google_maps["Google Maps"]
end

subgraph group_memory["Preference memory"]
  node_memory_routes["Memory API<br/>[memory_routes.py]"]
  node_memory_manager["Memory manager<br/>[memory_manager.py]"]
  node_memory_store[("Memory store<br/>[sqlite_store.py]")]
end

node_traveler(("Traveler"))
node_xhs_service{{"Xiaohongshu"}}
node_llm_service{{"LLM provider"}}
node_maps_provider{{"Map providers"}}

node_traveler -->|"enters trip details"| node_landing
node_landing -->|"submits plan"| node_frontend_api
node_frontend_api -->|"sends API requests"| node_fastapi
node_fastapi -->|"dispatches trip routes"| node_trip_routes
node_fastapi -->|"dispatches photo routes"| node_poi_routes
node_fastapi -->|"dispatches chat routes"| node_chat_routes
node_fastapi -->|"dispatches map routes"| node_map_routes
node_fastapi -->|"dispatches settings"| node_settings_routes
node_fastapi -->|"dispatches memory routes"| node_memory_routes
node_trip_routes -->|"starts planning task"| node_planner
node_planner -->|"searches attractions"| node_xhs
node_planner -->|"requests weather and lodging"| node_map_dispatcher
node_planner -->|"generates itinerary"| node_llm
node_planner -->|"builds graph"| node_knowledge_graph
node_xhs -->|"extracts structured attractions"| node_llm
node_xhs -->|"geocodes attractions"| node_map_dispatcher
node_xhs -->|"searches notes"| node_xhs_service
node_poi_routes -->|"requests attraction photo"| node_xhs
node_map_dispatcher -->|"selects or falls back"| node_amap
node_map_dispatcher -->|"selects or falls back"| node_google_maps
node_amap -->|"queries maps and weather"| node_maps_provider
node_google_maps -->|"queries maps and weather"| node_maps_provider
node_llm -->|"invokes model API"| node_llm_service
node_trip_routes -->|"returns task status"| node_frontend_api
node_frontend_api -->|"supplies plan result"| node_result_view
node_result_view -->|"polls task status"| node_frontend_api
node_result_view -->|"loads attraction photos"| node_poi_routes
node_result_view -->|"shows itinerary chat"| node_chat_ui
node_chat_ui -->|"sends chat requests"| node_frontend_api
node_chat_routes -->|"handles chat"| node_chat_service
node_chat_service -->|"generates reply"| node_llm
node_memory_routes -->|"recalls and edits preferences"| node_memory_manager
node_memory_manager -->|"reads and writes memories"| node_memory_store

click node_landing "https://github.com/hpy137/tripstar/blob/main/frontend/src/views/Landing.vue"
click node_frontend_api "https://github.com/hpy137/tripstar/blob/main/frontend/src/services/api.ts"
click node_result_view "https://github.com/hpy137/tripstar/blob/main/frontend/src/views/Result.vue"
click node_chat_ui "https://github.com/hpy137/tripstar/blob/main/frontend/src/components/AIChat.vue"
click node_frontend_i18n "https://github.com/hpy137/tripstar/blob/main/frontend/src/i18n/index.ts"
click node_fastapi "https://github.com/hpy137/tripstar/blob/main/backend/app/api/main.py"
click node_trip_routes "https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/trip.py"
click node_poi_routes "https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/poi.py"
click node_chat_routes "https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/chat.py"
click node_map_routes "https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/map.py"
click node_settings_routes "https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/settings.py"
click node_planner "https://github.com/hpy137/tripstar/blob/main/backend/app/agents/trip_planner_agent.py"
click node_chat_service "https://github.com/hpy137/tripstar/blob/main/backend/app/services/chat_service.py"
click node_llm "https://github.com/hpy137/tripstar/blob/main/backend/app/services/llm_service.py"
click node_knowledge_graph "https://github.com/hpy137/tripstar/blob/main/backend/app/services/knowledge_graph_service.py"
click node_xhs "https://github.com/hpy137/tripstar/blob/main/backend/app/services/xhs_service.py"
click node_map_dispatcher "https://github.com/hpy137/tripstar/blob/main/backend/app/services/map_dispatcher.py"
click node_amap "https://github.com/hpy137/tripstar/blob/main/backend/app/services/amap_service.py"
click node_google_maps "https://github.com/hpy137/tripstar/blob/main/backend/app/services/google_map_service.py"
click node_memory_routes "https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/memory_routes.py"
click node_memory_manager "https://github.com/hpy137/tripstar/blob/main/backend/app/memory/memory_manager.py"
click node_memory_store "https://github.com/hpy137/tripstar/blob/main/backend/app/memory/sqlite_store.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_landing,node_frontend_api,node_result_view,node_chat_ui,node_frontend_i18n toneBlue
class node_fastapi,node_trip_routes,node_poi_routes,node_chat_routes,node_map_routes,node_settings_routes toneAmber
class node_planner,node_chat_service,node_llm,node_knowledge_graph toneMint
class node_xhs,node_map_dispatcher,node_amap,node_google_maps toneRose
class node_memory_routes,node_memory_manager,node_memory_store,node_traveler,node_xhs_service,node_llm_service,node_maps_provider toneIndigo
```

## Components

### Trip interface

- [Trip setup](https://github.com/hpy137/tripstar/blob/main/frontend/src/views/Landing.vue): `frontend/src/views/Landing.vue`
- [API client](https://github.com/hpy137/tripstar/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Trip results](https://github.com/hpy137/tripstar/blob/main/frontend/src/views/Result.vue): `frontend/src/views/Result.vue`
- [Trip chat](https://github.com/hpy137/tripstar/blob/main/frontend/src/components/AIChat.vue): `frontend/src/components/AIChat.vue`
- [Localization](https://github.com/hpy137/tripstar/blob/main/frontend/src/i18n/index.ts): `frontend/src/i18n/index.ts`

### API layer

- [FastAPI app](https://github.com/hpy137/tripstar/blob/main/backend/app/api/main.py): `backend/app/api/main.py`
- [Trip tasks](https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/trip.py): `backend/app/api/routes/trip.py`
- [Attraction photos](https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/poi.py): `backend/app/api/routes/poi.py`
- [Chat endpoint](https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/chat.py): `backend/app/api/routes/chat.py`
- [Map endpoint](https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/map.py): `backend/app/api/routes/map.py`
- [Runtime settings](https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/settings.py): `backend/app/api/routes/settings.py`

### Planning services

- [Trip planner agent](https://github.com/hpy137/tripstar/blob/main/backend/app/agents/trip_planner_agent.py): `backend/app/agents/trip_planner_agent.py`
- [Chat service](https://github.com/hpy137/tripstar/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [LLM adapter](https://github.com/hpy137/tripstar/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`
- [Knowledge graph](https://github.com/hpy137/tripstar/blob/main/backend/app/services/knowledge_graph_service.py): `backend/app/services/knowledge_graph_service.py`

### External data

- [Xiaohongshu search](https://github.com/hpy137/tripstar/blob/main/backend/app/services/xhs_service.py): `backend/app/services/xhs_service.py`
- [Map dispatcher](https://github.com/hpy137/tripstar/blob/main/backend/app/services/map_dispatcher.py): `backend/app/services/map_dispatcher.py`
- [AMap service](https://github.com/hpy137/tripstar/blob/main/backend/app/services/amap_service.py): `backend/app/services/amap_service.py`
- [Google Maps](https://github.com/hpy137/tripstar/blob/main/backend/app/services/google_map_service.py): `backend/app/services/google_map_service.py`

### Preference memory

- [Memory API](https://github.com/hpy137/tripstar/blob/main/backend/app/api/routes/memory_routes.py): `backend/app/api/routes/memory_routes.py`
- [Memory manager](https://github.com/hpy137/tripstar/blob/main/backend/app/memory/memory_manager.py): `backend/app/memory/memory_manager.py`
- [Memory store](https://github.com/hpy137/tripstar/blob/main/backend/app/memory/sqlite_store.py): `backend/app/memory/sqlite_store.py`

### Other components

- **Traveler**
- **Xiaohongshu**
- **LLM provider**
- **Map providers**

## Connections

- Traveler → Trip setup: enters trip details
- Trip setup → API client: submits plan
- API client → FastAPI app: sends API requests
- FastAPI app → Trip tasks: dispatches trip routes
- FastAPI app → Attraction photos: dispatches photo routes
- FastAPI app → Chat endpoint: dispatches chat routes
- FastAPI app → Map endpoint: dispatches map routes
- FastAPI app → Runtime settings: dispatches settings
- FastAPI app → Memory API: dispatches memory routes
- Trip tasks → Trip planner agent: starts planning task
- Trip planner agent → Xiaohongshu search: searches attractions
- Trip planner agent → Map dispatcher: requests weather and lodging
- Trip planner agent → LLM adapter: generates itinerary
- Trip planner agent → Knowledge graph: builds graph
- Xiaohongshu search → LLM adapter: extracts structured attractions
- Xiaohongshu search → Map dispatcher: geocodes attractions
- Xiaohongshu search → Xiaohongshu: searches notes
- Attraction photos → Xiaohongshu search: requests attraction photo
- Map dispatcher → AMap service: selects or falls back
- Map dispatcher → Google Maps: selects or falls back
- AMap service → Map providers: queries maps and weather
- Google Maps → Map providers: queries maps and weather
- LLM adapter → LLM provider: invokes model API
- Trip tasks → API client: returns task status
- API client → Trip results: supplies plan result
- Trip results → API client: polls task status
- Trip results → Attraction photos: loads attraction photos
- Trip results → Trip chat: shows itinerary chat
- Trip chat → API client: sends chat requests
- Chat endpoint → Chat service: handles chat
- Chat service → LLM adapter: generates reply
- Memory API → Memory manager: recalls and edits preferences
- Memory manager → Memory store: reads and writes memories