# dang-khoa-nguyen/whereweeat architecture

> Architecture diagram of the GitHub repository dang-khoa-nguyen/whereweeat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dang-khoa-nguyen/whereweeat
- Repository: https://github.com/dang-khoa-nguyen/whereweeat

## Overview

WhereWeEat is a restaurant-discovery app with two user paths: search by location and preferences, or request a surprise pick. Both lead to selecting a restaurant, fetching walking/biking/driving routes, and viewing the result on a map. The README also documents a normalized restaurant-data layer and external Places, routing, map-tile, geolocation, and directions services. The principal frontend and backend wiring is supported by sampled source; the map and random-button implementations were not sampled, so their internal behavior is represented only where documented.

Main entry points: [`app/page.tsx`](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/page.tsx) (Search and results), [`backend/main.py`](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/main.py) (FastAPI endpoints), [`app/components/model/ScratchModel.tsx`](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/model/ScratchModel.tsx) (Scratch reveal), [`backend/services/seek_restaurant_service.py`](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/seek_restaurant_service.py) (Restaurant search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_home["Search and results<br/>[page.tsx]"]
  node_recommend_hook["Search hook"]
  node_random_button["Random button<br/>[randomButton.tsx]"]
  node_random_hook["Random hook<br/>[useRandom.ts]"]
  node_scratch["Scratch reveal<br/>[ScratchModel.tsx]"]
  node_list["Restaurant list<br/>[RestaurantList.tsx]"]
  node_geo["Browser location<br/>[geo.ts]"]
  node_api_config["API endpoint config<br/>[api.ts]"]
end

subgraph group_discovery["Restaurant discovery"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_seek["Restaurant search"]
  node_calculate["Radius calculation"]
  node_format["Result normalization<br/>[format_list.py]"]
  node_rating["Rating assignment<br/>[random_star.py]"]
  node_random_service["Random selection<br/>[random_service.py]"]
end

subgraph group_routing["Routes and maps"]
  node_map_view["Map display<br/>[RestaurantMap.tsx]"]
  node_route_service["Route service<br/>[routing_service.py]"]
end

subgraph group_providers["External services"]
  node_places["Foursquare Places"]
  node_ors["OpenRouteService"]
  node_tiles["OpenStreetMap tiles"]
  node_geolocation["Geolocation API"]
  node_directions["Google Maps directions"]
end

node_diner(("Diner"))

node_diner -->|"sets preferences"| node_home
node_home -->|"searches via"| node_recommend_hook
node_recommend_hook -->|"requests coordinates"| node_geo
node_geo -->|"reads location"| node_geolocation
node_recommend_hook -->|"uses endpoint"| node_api_config
node_recommend_hook -->|"fetches recommendations"| node_api
node_home -->|"offers surprise"| node_random_button
node_random_button -->|"requests pick"| node_random_hook
node_random_hook -->|"requests coordinates"| node_geo
node_random_hook -->|"uses endpoint"| node_api_config
node_random_hook -->|"fetches random pick"| node_api
node_api -->|"searches restaurants"| node_seek
node_api -->|"selects random"| node_random_service
node_seek -->|"calculates radius"| node_calculate
node_seek -->|"searches places"| node_places
node_places -->|"returns places"| node_seek
node_seek -->|"normalizes results"| node_format
node_format -->|"gets rating"| node_rating
node_api -->|"requests all routes"| node_route_service
node_route_service -->|"requests directions"| node_ors
node_ors -->|"returns route data"| node_route_service
node_api -->|"returns results"| node_home
node_home -->|"renders results"| node_list
node_list -->|"selects restaurant"| node_home
node_home -->|"requests route origin"| node_geo
node_home -->|"fetches selected routes"| node_api
node_home -->|"shows route"| node_map_view
node_map_view -->|"loads map tiles"| node_tiles
node_random_button -->|"opens reveal"| node_scratch
node_home -->|"passes result and routes"| node_scratch
node_scratch -->|"shows route"| node_map_view
node_scratch -->|"reads origin"| node_geolocation
node_scratch -->|"links directions"| node_directions

click node_home "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/page.tsx"
click node_recommend_hook "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/hooks/useRecommendation.ts"
click node_random_button "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/buttons/randomButton.tsx"
click node_random_hook "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/hooks/useRandom.ts"
click node_scratch "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/model/ScratchModel.tsx"
click node_list "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/RestaurantList.tsx"
click node_map_view "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/map/RestaurantMap.tsx"
click node_geo "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/lib/geo.ts"
click node_api_config "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/lib/api.ts"
click node_api "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/main.py"
click node_seek "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/seek_restaurant_service.py"
click node_calculate "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/calculate_service.py"
click node_format "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/utils/format_list.py"
click node_rating "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/utils/random_star.py"
click node_random_service "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/random_service.py"
click node_route_service "https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/routing_service.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_home,node_recommend_hook,node_random_button,node_random_hook,node_scratch,node_list,node_geo,node_api_config toneBlue
class node_api,node_seek,node_calculate,node_format,node_rating,node_random_service toneAmber
class node_map_view,node_route_service toneMint
class node_places,node_ors,node_tiles,node_geolocation,node_directions toneRose
class node_diner toneIndigo
```

## Components

### Frontend experience

- [Search and results](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/page.tsx): `app/page.tsx`
- [Search hook](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/hooks/useRecommendation.ts): `hooks/useRecommendation.ts`
- [Random button](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/buttons/randomButton.tsx): `app/components/buttons/randomButton.tsx`
- [Random hook](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/hooks/useRandom.ts): `hooks/useRandom.ts`
- [Scratch reveal](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/model/ScratchModel.tsx): `app/components/model/ScratchModel.tsx`
- [Restaurant list](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/RestaurantList.tsx): `app/components/RestaurantList.tsx`
- [Browser location](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/lib/geo.ts): `lib/geo.ts`
- [API endpoint config](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/lib/api.ts): `lib/api.ts`

### Restaurant discovery

- [FastAPI endpoints](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/main.py): `backend/main.py`
- [Restaurant search](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/seek_restaurant_service.py): `backend/services/seek_restaurant_service.py`
- [Radius calculation](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/calculate_service.py): `backend/services/calculate_service.py`
- [Result normalization](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/utils/format_list.py): `backend/utils/format_list.py`
- [Rating assignment](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/utils/random_star.py): `backend/utils/random_star.py`
- [Random selection](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/random_service.py): `backend/services/random_service.py`

### Routes and maps

- [Map display](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/app/components/map/RestaurantMap.tsx): `app/components/map/RestaurantMap.tsx`
- [Route service](https://github.com/dang-khoa-nguyen/whereweeat/blob/master/backend/services/routing_service.py): `backend/services/routing_service.py`

### External services

- **Foursquare Places**
- **OpenRouteService**
- **OpenStreetMap tiles**
- **Geolocation API**
- **Google Maps directions**

### Other components

- **Diner**

## Connections

- Diner → Search and results: sets preferences
- Search and results → Search hook: searches via
- Search hook → Browser location: requests coordinates
- Browser location → Geolocation API: reads location
- Search hook → API endpoint config: uses endpoint
- Search hook → FastAPI endpoints: fetches recommendations
- Search and results → Random button: offers surprise
- Random button → Random hook: requests pick
- Random hook → Browser location: requests coordinates
- Random hook → API endpoint config: uses endpoint
- Random hook → FastAPI endpoints: fetches random pick
- FastAPI endpoints → Restaurant search: searches restaurants
- FastAPI endpoints → Random selection: selects random
- Restaurant search → Radius calculation: calculates radius
- Restaurant search → Foursquare Places: searches places
- Foursquare Places → Restaurant search: returns places
- Restaurant search → Result normalization: normalizes results
- Result normalization → Rating assignment: gets rating
- FastAPI endpoints → Route service: requests all routes
- Route service → OpenRouteService: requests directions
- OpenRouteService → Route service: returns route data
- FastAPI endpoints → Search and results: returns results
- Search and results → Restaurant list: renders results
- Restaurant list → Search and results: selects restaurant
- Search and results → Browser location: requests route origin
- Search and results → FastAPI endpoints: fetches selected routes
- Search and results → Map display: shows route
- Map display → OpenStreetMap tiles: loads map tiles
- Random button → Scratch reveal: opens reveal
- Search and results → Scratch reveal: passes result and routes
- Scratch reveal → Map display: shows route
- Scratch reveal → Geolocation API: reads origin
- Scratch reveal → Google Maps directions: links directions