# trannam1304/finder architecture

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

- Interactive diagram: https://gitdiagram.com/trannam1304/finder
- Repository: https://github.com/trannam1304/finder

## Overview

Food Finder is a PHP/MySQL location-based place finder. Its principal workflow is that a visitor searches nearby places using location and filters, then explores results and place details; the README also documents random suggestions, saved favorites, reviews, and itinerary generation. Admins manage places, categories, reviews, and suggestions. The tree lacks frontend assets and some endpoint excerpts, so those capability links are documented or left unverified rather than inferred from filenames alone.

Main entry points: [`app/bootstrap.php`](https://github.com/trannam1304/finder/blob/main/app/bootstrap.php) (Application Bootstrap), [`app/services/itinerary.php`](https://github.com/trannam1304/finder/blob/main/app/services/itinerary.php) (Itinerary Generator), [`app/services/restaurant_query.php`](https://github.com/trannam1304/finder/blob/main/app/services/restaurant_query.php) (Nearby Place Query), [`app/core/jwt_auth.php`](https://github.com/trannam1304/finder/blob/main/app/core/jwt_auth.php) (Token Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Place Discovery"]
  node_place_api["Place Search API<br/>[restaurants.php]"]
  node_place_query["Nearby Place Query"]
  node_geo_service["Geospatial Helpers<br/>[geo.php]"]
  node_place_details["Place Details API<br/>[restaurant.php]"]
  node_categories_api["Categories API<br/>[categories.php]"]
  node_geocode_api["Geocoding API<br/>[geocode.php]"]
  node_random_api["Random Place API<br/>[random.php]"]
end

subgraph group_planning["Planning and Engagement"]
  node_suggest_api["Place Suggestions API<br/>[suggest.php]"]
  node_itinerary_api["Itinerary API<br/>[itinerary.php]"]
  node_itinerary_reroll["Reroll API"]
  node_itinerary_service["Itinerary Generator<br/>[itinerary.php]"]
  node_user_itineraries["Saved Itineraries API"]
  node_favorites_api["Favorites API<br/>[favorites.php]"]
  node_reviews_api["Reviews API<br/>[reviews.php]"]
end

subgraph group_identity["Identity and Security"]
  node_auth_api["Member Auth API<br/>[login.php]"]
  node_jwt_auth["Token Authentication<br/>[jwt_auth.php]"]
  node_jwt["JWT and Cookies<br/>[jwt.php]"]
end

subgraph group_admin["Administration"]
  node_admin_pages["Admin Management<br/>[dashboard.php]"]
  node_admin_boot["Admin Bootstrap<br/>[_bootstrap.php]"]
  node_admin_login["Admin Login<br/>[login.php]"]
end

subgraph group_foundation["Backend Foundation"]
  node_app_boot["Application Bootstrap<br/>[bootstrap.php]"]
  node_validation["Request Validation<br/>[validate.php]"]
  node_db_connection["PDO Connection<br/>[db.php]"]
end

node_visitor(("Visitor"))
node_mysql[("MySQL Database")]

node_visitor -.->|"searches places"| node_place_api
node_place_api -.->|"queries nearby"| node_place_query
node_place_query -->|"uses geo helpers"| node_geo_service
node_visitor -.->|"views details"| node_place_details
node_visitor -.->|"browses categories"| node_categories_api
node_visitor -.->|"requests geocoding"| node_geocode_api
node_visitor -.->|"requests random pick"| node_random_api
node_visitor -.->|"suggests a place"| node_suggest_api
node_visitor -.->|"plans a route"| node_itinerary_api
node_visitor -.->|"rerolls a stop"| node_itinerary_reroll
node_itinerary_reroll -->|"generates options"| node_itinerary_service
node_itinerary_service -->|"uses geo helpers"| node_geo_service
node_itinerary_service -->|"queries places"| node_place_query
node_visitor -.->|"manages itineraries"| node_user_itineraries
node_visitor -.->|"saves favorites"| node_favorites_api
node_visitor -.->|"submits reviews"| node_reviews_api
node_visitor -.->|"creates account"| node_auth_api
node_auth_api -.->|"authenticates"| node_jwt_auth
node_jwt_auth -->|"signs and verifies"| node_jwt
node_admin_login -.->|"loads admin context"| node_admin_boot
node_admin_pages -->|"loads admin context"| node_admin_boot
node_admin_boot -->|"loads application"| node_app_boot
node_app_boot -->|"loads helpers"| node_validation
node_app_boot -->|"loads database layer"| node_db_connection
node_app_boot -->|"loads authentication"| node_jwt_auth
node_db_connection -->|"connects to"| node_mysql
node_reviews_api -->|"loads application"| node_app_boot
node_place_details -.->|"loads application"| node_app_boot
node_favorites_api -.->|"loads application"| node_app_boot
node_suggest_api -.->|"loads application"| node_app_boot
node_user_itineraries -.->|"loads application"| node_app_boot

click node_place_api "https://github.com/trannam1304/finder/blob/main/public/api/restaurants.php"
click node_place_query "https://github.com/trannam1304/finder/blob/main/app/services/restaurant_query.php"
click node_geo_service "https://github.com/trannam1304/finder/blob/main/app/services/geo.php"
click node_place_details "https://github.com/trannam1304/finder/blob/main/public/api/restaurant.php"
click node_categories_api "https://github.com/trannam1304/finder/blob/main/public/api/categories.php"
click node_geocode_api "https://github.com/trannam1304/finder/blob/main/public/api/geocode.php"
click node_random_api "https://github.com/trannam1304/finder/blob/main/public/api/random.php"
click node_suggest_api "https://github.com/trannam1304/finder/blob/main/public/api/suggest.php"
click node_itinerary_api "https://github.com/trannam1304/finder/blob/main/public/api/itinerary.php"
click node_itinerary_reroll "https://github.com/trannam1304/finder/blob/main/public/api/itinerary_reroll.php"
click node_itinerary_service "https://github.com/trannam1304/finder/blob/main/app/services/itinerary.php"
click node_user_itineraries "https://github.com/trannam1304/finder/blob/main/public/api/user_itineraries.php"
click node_favorites_api "https://github.com/trannam1304/finder/blob/main/public/api/favorites.php"
click node_reviews_api "https://github.com/trannam1304/finder/blob/main/public/api/reviews.php"
click node_auth_api "https://github.com/trannam1304/finder/blob/main/public/api/auth/login.php"
click node_jwt_auth "https://github.com/trannam1304/finder/blob/main/app/core/jwt_auth.php"
click node_jwt "https://github.com/trannam1304/finder/blob/main/app/core/jwt.php"
click node_admin_pages "https://github.com/trannam1304/finder/blob/main/public/admin/dashboard.php"
click node_admin_boot "https://github.com/trannam1304/finder/blob/main/public/admin/_bootstrap.php"
click node_admin_login "https://github.com/trannam1304/finder/blob/main/public/admin/login.php"
click node_app_boot "https://github.com/trannam1304/finder/blob/main/app/bootstrap.php"
click node_validation "https://github.com/trannam1304/finder/blob/main/app/helpers/validate.php"
click node_db_connection "https://github.com/trannam1304/finder/blob/main/app/core/db.php"

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_place_api,node_place_query,node_geo_service,node_place_details,node_categories_api,node_geocode_api,node_random_api toneBlue
class node_suggest_api,node_itinerary_api,node_itinerary_reroll,node_itinerary_service,node_user_itineraries,node_favorites_api,node_reviews_api,node_mysql toneAmber
class node_auth_api,node_jwt_auth,node_jwt toneMint
class node_admin_pages,node_admin_boot,node_admin_login toneRose
class node_app_boot,node_validation,node_db_connection,node_visitor toneIndigo
```

## Components

### Place Discovery

- [Place Search API](https://github.com/trannam1304/finder/blob/main/public/api/restaurants.php): `public/api/restaurants.php`
- [Nearby Place Query](https://github.com/trannam1304/finder/blob/main/app/services/restaurant_query.php): `app/services/restaurant_query.php`
- [Geospatial Helpers](https://github.com/trannam1304/finder/blob/main/app/services/geo.php): `app/services/geo.php`
- [Place Details API](https://github.com/trannam1304/finder/blob/main/public/api/restaurant.php): `public/api/restaurant.php`
- [Categories API](https://github.com/trannam1304/finder/blob/main/public/api/categories.php): `public/api/categories.php`
- [Geocoding API](https://github.com/trannam1304/finder/blob/main/public/api/geocode.php): `public/api/geocode.php`
- [Random Place API](https://github.com/trannam1304/finder/blob/main/public/api/random.php): `public/api/random.php`

### Planning and Engagement

- [Place Suggestions API](https://github.com/trannam1304/finder/blob/main/public/api/suggest.php): `public/api/suggest.php`
- [Itinerary API](https://github.com/trannam1304/finder/blob/main/public/api/itinerary.php): `public/api/itinerary.php`
- [Reroll API](https://github.com/trannam1304/finder/blob/main/public/api/itinerary_reroll.php): `public/api/itinerary_reroll.php`
- [Itinerary Generator](https://github.com/trannam1304/finder/blob/main/app/services/itinerary.php): `app/services/itinerary.php`
- [Saved Itineraries API](https://github.com/trannam1304/finder/blob/main/public/api/user_itineraries.php): `public/api/user_itineraries.php`
- [Favorites API](https://github.com/trannam1304/finder/blob/main/public/api/favorites.php): `public/api/favorites.php`
- [Reviews API](https://github.com/trannam1304/finder/blob/main/public/api/reviews.php): `public/api/reviews.php`

### Identity and Security

- [Member Auth API](https://github.com/trannam1304/finder/blob/main/public/api/auth/login.php): `public/api/auth/login.php`
- [Token Authentication](https://github.com/trannam1304/finder/blob/main/app/core/jwt_auth.php): `app/core/jwt_auth.php`
- [JWT and Cookies](https://github.com/trannam1304/finder/blob/main/app/core/jwt.php): `app/core/jwt.php`

### Administration

- [Admin Management](https://github.com/trannam1304/finder/blob/main/public/admin/dashboard.php): `public/admin/dashboard.php`
- [Admin Bootstrap](https://github.com/trannam1304/finder/blob/main/public/admin/_bootstrap.php): `public/admin/_bootstrap.php`
- [Admin Login](https://github.com/trannam1304/finder/blob/main/public/admin/login.php): `public/admin/login.php`

### Backend Foundation

- [Application Bootstrap](https://github.com/trannam1304/finder/blob/main/app/bootstrap.php): `app/bootstrap.php`
- [Request Validation](https://github.com/trannam1304/finder/blob/main/app/helpers/validate.php): `app/helpers/validate.php`
- [PDO Connection](https://github.com/trannam1304/finder/blob/main/app/core/db.php): `app/core/db.php`

### Other components

- **Visitor**
- **MySQL Database**

## Connections

- Visitor → Place Search API: searches places (evidence: `README.md`)
- Place Search API → Nearby Place Query: queries nearby
- Nearby Place Query → Geospatial Helpers: uses geo helpers (evidence: `app/services/restaurant_query.php`)
- Visitor → Place Details API: views details (evidence: `README.md`)
- Visitor → Categories API: browses categories (evidence: `README.md`)
- Visitor → Geocoding API: requests geocoding
- Visitor → Random Place API: requests random pick (evidence: `README.md`)
- Visitor → Place Suggestions API: suggests a place
- Visitor → Itinerary API: plans a route
- Visitor → Reroll API: rerolls a stop
- Reroll API → Itinerary Generator: generates options (evidence: `public/api/itinerary_reroll.php`)
- Itinerary Generator → Geospatial Helpers: uses geo helpers (evidence: `app/services/itinerary.php`)
- Itinerary Generator → Nearby Place Query: queries places (evidence: `app/services/itinerary.php`)
- Visitor → Saved Itineraries API: manages itineraries
- Visitor → Favorites API: saves favorites (evidence: `README.md`)
- Visitor → Reviews API: submits reviews
- Visitor → Member Auth API: creates account
- Member Auth API → Token Authentication: authenticates (evidence: `public/api/auth/login.php`)
- Token Authentication → JWT and Cookies: signs and verifies (evidence: `app/core/jwt_auth.php`)
- Admin Login → Admin Bootstrap: loads admin context (evidence: `public/admin/_bootstrap.php`)
- Admin Management → Admin Bootstrap: loads admin context (evidence: `public/admin/dashboard.php`)
- Admin Bootstrap → Application Bootstrap: loads application (evidence: `public/admin/_bootstrap.php`)
- Application Bootstrap → Request Validation: loads helpers (evidence: `app/bootstrap.php`)
- Application Bootstrap → PDO Connection: loads database layer (evidence: `app/bootstrap.php`)
- Application Bootstrap → Token Authentication: loads authentication (evidence: `app/bootstrap.php`)
- PDO Connection → MySQL Database: connects to (evidence: `app/core/db.php`)
- Reviews API → Application Bootstrap: loads application (evidence: `public/api/reviews.php`)
- Place Details API → Application Bootstrap: loads application (evidence: `public/api/restaurant.php`)
- Favorites API → Application Bootstrap: loads application (evidence: `public/api/favorites.php`)
- Place Suggestions API → Application Bootstrap: loads application (evidence: `public/api/suggest.php`)
- Saved Itineraries API → Application Bootstrap: loads application (evidence: `public/api/user_itineraries.php`)