# debang5hu/travel-companion-finder-system architecture

> Architecture diagram of the GitHub repository debang5hu/travel-companion-finder-system, 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/debang5hu/travel-companion-finder-system
- Repository: https://github.com/debang5hu/travel-companion-finder-system

## Overview

Travel Companion Finder is a Flask/MySQL web app for creating traveler profiles, discovering compatible users and trips, organizing groups, and messaging. The user-facing flow is browser pages → shared API client → Flask endpoints; recommendations use profile, ratings, location, and clustering signals. Group and chat capabilities are documented, but their implementation is part of the large Flask module and was not sampled in detail. Edges to those domain handlers are therefore documented at the API boundary; the recommendation-to-model call is shown as unverified.

Main entry points: [`app/frontend/js/api.js`](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/frontend/js/api.js) (API client), [`app/backend/main.sql`](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/main.sql) (MySQL database), [`app/backend/module/poi.py`](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/module/poi.py) (POI service), [`app/frontend`](https://github.com/debang5hu/travel-companion-finder-system/tree/main/app/frontend) (Browser pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Browser pages"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_accounts["Accounts and groups"]
  node_accounts_api["Accounts and auth<br/>[app.py]"]
  node_groups_api["Travel groups<br/>[app.py]"]
end

subgraph group_social["Messaging"]
  node_private_chat["Private chat<br/>[app.py]"]
  node_group_chat["Group chat<br/>[app.py]"]
end

subgraph group_discovery["Discovery and recommendations"]
  node_recommend_api["Recommendation endpoint<br/>[app.py]"]
  node_recommender["Hybrid recommender<br/>[recommender.py]"]
  node_poi_service["POI service<br/>[poi.py]"]
end

subgraph group_data["Data services"]
  node_mysql[("MySQL database<br/>[main.sql]")]
end

node_traveler(("Traveler"))
node_opentripmap{{"OpenTripMap"}}

node_traveler -->|"uses"| node_browser
node_browser -.->|"requests data"| node_api_client
node_api_client -->|"calls account APIs"| node_accounts_api
node_api_client -->|"calls group APIs"| node_groups_api
node_api_client -->|"calls chat APIs"| node_private_chat
node_api_client -->|"calls group chat"| node_group_chat
node_api_client -->|"requests matches"| node_recommend_api
node_accounts_api -->|"reads and writes"| node_mysql
node_groups_api -->|"reads and writes"| node_mysql
node_private_chat -->|"reads and writes"| node_mysql
node_group_chat -->|"reads and writes"| node_mysql
node_recommend_api -.->|"requests scores"| node_recommender
node_recommender -->|"loads profiles and ratings"| node_mysql
node_poi_service -->|"fetches places"| node_opentripmap
node_poi_service -->|"upserts places"| node_mysql

click node_browser "https://github.com/debang5hu/travel-companion-finder-system/tree/main/app/frontend"
click node_api_client "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/frontend/js/api.js"
click node_accounts_api "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py"
click node_groups_api "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py"
click node_private_chat "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py"
click node_group_chat "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py"
click node_recommend_api "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py"
click node_recommender "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/module/recommender.py"
click node_poi_service "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/module/poi.py"
click node_mysql "https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/main.sql"

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_browser,node_api_client toneBlue
class node_accounts_api,node_groups_api toneAmber
class node_private_chat,node_group_chat toneMint
class node_recommend_api,node_recommender,node_poi_service toneRose
class node_mysql,node_traveler,node_opentripmap toneIndigo
```

## Components

### Web experience

- [Browser pages](https://github.com/debang5hu/travel-companion-finder-system/tree/main/app/frontend): `app/frontend`
- [API client](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/frontend/js/api.js): `app/frontend/js/api.js`

### Accounts and groups

- [Accounts and auth](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py): `app/backend/app.py`
- [Travel groups](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py): `app/backend/app.py`

### Messaging

- [Private chat](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py): `app/backend/app.py`
- [Group chat](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py): `app/backend/app.py`

### Discovery and recommendations

- [Recommendation endpoint](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/app.py): `app/backend/app.py`
- [Hybrid recommender](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/module/recommender.py): `app/backend/module/recommender.py`
- [POI service](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/module/poi.py): `app/backend/module/poi.py`

### Data services

- [MySQL database](https://github.com/debang5hu/travel-companion-finder-system/blob/main/app/backend/main.sql): `app/backend/main.sql`

### Other components

- **Traveler**
- **OpenTripMap**

## Connections

- Traveler → Browser pages: uses (evidence: `README.md`)
- Browser pages → API client: requests data
- API client → Accounts and auth: calls account APIs (evidence: `app/frontend/js/api.js`)
- API client → Travel groups: calls group APIs (evidence: `app/frontend/js/api.js`)
- API client → Private chat: calls chat APIs (evidence: `app/frontend/js/api.js`)
- API client → Group chat: calls group chat (evidence: `app/frontend/js/api.js`)
- API client → Recommendation endpoint: requests matches (evidence: `app/frontend/js/api.js`)
- Accounts and auth → MySQL database: reads and writes (evidence: `app/backend/app.py`)
- Travel groups → MySQL database: reads and writes (evidence: `app/backend/app.py`)
- Private chat → MySQL database: reads and writes (evidence: `app/backend/app.py`)
- Group chat → MySQL database: reads and writes (evidence: `app/backend/app.py`)
- Recommendation endpoint → Hybrid recommender: requests scores (evidence: `app/backend/app.py`)
- Hybrid recommender → MySQL database: loads profiles and ratings (evidence: `app/backend/module/recommender.py`)
- POI service → OpenTripMap: fetches places (evidence: `app/backend/module/poi.py`)
- POI service → MySQL database: upserts places (evidence: `app/backend/module/poi.py`)
