# sigallage/ceylonroam architecture

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

- Interactive diagram: https://gitdiagram.com/sigallage/ceylonroam
- Repository: https://github.com/sigallage/ceylonroam

## Overview

CeylonRoam combines a web/mobile travel-planning experience with separate itinerary-generation, route-optimization, voice-translation, and account services. The main journey runs from trip preferences to a generated itinerary, route ordering, and saved plans; translation supports travelers during the trip. The README establishes these product stages, while sampled source confirms routing, selected API and persistence behavior. Some frontend-to-service calls and unsampled service internals are documented only at product level, so those links are dashed.

Main entry points: [`frontend/src/pages/routes/router.jsx`](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/routes/router.jsx) (Web App Router), [`backend/routeOptimizer/main.py`](https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/main.py) (Optimizer API), [`frontend/src/pages/Login/LoginPage.jsx`](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/Login/LoginPage.jsx) (Sign-in and Profile), [`backend/authService/server.js`](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/server.js) (Account API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Traveler Experience"]
  node_web["Web App Router<br/>[router.jsx]"]
end

subgraph group_planning["Itinerary Planning"]
  node_planner["Trip Preferences"]
  node_generator["Itinerary Generator<br/>[main.py]"]
  node_results["Plan Results<br/>[Main.jsx]"]
end

subgraph group_routing["Route Optimization"]
  node_optimizer_ui["Route Planner<br/>[routeOptimizer.jsx]"]
  node_optimizer_api["Optimizer API<br/>[main.py]"]
  node_optimizer_core["Route Ordering<br/>[optimizer.py]"]
  node_google_routes["Traffic Routes<br/>[google_routes.py]"]
  node_maps["Google Routes API"]
end

subgraph group_assistance["Language Assistance"]
  node_voice_ui["Voice Translation UI"]
  node_voice_service["Voice Translation Service<br/>[main.py]"]
end

subgraph group_accounts["Accounts and Plans"]
  node_auth_ui["Sign-in and Profile<br/>[LoginPage.jsx]"]
  node_auth_server["Account API<br/>[server.js]"]
  node_auth_routes["Account Routes<br/>[auth.js]"]
  node_auth_controller["Account Workflows<br/>[authController.js]"]
  node_auth_middleware["Token Verification<br/>[authMiddleware.js]"]
  node_user_model[("User Records<br/>[User.js]")]
  node_email["OTP Email<br/>[emailService.js]"]
  node_itinerary_ui["Saved Plan History"]
  node_itinerary_routes["Itinerary Routes<br/>[itinerary.js]"]
  node_itinerary_controller["Plan Persistence"]
  node_itinerary_model[("Saved Itineraries<br/>[Itinerary.js]")]
end

node_traveler(("Traveler"))

node_traveler -->|"uses"| node_web
node_web -->|"routes to"| node_planner
node_planner -.->|"requests plan"| node_generator
node_generator -.->|"returns itinerary"| node_results
node_traveler -->|"selects destinations"| node_optimizer_ui
node_optimizer_ui -.->|"requests ordering"| node_optimizer_api
node_optimizer_api -->|"optimizes order"| node_optimizer_core
node_optimizer_api -->|"requests traffic route"| node_google_routes
node_google_routes -->|"calls"| node_maps
node_traveler -->|"requests translation"| node_voice_ui
node_voice_ui -.->|"sends speech or text"| node_voice_service
node_web -->|"routes to"| node_auth_ui
node_auth_ui -.->|"sends account requests"| node_auth_server
node_auth_server -->|"mounts routes"| node_auth_routes
node_auth_routes -->|"dispatches to"| node_auth_controller
node_auth_controller -->|"reads and writes"| node_user_model
node_auth_controller -->|"sends OTP"| node_email
node_auth_ui -.->|"opens saved plans"| node_itinerary_ui
node_itinerary_ui -.->|"requests saved plans"| node_itinerary_routes
node_auth_server -->|"mounts routes"| node_itinerary_routes
node_itinerary_routes -->|"dispatches to"| node_itinerary_controller
node_itinerary_controller -->|"looks up owner"| node_user_model
node_itinerary_controller -->|"reads and writes"| node_itinerary_model

click node_web "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/routes/router.jsx"
click node_planner "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/itineraryGenerator/itineraryGenerator.jsx"
click node_generator "https://github.com/sigallage/ceylonroam/blob/main/backend/itineraryGenerator/main.py"
click node_results "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/Main/Main.jsx"
click node_optimizer_ui "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/routeOptimizer/routeOptimizer.jsx"
click node_optimizer_api "https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/main.py"
click node_optimizer_core "https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/optimizer.py"
click node_google_routes "https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/google_routes.py"
click node_voice_ui "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/VoiceTranslation/VoiceTranslationPage.jsx"
click node_voice_service "https://github.com/sigallage/ceylonroam/blob/main/backend/voiceTranslation/main.py"
click node_auth_ui "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/Login/LoginPage.jsx"
click node_auth_server "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/server.js"
click node_auth_routes "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/routes/auth.js"
click node_auth_controller "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/controllers/authController.js"
click node_auth_middleware "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/middleware/authMiddleware.js"
click node_user_model "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/models/User.js"
click node_email "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/utils/emailService.js"
click node_itinerary_ui "https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/ItineraryHistory/ItineraryHistory.jsx"
click node_itinerary_routes "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/routes/itinerary.js"
click node_itinerary_controller "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/controllers/itineraryController.js"
click node_itinerary_model "https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/models/Itinerary.js"

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_web toneBlue
class node_planner,node_generator,node_results toneAmber
class node_optimizer_ui,node_optimizer_api,node_optimizer_core,node_google_routes,node_maps toneMint
class node_voice_ui,node_voice_service toneRose
class node_auth_ui,node_auth_server,node_auth_routes,node_auth_controller,node_auth_middleware,node_user_model,node_email,node_itinerary_ui,node_itinerary_routes,node_itinerary_controller,node_itinerary_model,node_traveler toneIndigo
```

## Components

### Traveler Experience

- [Web App Router](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/routes/router.jsx): `frontend/src/pages/routes/router.jsx`

### Itinerary Planning

- [Trip Preferences](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/itineraryGenerator/itineraryGenerator.jsx): `frontend/src/pages/itineraryGenerator/itineraryGenerator.jsx`
- [Itinerary Generator](https://github.com/sigallage/ceylonroam/blob/main/backend/itineraryGenerator/main.py): `backend/itineraryGenerator/main.py`
- [Plan Results](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/Main/Main.jsx): `frontend/src/pages/Main/Main.jsx`

### Route Optimization

- [Route Planner](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/routeOptimizer/routeOptimizer.jsx): `frontend/src/pages/routeOptimizer/routeOptimizer.jsx`
- [Optimizer API](https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/main.py): `backend/routeOptimizer/main.py`
- [Route Ordering](https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/optimizer.py): `backend/routeOptimizer/optimizer.py`
- [Traffic Routes](https://github.com/sigallage/ceylonroam/blob/main/backend/routeOptimizer/google_routes.py): `backend/routeOptimizer/google_routes.py`
- **Google Routes API**

### Language Assistance

- [Voice Translation UI](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/VoiceTranslation/VoiceTranslationPage.jsx): `frontend/src/pages/VoiceTranslation/VoiceTranslationPage.jsx`
- [Voice Translation Service](https://github.com/sigallage/ceylonroam/blob/main/backend/voiceTranslation/main.py): `backend/voiceTranslation/main.py`

### Accounts and Plans

- [Sign-in and Profile](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/Login/LoginPage.jsx): `frontend/src/pages/Login/LoginPage.jsx`
- [Account API](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/server.js): `backend/authService/server.js`
- [Account Routes](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/routes/auth.js): `backend/authService/src/routes/auth.js`
- [Account Workflows](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/controllers/authController.js): `backend/authService/controllers/authController.js`
- [Token Verification](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/middleware/authMiddleware.js): `backend/authService/middleware/authMiddleware.js`
- [User Records](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/models/User.js): `backend/authService/src/models/User.js`
- [OTP Email](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/utils/emailService.js): `backend/authService/utils/emailService.js`
- [Saved Plan History](https://github.com/sigallage/ceylonroam/blob/main/frontend/src/pages/ItineraryHistory/ItineraryHistory.jsx): `frontend/src/pages/ItineraryHistory/ItineraryHistory.jsx`
- [Itinerary Routes](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/routes/itinerary.js): `backend/authService/src/routes/itinerary.js`
- [Plan Persistence](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/controllers/itineraryController.js): `backend/authService/controllers/itineraryController.js`
- [Saved Itineraries](https://github.com/sigallage/ceylonroam/blob/main/backend/authService/src/models/Itinerary.js): `backend/authService/src/models/Itinerary.js`

### Other components

- **Traveler**

## Connections

- Traveler → Web App Router: uses
- Web App Router → Trip Preferences: routes to (evidence: `frontend/src/pages/routes/router.jsx`)
- Trip Preferences → Itinerary Generator: requests plan
- Itinerary Generator → Plan Results: returns itinerary
- Traveler → Route Planner: selects destinations
- Route Planner → Optimizer API: requests ordering
- Optimizer API → Route Ordering: optimizes order (evidence: `backend/routeOptimizer/main.py`)
- Optimizer API → Traffic Routes: requests traffic route (evidence: `backend/routeOptimizer/main.py`)
- Traffic Routes → Google Routes API: calls (evidence: `backend/routeOptimizer/google_routes.py`)
- Traveler → Voice Translation UI: requests translation
- Voice Translation UI → Voice Translation Service: sends speech or text
- Web App Router → Sign-in and Profile: routes to (evidence: `frontend/src/pages/routes/router.jsx`)
- Sign-in and Profile → Account API: sends account requests
- Account API → Account Routes: mounts routes (evidence: `backend/authService/server.js`)
- Account Routes → Account Workflows: dispatches to (evidence: `backend/authService/src/routes/auth.js`)
- Account Workflows → User Records: reads and writes (evidence: `backend/authService/controllers/authController.js`)
- Account Workflows → OTP Email: sends OTP (evidence: `backend/authService/controllers/authController.js`)
- Sign-in and Profile → Saved Plan History: opens saved plans
- Saved Plan History → Itinerary Routes: requests saved plans
- Account API → Itinerary Routes: mounts routes (evidence: `backend/authService/server.js`)
- Itinerary Routes → Plan Persistence: dispatches to (evidence: `backend/authService/src/routes/itinerary.js`)
- Plan Persistence → User Records: looks up owner (evidence: `backend/authService/controllers/itineraryController.js`)
- Plan Persistence → Saved Itineraries: reads and writes (evidence: `backend/authService/controllers/itineraryController.js`)
