praveen-kumar625/trip-planner

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.