# praveen-kumar625/trip-planner architecture

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

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

## Overview

1. **Overall shape**
   - This is a two-tier trip-planning product: a **Python backend API** and a **React/Vite frontend**.
   - The backend owns trip generation, itinerary storage, finance logic, auth, and external integrations.
   - The frontend owns user interaction, trip planning UX, dashboards, maps, and chat-style concierge experiences.

2. **Backend layering**
   - The backend is organized into **core infrastructure**, **domain modules**, **LLM orchestration**, and **provider adapters**.
   - Requests enter through `backend/main.py` / `backend/run.py`, then flow into module routers, services, and repositories.
   - This separation makes it easy to diagram a clean boundary between HTTP/API, business logic, persistence, and third-party services.

3. **Core infrastructure**
   - `backend/core` contains cross-cutting concerns: environment loading, database access, cache, HTTP helpers, auth/security, and in-memory/thread-local utilities.
   - These are shared by multiple modules rather than owned by a single feature.
   - `core/http.py`, `core/database.py`, and `core/cache.py` are the main plumbing layers for external requests and persistence.

4. **Domain modules on the backend**
   - The backend is split into feature modules: **auth**, **user**, **trip**, **itinerary**, **finance**, and **system**.
   - Each module typically has a router plus a service/repository split, showing a classic controller-service-data boundary.
   - `system/router.py` likely exposes health or operational endpoints, while the others map to product features.

5. **Trip-planning engine**
   - The `backend/modules/trip` package is the most distinctive subsystem.
   - It includes a **multi-agent workflow** under `agents/` with specialized roles such as destination, transport, accommodation, meals, budget, planner, and finalize.
   - `graph.py`, `orchestrator.py`, `prompts.py`, and `profile_updater.py` suggest a coordinated LLM-driven planning pipeline that assembles a full trip plan from smaller decision stages.

6. **LLM abstraction**
   - `backend/llm/factory.py` centralizes model/provider selection.
   - The trip agents appear to depend on this layer rather than calling a model directly, which keeps model choice and prompting separated from business orchestration.
   - The tests include LLM reliability coverage, so AI behavior is treated as a first-class integration boundary.

7. **Persistence and domain models**
   - `backend/models/user.py` and `backend/models/itinerary.py` define the core persisted entities.
   - Repositories under `auth`, `user`, `trip`, and `itinerary` handle data access behind the service layer.
   - This suggests the backend persists user/trip state independently of the frontend, with itinerary generation and edits stored server-side.

8. **External service adapters**
   - `backend/providers/google` wraps Google Directions and Places, while `backend/providers/weather/openweather.py` integrates weather data.
   - These adapters are separate from the trip logic, so the trip engine can combine LLM reasoning with live travel data.
   - This is an important architecture boundary: product logic stays inside `modules/trip`, while vendor-specific calls stay in `providers/`.

9. **Frontend application structure**
   - The frontend is a React app built with Vite and organized by **app shell**, **pages**, **feature folders**, **shared components**, and **global state**.
   - `src/app` contains routing and providers; `src/pages` contains top-level screens like landing, dashboard, planner, and trip pages.
   - `src/features` groups major product areas: auth, concierge chat, finance, itinerary/map, stories, and trip management.

10. **Frontend data flow**
    - UI components call feature services such as `tripService.js`, `financeService.js`, and `authService.js`, which in turn talk to `src/services/apiClient.js`.
    - State is shared through stores like `authStore.js` and `financeStore.js`, with hooks wrapping common feature behavior.
    - This gives a clear flow: **page/component → hook/store → service → API client → backend**.

11. **Client-side integrations**
    - `src/core/firebase.js` shows a frontend Firebase integration, likely for authentication or identity-related client setup.
    - The app also includes localization assets for **English** and **Hinglish**, indicating the UI is built for multilingual presentation.
    - 3D and map-related components suggest the UI is visually rich, but these are presentation concerns rather than system boundaries.

12. **Testing and validation**
    - Backend tests cover auth, user, itinerary, trip service behavior, manual edit APIs, meal reliability, and weather mocking.
    - The frontend includes at least store-level tests and a test setup harness.
    - GitHub Actions validation plus Ruff/Pytest/Vite tooling indicate the repo is designed for automated quality checks across both tiers.

Main entry points: [`TRIP/backend/main.py`](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/main.py) (API entry), [`TRIP/tests`](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/tests) (Tests), [`TRIP/backend/modules/trip/service.py`](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/service.py) (Trip service), [`TRIP/frontend/src/app`](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/app) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_entry["API entry<br/>[main.py]"]
  node_backend_core["Core infra<br/>shared infrastructure"]
  node_backend_llm["LLM factory<br/>model abstraction<br/>[factory.py]"]
  node_backend_auth["Auth module<br/>user auth"]
  node_backend_user["User module<br/>profile management"]
  node_backend_trip_api["Trip API<br/>trip endpoints<br/>[router.py]"]
  node_backend_trip_service["Trip service<br/>trip orchestration<br/>[service.py]"]
  node_backend_trip_agents["Trip agents<br/>multi-agent pipeline"]
  node_backend_trip_graph["Trip graph<br/>workflow graph<br/>[graph.py]"]
  node_backend_itinerary["Itinerary module<br/>itinerary storage"]
  node_backend_finance["Finance module<br/>budgeting"]
  node_backend_system["System module<br/>ops endpoints<br/>[router.py]"]
  node_backend_providers["Providers<br/>external adapters"]
  node_backend_models["Domain models<br/>persistence models"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React shell"]
  node_frontend_pages["Pages<br/>screen layer"]
  node_frontend_features["Features<br/>feature modules"]
  node_frontend_services["API client<br/>client transport<br/>[apiClient.js]"]
  node_frontend_state["Stores<br/>client state"]
  node_frontend_core["Client core<br/>shared setup"]
  node_frontend_i18n["Localization<br/>translations"]
end

subgraph group_tests["Validation"]
  node_tests_suite["Tests"]
  node_ci_workflow["CI workflow<br/>github actions<br/>[validation.yml]"]
end

node_backend_entry -->|"uses infra"| node_backend_core
node_backend_entry -->|"mounts"| node_backend_auth
node_backend_entry -->|"mounts"| node_backend_user
node_backend_entry -->|"mounts"| node_backend_trip_api
node_backend_entry -->|"mounts"| node_backend_itinerary
node_backend_entry -->|"mounts"| node_backend_finance
node_backend_entry -->|"mounts"| node_backend_system
node_backend_auth -->|"auth helpers"| node_backend_core
node_backend_user -->|"uses infra"| node_backend_core
node_backend_trip_service -->|"orchestrates"| node_backend_trip_agents
node_backend_trip_service -->|"drives"| node_backend_trip_graph
node_backend_trip_agents -->|"calls models"| node_backend_llm
node_backend_trip_service -->|"fetches travel data"| node_backend_providers
node_backend_itinerary -->|"persists"| node_backend_models
node_backend_user -->|"persists"| node_backend_models
node_frontend_app -->|"routes to"| node_frontend_pages
node_frontend_pages -->|"composes"| node_frontend_features
node_frontend_features -->|"API calls"| node_frontend_services
node_frontend_features -->|"shares state"| node_frontend_state
node_frontend_app -->|"boots"| node_frontend_core
node_frontend_app -->|"localizes"| node_frontend_i18n
node_tests_suite -.->|"covers"| node_backend_trip_service
node_tests_suite -.->|"covers"| node_backend_auth
node_tests_suite -.->|"covers"| node_backend_itinerary
node_tests_suite -.->|"covers"| node_frontend_state
node_ci_workflow -.->|"runs"| node_tests_suite

click node_backend_entry "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/main.py"
click node_backend_core "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/core"
click node_backend_llm "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/llm/factory.py"
click node_backend_auth "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/auth"
click node_backend_user "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/user"
click node_backend_trip_api "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/router.py"
click node_backend_trip_service "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/service.py"
click node_backend_trip_agents "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/trip/agents"
click node_backend_trip_graph "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/graph.py"
click node_backend_itinerary "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/itinerary"
click node_backend_finance "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/finance"
click node_backend_system "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/system/router.py"
click node_backend_providers "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/providers"
click node_backend_models "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/models"
click node_frontend_app "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/app"
click node_frontend_pages "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/pages"
click node_frontend_features "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/features"
click node_frontend_services "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/frontend/src/services/apiClient.js"
click node_frontend_state "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/store"
click node_frontend_core "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/core"
click node_frontend_i18n "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/public/locales"
click node_tests_suite "https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/tests"
click node_ci_workflow "https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/.github/workflows/validation.yml"

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_backend_entry,node_backend_core,node_backend_llm,node_backend_auth,node_backend_user,node_backend_trip_api,node_backend_trip_service,node_backend_trip_agents,node_backend_trip_graph,node_backend_itinerary,node_backend_finance,node_backend_system,node_backend_providers,node_backend_models toneBlue
class node_frontend_app,node_frontend_pages,node_frontend_features,node_frontend_services,node_frontend_state,node_frontend_core,node_frontend_i18n toneAmber
class node_tests_suite,node_ci_workflow toneMint
```

## Components

### Backend

Python API, orchestration, persistence, and external adapters

- [API entry](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/main.py): FastAPI entrypoint · Bootstraps the backend app and request lifecycle · `TRIP/backend/main.py`
- [Core infra](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/core): shared infrastructure · Cross-cutting helpers for env, auth, cache, DB, HTTP, and memory utilities · `TRIP/backend/core`
- [LLM factory](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/llm/factory.py): model abstraction · Centralizes model/provider selection for AI-driven planning · `TRIP/backend/llm/factory.py`
- [Auth module](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/auth): user auth · Authentication routes, service logic, and data access · `TRIP/backend/modules/auth`
- [User module](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/user): profile management · User profile routes, service logic, and persistence · `TRIP/backend/modules/user`
- [Trip API](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/router.py): trip endpoints · HTTP surface for trip planning, editing, and retrieval · `TRIP/backend/modules/trip/router.py`
- [Trip service](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/service.py): trip orchestration · Coordinates trip generation and trip-domain workflows · `TRIP/backend/modules/trip/service.py`
- [Trip agents](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/trip/agents): multi-agent pipeline · Specialized destination, transport, accommodation, meals, budget, planner, and finalize agents · `TRIP/backend/modules/trip/agents`
- [Trip graph](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/trip/graph.py): workflow graph · Defines the execution graph for the planning pipeline · `TRIP/backend/modules/trip/graph.py`
- [Itinerary module](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/itinerary): itinerary storage · Itinerary routes, service logic, and repository access · `TRIP/backend/modules/itinerary`
- [Finance module](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/modules/finance): budgeting · Finance endpoints and budget schemas for trip spending · `TRIP/backend/modules/finance`
- [System module](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/backend/modules/system/router.py): ops endpoints · Operational endpoints such as health or system status · `TRIP/backend/modules/system/router.py`
- [Providers](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/providers): external adapters · Vendor integrations for places, directions, and weather data · `TRIP/backend/providers`
- [Domain models](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/backend/models): persistence models · Core persisted entities for users and itineraries · `TRIP/backend/models`

### Frontend

React/Vite app, feature UI, and client-side state

- [App shell](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/app): React shell · Top-level routing, providers, and app composition · `TRIP/frontend/src/app`
- [Pages](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/pages): screen layer · Landing, dashboard, planner, and trip-level screens · `TRIP/frontend/src/pages`
- [Features](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/features): feature modules · Auth, concierge, finance, itinerary, stories, and trip UI modules · `TRIP/frontend/src/features`
- [API client](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/frontend/src/services/apiClient.js): client transport · Shared HTTP client and service wrappers for backend calls · `TRIP/frontend/src/services/apiClient.js`
- [Stores](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/store): client state · Global UI state for auth and finance workflows · `TRIP/frontend/src/store`
- [Client core](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/src/core): shared setup · Firebase, theming, and error boundary setup · `TRIP/frontend/src/core`
- [Localization](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/frontend/public/locales): translations · English and Hinglish translation assets for the UI · `TRIP/frontend/public/locales`

### Validation

Automated test and CI coverage

- [Tests](https://github.com/praveen-kumar625/trip-planner/tree/main/TRIP/tests): pytest/vite tests · Backend service tests, API behavior checks, and frontend store tests · `TRIP/tests`
- [CI workflow](https://github.com/praveen-kumar625/trip-planner/blob/main/TRIP/.github/workflows/validation.yml): github actions · Validation pipeline for linting, tests, and build checks · `TRIP/.github/workflows/validation.yml`

## Connections

- API entry → Core infra: uses infra · Bootstrapping depends on shared backend infrastructure
- API entry → Auth module: mounts · API entry exposes auth routes
- API entry → User module: mounts · API entry exposes user routes
- API entry → Trip API: mounts · API entry exposes trip routes
- API entry → Itinerary module: mounts · API entry exposes itinerary routes
- API entry → Finance module: mounts · API entry exposes finance routes
- API entry → System module: mounts · API entry exposes system routes
- Auth module → Core infra: auth helpers · Auth depends on security, DB, and HTTP helpers
- User module → Core infra: uses infra · User services use shared backend plumbing
- Trip service → Trip agents: orchestrates · Trip service coordinates the planning agents
- Trip service → Trip graph: drives · Service uses the workflow graph to run planning stages
- Trip agents → LLM factory: calls models · Agents obtain model instances through the LLM factory
- Trip service → Providers: fetches travel data · Trip planning combines live places, directions, and weather data
- Itinerary module → Domain models: persists · Itinerary module stores and reads persisted domain entities
- User module → Domain models: persists · User module works with user domain entities
- App shell → Pages: routes to · App shell wires page-level screens
- Pages → Features: composes · Pages assemble feature modules into screens
- Features → API client: API calls · Feature modules talk to the shared API client layer
- Features → Stores: shares state · Feature modules read and update global stores
- App shell → Client core: boots · App shell applies core providers and error handling
- App shell → Localization: localizes · App shell loads translation resources
- Tests → Trip service: covers · Tests validate trip planning behavior and reliability
- Tests → Auth module: covers · Tests validate authentication flows
- Tests → Itinerary module: covers · Tests validate itinerary APIs and edits
- Tests → Stores: covers · Frontend tests cover store behavior
- CI workflow → Tests: runs · CI executes the repository validation suite