# vppm-ui/ferene-travel-app architecture

> Architecture diagram of the GitHub repository vppm-ui/ferene-travel-app, 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/vppm-ui/ferene-travel-app
- Repository: https://github.com/vppm-ui/ferene-travel-app

## Overview

Ferene combines a browser travel-planning experience with a FastAPI destination-recommendation service. In the main workflow, travelers express crowd and trip preferences in the planner; the browser saves those preferences, and the hidden-gems page requests crowd-filtered recommendations for display. The service ranks tourism data by pressure and can calculate distance when starting coordinates are available. Separate frontend features include trip setup, emergency SOS, and swipe-based travel matching. The excerpts show no frontend call to the API chat endpoint; coordinate-file availability and some page wiring are not established by the supplied evidence.

Main entry points: [`frontend/planner.js`](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/planner.js) (Preference capture), [`frontend/home.js`](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/home.js) (Trip setup), [`frontend/gems.js`](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.js) (Recommendation display), [`backend/recommendation.py`](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/recommendation.py) (Place ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Travel planning"]
  node_planner_ui["Planner page<br/>[planner.html]"]
  node_preference_capture["Preference capture<br/>[planner.js]"]
  node_preference_store[("Browser preferences")]
  node_home_page["Trip setup<br/>[home.js]"]
  node_app_navigation["View navigation<br/>[script.js]"]
  node_itinerary_page["Itinerary view<br/>[itinerary.html]"]
end

subgraph group_recommendation["Destination recommendations"]
  node_gems_ui["Hidden gems page<br/>[gems.html]"]
  node_gems_loader["Recommendation display<br/>[gems.js]"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_ranking["Place ranking<br/>[recommendation.py]"]
  node_distance_calc["Distance calculation<br/>[distance.py]"]
  node_recommendations_page["Recommendations view<br/>[gems.html]"]
end

subgraph group_data["Tourism data"]
  node_pressure_calc["Pressure scoring"]
  node_crowd_data["Crowd input data"]
  node_pressure_data["Pressure results"]
end

subgraph group_social["Travel safety and matching"]
  node_sos["Emergency SOS<br/>[home.js]"]
  node_swipe_matching["Swipe matching<br/>[swipe.js]"]
end

node_traveler(("Traveler"))
node_location_service["Geolocation and reverse lookup"]
node_sharing["Device sharing"]

node_traveler -->|"sets preferences"| node_planner_ui
node_planner_ui -->|"submits text"| node_preference_capture
node_preference_capture -->|"saves preferences"| node_preference_store
node_preference_capture -->|"links to gems"| node_gems_ui
node_gems_ui -->|"loads recommendations"| node_gems_loader
node_gems_loader -->|"reads preferences"| node_preference_store
node_gems_loader -->|"requests recommendations"| node_api
node_api -->|"calls ranking"| node_ranking
node_ranking -->|"reads pressure data"| node_pressure_data
node_ranking -->|"calculates distances"| node_distance_calc
node_pressure_calc -->|"reads crowd data"| node_crowd_data
node_pressure_calc -->|"writes scores"| node_pressure_data
node_traveler -->|"sets trip details"| node_home_page
node_home_page -->|"looks up location"| node_location_service
node_home_page -->|"activates SOS"| node_sos
node_sos -->|"gets coordinates"| node_location_service
node_sos -->|"shares details"| node_sharing
node_traveler -->|"swipes profiles"| node_swipe_matching
node_app_navigation -->|"opens itinerary"| node_itinerary_page

click node_planner_ui "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/planner.html"
click node_preference_capture "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/planner.js"
click node_gems_ui "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.html"
click node_gems_loader "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.js"
click node_api "https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/main.py"
click node_ranking "https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/recommendation.py"
click node_distance_calc "https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/distance.py"
click node_pressure_calc "https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/tourism_pressure.py"
click node_crowd_data "https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/uttarakhand_tourism_with_crowd.csv"
click node_pressure_data "https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/uttarakhand_tourism_with_pressure.csv"
click node_home_page "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/home.js"
click node_sos "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/home.js"
click node_swipe_matching "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/swipe.js"
click node_app_navigation "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/script.js"
click node_itinerary_page "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/itinerary.html"
click node_recommendations_page "https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.html"

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_planner_ui,node_preference_capture,node_preference_store,node_home_page,node_app_navigation,node_itinerary_page toneBlue
class node_gems_ui,node_gems_loader,node_api,node_ranking,node_distance_calc,node_recommendations_page toneAmber
class node_pressure_calc,node_crowd_data,node_pressure_data toneMint
class node_sos,node_swipe_matching toneRose
class node_traveler,node_location_service,node_sharing toneIndigo
```

## Components

### Travel planning

- [Planner page](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/planner.html): `frontend/planner.html`
- [Preference capture](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/planner.js): `frontend/planner.js`
- **Browser preferences**
- [Trip setup](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/home.js): `frontend/home.js`
- [View navigation](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/script.js): `frontend/script.js`
- [Itinerary view](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/itinerary.html): `frontend/itinerary.html`

### Destination recommendations

- [Hidden gems page](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.html): `frontend/gems.html`
- [Recommendation display](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.js): `frontend/gems.js`
- [FastAPI endpoints](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/main.py): `backend/main.py`
- [Place ranking](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/recommendation.py): `backend/recommendation.py`
- [Distance calculation](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/distance.py): `backend/distance.py`
- [Recommendations view](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/gems.html): `frontend/gems.html`

### Tourism data

- [Pressure scoring](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/tourism_pressure.py): `backend/tourism_pressure.py`
- [Crowd input data](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/uttarakhand_tourism_with_crowd.csv): `backend/uttarakhand_tourism_with_crowd.csv`
- [Pressure results](https://github.com/vppm-ui/ferene-travel-app/blob/main/backend/uttarakhand_tourism_with_pressure.csv): `backend/uttarakhand_tourism_with_pressure.csv`

### Travel safety and matching

- [Emergency SOS](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/home.js): `frontend/home.js`
- [Swipe matching](https://github.com/vppm-ui/ferene-travel-app/blob/main/frontend/swipe.js): `frontend/swipe.js`

### Other components

- **Traveler**
- **Geolocation and reverse lookup**
- **Device sharing**

## Connections

- Traveler → Planner page: sets preferences
- Planner page → Preference capture: submits text (evidence: `frontend/planner.js`)
- Preference capture → Browser preferences: saves preferences (evidence: `frontend/planner.js`)
- Preference capture → Hidden gems page: links to gems (evidence: `frontend/planner.js`)
- Hidden gems page → Recommendation display: loads recommendations (evidence: `frontend/gems.js`)
- Recommendation display → Browser preferences: reads preferences (evidence: `frontend/gems.js`)
- Recommendation display → FastAPI endpoints: requests recommendations (evidence: `frontend/gems.js`)
- FastAPI endpoints → Place ranking: calls ranking (evidence: `backend/main.py`)
- Place ranking → Pressure results: reads pressure data (evidence: `backend/recommendation.py`)
- Place ranking → Distance calculation: calculates distances (evidence: `backend/recommendation.py`)
- Pressure scoring → Crowd input data: reads crowd data (evidence: `backend/tourism_pressure.py`)
- Pressure scoring → Pressure results: writes scores (evidence: `backend/tourism_pressure.py`)
- Traveler → Trip setup: sets trip details (evidence: `frontend/home.js`)
- Trip setup → Geolocation and reverse lookup: looks up location (evidence: `frontend/home.js`)
- Trip setup → Emergency SOS: activates SOS (evidence: `frontend/home.js`)
- Emergency SOS → Geolocation and reverse lookup: gets coordinates (evidence: `frontend/home.js`)
- Emergency SOS → Device sharing: shares details (evidence: `frontend/home.js`)
- Traveler → Swipe matching: swipes profiles (evidence: `frontend/swipe.js`)
- View navigation → Itinerary view: opens itinerary (evidence: `frontend/script.js`)
