# nguyentribaothang/localexplorerai architecture

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

- Interactive diagram: https://gitdiagram.com/nguyentribaothang/localexplorerai
- Repository: https://github.com/nguyentribaothang/localexplorerai

## Overview

Local Explorer AI is a Ho Chi Minh City experience-discovery and trip-planning platform. Travelers explore verified experiences, express trip constraints in chat or the planner, receive slot-aware itineraries with routes, and can book and pay; providers manage availability and booking decisions, while administrators oversee operations and integrations. The graph also preserves the documented local search/ranking, dynamic replanning, 3D map, evidence, and payment capabilities. Several backend route implementations were not sampled, so those feature links are based on README documentation rather than inspected calls.

Main entry points: [`apps/api/app/main.py`](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/main.py) (FastAPI application), [`apps/web/src/router.tsx`](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/router.tsx) (Role-based routes), [`apps/web/src/pages/ExplorePage.tsx`](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ExplorePage.tsx) (Explore and chat), [`apps/web/src/api/client.ts`](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Traveler Interface"]
  node_webapp["Web application<br/>[main.tsx]"]
  node_router["Role-based routes<br/>[router.tsx]"]
  node_explore_ui["Explore and chat<br/>[ExplorePage.tsx]"]
  node_itinerary_ui["Itinerary view<br/>[ItineraryPage.tsx]"]
  node_provider_ui["Provider portal"]
  node_admin_ui["Admin tools<br/>[AdminPage.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_discovery["Experience Discovery"]
  node_catalog["Experience catalog<br/>[catalog.py]"]
  node_search["Semantic search"]
  node_evidence["Evidence verification"]
end

subgraph group_planning["Planning and AI"]
  node_chat["Concierge chat<br/>[chat.py]"]
  node_planner_route["Planner API<br/>[planner.py]"]
  node_planner_service["Itinerary planning<br/>[planner_service.py]"]
  node_planner_engine["Heuristic solver<br/>[planner_engine.py]"]
  node_ranker["ML ranker"]
  node_replanning["Dynamic replanning"]
  node_routing["Goong routing<br/>[routing_service.py]"]
end

subgraph group_transactions["Bookings and Operations"]
  node_booking_routes["Booking and payment API<br/>[bookings.py]"]
  node_provider_routes["Provider management API<br/>[provider.py]"]
  node_admin_routes["Admin API<br/>[admin.py]"]
end

subgraph group_foundation["API and Data"]
  node_auth_routes["Authentication API<br/>[auth.py]"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_database[("PostgreSQL and PostGIS<br/>[entities.py]")]
  node_llm["LLM provider<br/>[provider.py]"]
end

node_traveler(("Traveler"))
node_provider(("Experience provider"))
node_admin(("Administrator"))
node_goong["Goong Maps"]
node_payment_gateway["VNPay or MoMo"]

node_traveler -->|"uses"| node_webapp
node_webapp -->|"loads routes"| node_router
node_router -->|"routes to"| node_explore_ui
node_router -->|"routes to"| node_itinerary_ui
node_router -->|"routes to"| node_provider_ui
node_router -->|"routes to"| node_admin_ui
node_explore_ui -.->|"requests data"| node_api_client
node_itinerary_ui -->|"requests data"| node_api_client
node_provider_ui -->|"manages bookings"| node_api_client
node_admin_ui -.->|"requests tools"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"registers routes"| node_catalog
node_api_app -->|"registers routes"| node_chat
node_api_app -->|"registers routes"| node_planner_route
node_api_app -->|"registers routes"| node_booking_routes
node_api_app -->|"registers routes"| node_provider_routes
node_api_app -->|"registers routes"| node_admin_routes
node_api_app -->|"registers routes"| node_auth_routes
node_explore_ui -.->|"browses experiences"| node_catalog
node_explore_ui -.->|"searches semantically"| node_search
node_catalog -.->|"verifies provenance"| node_evidence
node_explore_ui -.->|"sends constraints"| node_chat
node_chat -.->|"parses intent"| node_llm
node_chat -.->|"transfers constraints"| node_planner_route
node_planner_route -->|"requests plan"| node_planner_service
node_planner_service -->|"selects schedule"| node_planner_engine
node_planner_service -->|"ranks candidates"| node_ranker
node_planner_service -->|"computes routes"| node_routing
node_routing -->|"requests directions"| node_goong
node_itinerary_ui -.->|"requests replanning"| node_replanning
node_booking_routes -.->|"initiates payment"| node_payment_gateway
node_traveler -.->|"books experience"| node_booking_routes
node_provider -.->|"manages availability"| node_provider_ui
node_admin -.->|"oversees platform"| node_admin_ui
node_booking_routes -.->|"holds seats"| node_database
node_provider_routes -.->|"updates offerings"| node_database
node_catalog -.->|"reads catalog"| node_database
node_auth_routes -->|"loads accounts"| node_database

click node_webapp "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/main.tsx"
click node_router "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/router.tsx"
click node_explore_ui "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ExplorePage.tsx"
click node_itinerary_ui "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ItineraryPage.tsx"
click node_provider_ui "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ProviderPortalPage.tsx"
click node_admin_ui "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/AdminPage.tsx"
click node_api_client "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/api/client.ts"
click node_catalog "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/catalog.py"
click node_search "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/e5_search_service.py"
click node_evidence "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/evidence_service.py"
click node_chat "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/chat.py"
click node_planner_route "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/planner.py"
click node_planner_service "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/planner_service.py"
click node_planner_engine "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/planner_engine.py"
click node_ranker "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/ml_ranker_service.py"
click node_replanning "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/replanning_service.py"
click node_routing "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/routing_service.py"
click node_booking_routes "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/bookings.py"
click node_provider_routes "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/provider.py"
click node_admin_routes "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/admin.py"
click node_auth_routes "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/auth.py"
click node_api_app "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/main.py"
click node_database "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/models/entities.py"
click node_llm "https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/adapters/llm/provider.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_webapp,node_router,node_explore_ui,node_itinerary_ui,node_provider_ui,node_admin_ui,node_api_client toneBlue
class node_catalog,node_search,node_evidence toneAmber
class node_chat,node_planner_route,node_planner_service,node_planner_engine,node_ranker,node_replanning,node_routing toneMint
class node_booking_routes,node_provider_routes,node_admin_routes toneRose
class node_auth_routes,node_api_app,node_database,node_llm,node_traveler,node_provider,node_admin,node_goong,node_payment_gateway toneIndigo
```

## Components

### Traveler Interface

- [Web application](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Role-based routes](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/router.tsx): `apps/web/src/router.tsx`
- [Explore and chat](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ExplorePage.tsx): `apps/web/src/pages/ExplorePage.tsx`
- [Itinerary view](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ItineraryPage.tsx): `apps/web/src/pages/ItineraryPage.tsx`
- [Provider portal](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/ProviderPortalPage.tsx): `apps/web/src/pages/ProviderPortalPage.tsx`
- [Admin tools](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/pages/AdminPage.tsx): `apps/web/src/pages/AdminPage.tsx`
- [API client](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/web/src/api/client.ts): `apps/web/src/api/client.ts`

### Experience Discovery

- [Experience catalog](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/catalog.py): `apps/api/app/api/routes/catalog.py`
- [Semantic search](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/e5_search_service.py): `apps/api/app/services/e5_search_service.py`
- [Evidence verification](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/evidence_service.py): `apps/api/app/services/evidence_service.py`

### Planning and AI

- [Concierge chat](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/chat.py): `apps/api/app/api/routes/chat.py`
- [Planner API](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/planner.py): `apps/api/app/api/routes/planner.py`
- [Itinerary planning](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/planner_service.py): `apps/api/app/services/planner_service.py`
- [Heuristic solver](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/planner_engine.py): `apps/api/app/services/planner_engine.py`
- [ML ranker](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/ml_ranker_service.py): `apps/api/app/services/ml_ranker_service.py`
- [Dynamic replanning](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/replanning_service.py): `apps/api/app/services/replanning_service.py`
- [Goong routing](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/services/routing_service.py): `apps/api/app/services/routing_service.py`

### Bookings and Operations

- [Booking and payment API](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/bookings.py): `apps/api/app/api/routes/bookings.py`
- [Provider management API](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/provider.py): `apps/api/app/api/routes/provider.py`
- [Admin API](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/admin.py): `apps/api/app/api/routes/admin.py`

### API and Data

- [Authentication API](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/api/routes/auth.py): `apps/api/app/api/routes/auth.py`
- [FastAPI application](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [PostgreSQL and PostGIS](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/models/entities.py): `apps/api/app/models/entities.py`
- [LLM provider](https://github.com/nguyentribaothang/localexplorerai/blob/main/apps/api/app/adapters/llm/provider.py): `apps/api/app/adapters/llm/provider.py`

### Other components

- **Traveler**
- **Experience provider**
- **Administrator**
- **Goong Maps**
- **VNPay or MoMo**

## Connections

- Traveler → Web application: uses (evidence: `README.md`)
- Web application → Role-based routes: loads routes (evidence: `apps/web/src/main.tsx`)
- Role-based routes → Explore and chat: routes to (evidence: `apps/web/src/router.tsx`)
- Role-based routes → Itinerary view: routes to (evidence: `apps/web/src/router.tsx`)
- Role-based routes → Provider portal: routes to (evidence: `apps/web/src/router.tsx`)
- Role-based routes → Admin tools: routes to (evidence: `apps/web/src/router.tsx`)
- Explore and chat → API client: requests data
- Itinerary view → API client: requests data (evidence: `apps/web/src/pages/ItineraryPage.tsx`)
- Provider portal → API client: manages bookings (evidence: `apps/web/src/api/client.ts`)
- Admin tools → API client: requests tools
- API client → FastAPI application: calls API (evidence: `apps/web/src/api/client.ts`)
- FastAPI application → Experience catalog: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Concierge chat: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Planner API: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Booking and payment API: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Provider management API: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Admin API: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Authentication API: registers routes (evidence: `apps/api/app/main.py`)
- Explore and chat → Experience catalog: browses experiences (evidence: `README.md`)
- Explore and chat → Semantic search: searches semantically (evidence: `README.md`)
- Experience catalog → Evidence verification: verifies provenance (evidence: `README.md`)
- Explore and chat → Concierge chat: sends constraints (evidence: `README.md`)
- Concierge chat → LLM provider: parses intent (evidence: `README.md`)
- Concierge chat → Planner API: transfers constraints (evidence: `README.md`)
- Planner API → Itinerary planning: requests plan (evidence: `apps/api/app/services/planner_service.py`)
- Itinerary planning → Heuristic solver: selects schedule (evidence: `apps/api/app/services/planner_service.py`)
- Itinerary planning → ML ranker: ranks candidates (evidence: `apps/api/app/services/planner_service.py`)
- Itinerary planning → Goong routing: computes routes (evidence: `apps/api/app/services/planner_service.py`)
- Goong routing → Goong Maps: requests directions (evidence: `apps/api/app/services/routing_service.py`)
- Itinerary view → Dynamic replanning: requests replanning (evidence: `README.md`)
- Booking and payment API → VNPay or MoMo: initiates payment (evidence: `README.md`)
- Traveler → Booking and payment API: books experience (evidence: `README.md`)
- Experience provider → Provider portal: manages availability (evidence: `README.md`)
- Administrator → Admin tools: oversees platform (evidence: `README.md`)
- Booking and payment API → PostgreSQL and PostGIS: holds seats (evidence: `README.md`)
- Provider management API → PostgreSQL and PostGIS: updates offerings (evidence: `README.md`)
- Experience catalog → PostgreSQL and PostGIS: reads catalog
- Authentication API → PostgreSQL and PostGIS: loads accounts (evidence: `apps/api/app/api/routes/auth.py`)
