# varun1323/jaunt-route-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/varun1323/jaunt-route-recommender
- Repository: https://github.com/varun1323/jaunt-route-recommender

## Overview

Jaunt is a Manhattan walking-route recommender: travelers choose landmarks and express preferences, then the app retrieves cached pedestrian routes, ranks them, and presents route details and geometry. The backend also exposes landmark data and can obtain a missing baseline through Valhalla. Geographic research and candidate access-point work support the route data, but the sampled excerpts do not establish a complete production pipeline between those utilities and the app. The graph reflects documented or excerpted connections; some UI rendering and data wiring is omitted where excerpts do not show it.

Main entry points: [`frontend/src/App.tsx`](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/App.tsx) (App state), [`backend/app.py`](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/app.py) (Jaunt API), [`backend/scripts/recommendation_engine.py`](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/recommendation_engine.py) (Recommendation engine), [`backend/scripts/fetch_routes.py`](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/fetch_routes.py) (Route fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Traveler experience"]
  node_app["App state<br/>[App.tsx]"]
  node_journey["Journey selector"]
  node_preference["Preference input"]
  node_recommendation_card["Recommendation card"]
  node_route_list["Route list<br/>[RouteList.tsx]"]
  node_map["Route map<br/>[Map.tsx]"]
  node_header["Header<br/>[Header.tsx]"]
  node_limitation["Limitation notice"]
  node_error["Error notice<br/>[ErrorBanner.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Recommendation API"]
  node_api_service["Jaunt API<br/>[app.py]"]
  node_engine["Recommendation engine"]
  node_parser["Preference parser"]
end

subgraph group_routing["Route data"]
  node_landmarks["Landmark records<br/>[landmarks.json]"]
  node_route_cache[("Route GeoJSON cache")]
  node_route_fetcher["Route fetcher<br/>[fetch_routes.py]"]
end

subgraph group_research["Geographic research"]
  node_nyc_buildings["Building collection"]
  node_geodata["Geodata collection<br/>[collect_geodata.py]"]
  node_geometry["Geometry utilities"]
  node_access_match["Access-point matching"]
  node_access_candidates["Access candidates"]
end

node_traveler(("Traveler"))
node_valhalla["Valhalla routing"]

node_traveler -->|"uses"| node_app
node_app -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api_service
node_api_service -->|"reads"| node_landmarks
node_api_service -->|"loads routes"| node_route_cache
node_api_service -->|"requests ranking"| node_engine
node_engine -->|"parses preference"| node_parser
node_engine -->|"scores routes"| node_route_cache
node_api_service -->|"generates missing route"| node_route_fetcher
node_route_fetcher -->|"requests pedestrian route"| node_valhalla
node_route_fetcher -->|"writes GeoJSON"| node_route_cache
node_app -->|"renders"| node_journey
node_app -->|"renders"| node_header
node_app -->|"renders"| node_limitation
node_app -->|"renders"| node_recommendation_card
node_app -->|"renders"| node_route_list
node_app -->|"renders"| node_map
node_app -->|"renders"| node_error
node_app -.->|"renders"| node_preference
node_traveler -.->|"researches places"| node_nyc_buildings
node_traveler -.->|"researches geography"| node_geodata
node_geometry -.->|"supports matching"| node_access_match
node_access_match -.->|"produces candidates"| node_access_candidates

click node_app "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/App.tsx"
click node_journey "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/JourneySelector.tsx"
click node_preference "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/PreferenceInput.tsx"
click node_recommendation_card "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/RecommendationCard.tsx"
click node_route_list "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/RouteList.tsx"
click node_map "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/Map.tsx"
click node_header "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/Header.tsx"
click node_limitation "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/LimitationBanner.tsx"
click node_error "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/ErrorBanner.tsx"
click node_api_client "https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/services/api.ts"
click node_api_service "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/app.py"
click node_engine "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/recommendation_engine.py"
click node_parser "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/preference_parser.py"
click node_landmarks "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/data/landmarks.json"
click node_route_cache "https://github.com/varun1323/jaunt-route-recommender/tree/main/backend/data/routes"
click node_route_fetcher "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/fetch_routes.py"
click node_nyc_buildings "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/collect_nyc_buildings.py"
click node_geodata "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/collect_geodata.py"
click node_geometry "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/geodata_geometry.py"
click node_access_match "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/match_access_points.py"
click node_access_candidates "https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/data/pedestrian_access_point_candidates.json"

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_journey,node_preference,node_recommendation_card,node_route_list,node_map,node_header,node_limitation,node_error,node_api_client toneBlue
class node_api_service,node_engine,node_parser toneAmber
class node_landmarks,node_route_cache,node_route_fetcher toneMint
class node_nyc_buildings,node_geodata,node_geometry,node_access_match,node_access_candidates toneRose
class node_traveler,node_valhalla toneIndigo
```

## Components

### Traveler experience

- [App state](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Journey selector](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/JourneySelector.tsx): `frontend/src/components/JourneySelector.tsx`
- [Preference input](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/PreferenceInput.tsx): `frontend/src/components/PreferenceInput.tsx`
- [Recommendation card](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/RecommendationCard.tsx): `frontend/src/components/RecommendationCard.tsx`
- [Route list](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/RouteList.tsx): `frontend/src/components/RouteList.tsx`
- [Route map](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/Map.tsx): `frontend/src/components/Map.tsx`
- [Header](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/Header.tsx): `frontend/src/components/Header.tsx`
- [Limitation notice](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/LimitationBanner.tsx): `frontend/src/components/LimitationBanner.tsx`
- [Error notice](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/components/ErrorBanner.tsx): `frontend/src/components/ErrorBanner.tsx`
- [API client](https://github.com/varun1323/jaunt-route-recommender/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Recommendation API

- [Jaunt API](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/app.py): `backend/app.py`
- [Recommendation engine](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/recommendation_engine.py): `backend/scripts/recommendation_engine.py`
- [Preference parser](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/preference_parser.py): `backend/scripts/preference_parser.py`

### Route data

- [Landmark records](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/data/landmarks.json): `backend/data/landmarks.json`
- [Route GeoJSON cache](https://github.com/varun1323/jaunt-route-recommender/tree/main/backend/data/routes): `backend/data/routes`
- [Route fetcher](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/fetch_routes.py): `backend/scripts/fetch_routes.py`

### Geographic research

- [Building collection](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/collect_nyc_buildings.py): `backend/scripts/collect_nyc_buildings.py`
- [Geodata collection](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/collect_geodata.py): `backend/scripts/collect_geodata.py`
- [Geometry utilities](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/geodata_geometry.py): `backend/scripts/geodata_geometry.py`
- [Access-point matching](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/scripts/match_access_points.py): `backend/scripts/match_access_points.py`
- [Access candidates](https://github.com/varun1323/jaunt-route-recommender/blob/main/backend/data/pedestrian_access_point_candidates.json): `backend/data/pedestrian_access_point_candidates.json`

### Other components

- **Traveler**
- **Valhalla routing**

## Connections

- Traveler → App state: uses (evidence: `README.md`)
- App state → API client: requests data (evidence: `frontend/src/App.tsx`)
- API client → Jaunt API: calls API (evidence: `README.md`)
- Jaunt API → Landmark records: reads (evidence: `backend/app.py`)
- Jaunt API → Route GeoJSON cache: loads routes (evidence: `README.md`)
- Jaunt API → Recommendation engine: requests ranking (evidence: `backend/app.py`)
- Recommendation engine → Preference parser: parses preference (evidence: `backend/scripts/recommendation_engine.py`)
- Recommendation engine → Route GeoJSON cache: scores routes (evidence: `backend/scripts/recommendation_engine.py`)
- Jaunt API → Route fetcher: generates missing route (evidence: `README.md`)
- Route fetcher → Valhalla routing: requests pedestrian route (evidence: `README.md`)
- Route fetcher → Route GeoJSON cache: writes GeoJSON (evidence: `README.md`)
- App state → Journey selector: renders (evidence: `frontend/src/App.tsx`)
- App state → Header: renders (evidence: `frontend/src/App.tsx`)
- App state → Limitation notice: renders (evidence: `frontend/src/App.tsx`)
- App state → Recommendation card: renders (evidence: `frontend/src/App.tsx`)
- App state → Route list: renders (evidence: `frontend/src/App.tsx`)
- App state → Route map: renders (evidence: `frontend/src/App.tsx`)
- App state → Error notice: renders (evidence: `frontend/src/App.tsx`)
- App state → Preference input: renders (evidence: `frontend/src/App.tsx`)
- Traveler → Building collection: researches places
- Traveler → Geodata collection: researches geography
- Geometry utilities → Access-point matching: supports matching
- Access-point matching → Access candidates: produces candidates
