# uday2319/citywise architecture

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

- Interactive diagram: https://gitdiagram.com/uday2319/citywise
- Repository: https://github.com/uday2319/citywise

## Overview

CityWise turns a traveller’s preferences into a day-by-day trip plan, then presents it in a workspace for mapping and editing. The documented planning stages are live-place discovery, semantic matching, ranking, scheduling, hotel-based ordering, and meal completion. The React app also supports destination discovery, saved trips and favorites, and an always-available voice translator. The README documents these capabilities; backend route wiring and several frontend pages were not sampled, so their detailed call relationships are not asserted.

Main entry points: [`backend/services/ml_service.py`](https://github.com/uday2319/citywise/blob/main/backend/services/ml_service.py) (Itinerary orchestration), [`frontend/src/api/itineraApi.ts`](https://github.com/uday2319/citywise/blob/main/frontend/src/api/itineraApi.ts) (API client), [`frontend/src/App.tsx`](https://github.com/uday2319/citywise/blob/main/frontend/src/App.tsx) (App routing and providers), [`frontend/src/pages/Discover.tsx`](https://github.com/uday2319/citywise/blob/main/frontend/src/pages/Discover.tsx) (Discover and explore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Travel app"]
  node_app["App routing and providers<br/>[App.tsx]"]
  node_trip_ui["Trip workspace<br/>[TripView.tsx]"]
  node_browse_ui["Discover and explore<br/>[Discover.tsx]"]
  node_saved_ui["Trips and favorites<br/>[Trips.tsx]"]
  node_translator_ui["Voice translator"]
  node_trip_state["Trip state<br/>[TripContext.tsx]"]
end

subgraph group_api["Backend services"]
  node_api_client["API client<br/>[itineraApi.ts]"]
  node_itinerary_api["Itinerary endpoint<br/>[itinerary.py]"]
  node_discovery_apis["Discovery and info endpoints"]
  node_routing_api["Road routing endpoint<br/>[routing.py]"]
  node_translate_api["Translation endpoint<br/>[translate.py]"]
  node_geo["Live place services<br/>[geo_service.py]"]
  node_translator["Translation service"]
  node_weather["Weather endpoint<br/>[weather.py]"]
  node_media["Place photos endpoint<br/>[media.py]"]
end

subgraph group_planning["Itinerary planning"]
  node_ml_service["Itinerary orchestration<br/>[ml_service.py]"]
  node_scheduler["Day scheduler<br/>[day_scheduler.py]"]
  node_optimizer["Route optimization<br/>[route_optimizer.py]"]
end

subgraph group_ml["Recommendation engine"]
  node_semantic["Semantic matching<br/>[semantic_search.py]"]
  node_ranker["Candidate ranking<br/>[train_ranker.py]"]
  node_restaurants["Restaurant recommendations"]
end

subgraph group_support["Trip utilities"]
  node_local_storage[("Browser storage<br/>[storage.ts]")]
  node_worker["Async itinerary task<br/>[tasks.py]"]
  node_database[("Database sessions<br/>[database.py]")]
end

node_traveller(("Traveller"))

node_traveller -->|"uses"| node_app
node_app -->|"routes to"| node_trip_ui
node_app -->|"routes to"| node_browse_ui
node_app -->|"routes to"| node_saved_ui
node_app -->|"provides state"| node_trip_state
node_trip_ui -.->|"edits"| node_trip_state
node_trip_state -.->|"persists"| node_local_storage
node_trip_ui -->|"requests routes"| node_api_client
node_api_client -.->|"requests plan"| node_itinerary_api
node_api_client -.->|"requests places"| node_discovery_apis
node_api_client -->|"requests road route"| node_routing_api
node_api_client -.->|"requests translation"| node_translate_api
node_itinerary_api -.->|"generates plan"| node_ml_service
node_ml_service -->|"fetches places"| node_geo
node_ml_service -->|"matches candidates"| node_semantic
node_ml_service -->|"reranks candidates"| node_ranker
node_ml_service -->|"builds days"| node_scheduler
node_scheduler -->|"optimizes day route"| node_optimizer
node_ml_service -->|"fetches meals and hotels"| node_geo
node_ml_service -.->|"recommends meals"| node_restaurants
node_translate_api -.->|"translates text"| node_translator
node_browse_ui -.->|"searches places"| node_api_client
node_browse_ui -.->|"gets forecast"| node_weather
node_browse_ui -.->|"gets photos"| node_media
node_worker -->|"generates itinerary"| node_ml_service
node_ml_service -.->|"uses sessions"| node_database

click node_app "https://github.com/uday2319/citywise/blob/main/frontend/src/App.tsx"
click node_trip_ui "https://github.com/uday2319/citywise/blob/main/frontend/src/pages/TripView.tsx"
click node_browse_ui "https://github.com/uday2319/citywise/blob/main/frontend/src/pages/Discover.tsx"
click node_saved_ui "https://github.com/uday2319/citywise/blob/main/frontend/src/pages/Trips.tsx"
click node_translator_ui "https://github.com/uday2319/citywise/blob/main/frontend/src/components/VoiceTranslator.tsx"
click node_trip_state "https://github.com/uday2319/citywise/blob/main/frontend/src/context/TripContext.tsx"
click node_local_storage "https://github.com/uday2319/citywise/blob/main/frontend/src/lib/storage.ts"
click node_api_client "https://github.com/uday2319/citywise/blob/main/frontend/src/api/itineraApi.ts"
click node_itinerary_api "https://github.com/uday2319/citywise/blob/main/backend/api/routes/itinerary.py"
click node_discovery_apis "https://github.com/uday2319/citywise/tree/main/backend/api/routes"
click node_routing_api "https://github.com/uday2319/citywise/blob/main/backend/api/routes/routing.py"
click node_translate_api "https://github.com/uday2319/citywise/blob/main/backend/api/routes/translate.py"
click node_geo "https://github.com/uday2319/citywise/blob/main/backend/services/geo_service.py"
click node_ml_service "https://github.com/uday2319/citywise/blob/main/backend/services/ml_service.py"
click node_semantic "https://github.com/uday2319/citywise/blob/main/ml/recommender/semantic_search.py"
click node_ranker "https://github.com/uday2319/citywise/blob/main/ml/ranking/train_ranker.py"
click node_scheduler "https://github.com/uday2319/citywise/blob/main/ml/scheduler/day_scheduler.py"
click node_optimizer "https://github.com/uday2319/citywise/blob/main/ml/optimizer/route_optimizer.py"
click node_restaurants "https://github.com/uday2319/citywise/blob/main/ml/recommender/restaurant_recommender.py"
click node_translator "https://github.com/uday2319/citywise/blob/main/backend/services/translate_service.py"
click node_weather "https://github.com/uday2319/citywise/blob/main/backend/api/routes/weather.py"
click node_media "https://github.com/uday2319/citywise/blob/main/backend/api/routes/media.py"
click node_worker "https://github.com/uday2319/citywise/blob/main/workers/tasks.py"
click node_database "https://github.com/uday2319/citywise/blob/main/backend/core/database.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_ui,node_browse_ui,node_saved_ui,node_translator_ui,node_trip_state toneBlue
class node_api_client,node_itinerary_api,node_discovery_apis,node_routing_api,node_translate_api,node_geo,node_translator,node_weather,node_media toneAmber
class node_ml_service,node_scheduler,node_optimizer toneMint
class node_semantic,node_ranker,node_restaurants toneRose
class node_local_storage,node_worker,node_database,node_traveller toneIndigo
```

## Components

### Travel app

- [App routing and providers](https://github.com/uday2319/citywise/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Trip workspace](https://github.com/uday2319/citywise/blob/main/frontend/src/pages/TripView.tsx): `frontend/src/pages/TripView.tsx`
- [Discover and explore](https://github.com/uday2319/citywise/blob/main/frontend/src/pages/Discover.tsx): `frontend/src/pages/Discover.tsx`
- [Trips and favorites](https://github.com/uday2319/citywise/blob/main/frontend/src/pages/Trips.tsx): `frontend/src/pages/Trips.tsx`
- [Voice translator](https://github.com/uday2319/citywise/blob/main/frontend/src/components/VoiceTranslator.tsx): `frontend/src/components/VoiceTranslator.tsx`
- [Trip state](https://github.com/uday2319/citywise/blob/main/frontend/src/context/TripContext.tsx): `frontend/src/context/TripContext.tsx`

### Backend services

- [API client](https://github.com/uday2319/citywise/blob/main/frontend/src/api/itineraApi.ts): `frontend/src/api/itineraApi.ts`
- [Itinerary endpoint](https://github.com/uday2319/citywise/blob/main/backend/api/routes/itinerary.py): `backend/api/routes/itinerary.py`
- [Discovery and info endpoints](https://github.com/uday2319/citywise/tree/main/backend/api/routes): `backend/api/routes`
- [Road routing endpoint](https://github.com/uday2319/citywise/blob/main/backend/api/routes/routing.py): `backend/api/routes/routing.py`
- [Translation endpoint](https://github.com/uday2319/citywise/blob/main/backend/api/routes/translate.py): `backend/api/routes/translate.py`
- [Live place services](https://github.com/uday2319/citywise/blob/main/backend/services/geo_service.py): `backend/services/geo_service.py`
- [Translation service](https://github.com/uday2319/citywise/blob/main/backend/services/translate_service.py): `backend/services/translate_service.py`
- [Weather endpoint](https://github.com/uday2319/citywise/blob/main/backend/api/routes/weather.py): `backend/api/routes/weather.py`
- [Place photos endpoint](https://github.com/uday2319/citywise/blob/main/backend/api/routes/media.py): `backend/api/routes/media.py`

### Itinerary planning

- [Itinerary orchestration](https://github.com/uday2319/citywise/blob/main/backend/services/ml_service.py): `backend/services/ml_service.py`
- [Day scheduler](https://github.com/uday2319/citywise/blob/main/ml/scheduler/day_scheduler.py): `ml/scheduler/day_scheduler.py`
- [Route optimization](https://github.com/uday2319/citywise/blob/main/ml/optimizer/route_optimizer.py): `ml/optimizer/route_optimizer.py`

### Recommendation engine

- [Semantic matching](https://github.com/uday2319/citywise/blob/main/ml/recommender/semantic_search.py): `ml/recommender/semantic_search.py`
- [Candidate ranking](https://github.com/uday2319/citywise/blob/main/ml/ranking/train_ranker.py): `ml/ranking/train_ranker.py`
- [Restaurant recommendations](https://github.com/uday2319/citywise/blob/main/ml/recommender/restaurant_recommender.py): `ml/recommender/restaurant_recommender.py`

### Trip utilities

- [Browser storage](https://github.com/uday2319/citywise/blob/main/frontend/src/lib/storage.ts): `frontend/src/lib/storage.ts`
- [Async itinerary task](https://github.com/uday2319/citywise/blob/main/workers/tasks.py): `workers/tasks.py`
- [Database sessions](https://github.com/uday2319/citywise/blob/main/backend/core/database.py): `backend/core/database.py`

### Other components

- **Traveller**

## Connections

- Traveller → App routing and providers: uses
- App routing and providers → Trip workspace: routes to (evidence: `frontend/src/App.tsx`)
- App routing and providers → Discover and explore: routes to (evidence: `frontend/src/App.tsx`)
- App routing and providers → Trips and favorites: routes to (evidence: `frontend/src/App.tsx`)
- App routing and providers → Trip state: provides state (evidence: `frontend/src/App.tsx`)
- Trip workspace → Trip state: edits
- Trip state → Browser storage: persists
- Trip workspace → API client: requests routes
- API client → Itinerary endpoint: requests plan
- API client → Discovery and info endpoints: requests places
- API client → Road routing endpoint: requests road route
- API client → Translation endpoint: requests translation
- Itinerary endpoint → Itinerary orchestration: generates plan
- Itinerary orchestration → Live place services: fetches places (evidence: `backend/services/ml_service.py`)
- Itinerary orchestration → Semantic matching: matches candidates (evidence: `backend/services/ml_service.py`)
- Itinerary orchestration → Candidate ranking: reranks candidates (evidence: `backend/services/ml_service.py`)
- Itinerary orchestration → Day scheduler: builds days (evidence: `backend/services/ml_service.py`)
- Day scheduler → Route optimization: optimizes day route (evidence: `ml/scheduler/day_scheduler.py`)
- Itinerary orchestration → Live place services: fetches meals and hotels (evidence: `backend/services/ml_service.py`)
- Itinerary orchestration → Restaurant recommendations: recommends meals
- Translation endpoint → Translation service: translates text
- Discover and explore → API client: searches places
- Discover and explore → Weather endpoint: gets forecast
- Discover and explore → Place photos endpoint: gets photos
- Async itinerary task → Itinerary orchestration: generates itinerary (evidence: `workers/tasks.py`)
- Itinerary orchestration → Database sessions: uses sessions