# ansh5922/wetravel architecture

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

- Interactive diagram: https://gitdiagram.com/ansh5922/wetravel
- Repository: https://github.com/ansh5922/wetravel

## Overview

WeTravel is a group-travel platform with a Node.js API for accounts, trips, collaboration, expenses, and memories, plus a FastAPI AI service for itinerary-related intelligence, preference embeddings, consensus, and receipt OCR. The main user workflow is to create or join a trip, coordinate plans and chat, then record shared expenses and memories. Sampled source confirms the Node expense route-to-controller flow and AI embedding/OCR controller calls; other subsystem links are included only at the documented or tree-supported module level.

Main entry points: [`backend/src/index.js`](https://github.com/ansh5922/wetravel/blob/main/backend/src/index.js) (HTTP API), [`backend/src/services/expense.service.js`](https://github.com/ansh5922/wetravel/blob/main/backend/src/services/expense.service.js) (Expense logic), [`ai/app/controllers`](https://github.com/ansh5922/wetravel/tree/main/ai/app/controllers) (AI controllers), [`ai/app/main.py`](https://github.com/ansh5922/wetravel/blob/main/ai/app/main.py) (AI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Core backend"]
  node_api["HTTP API<br/>[index.js]"]
  node_auth["Accounts and auth<br/>[auth.service.js]"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
end

subgraph group_collaboration["Trip collaboration"]
  node_trips["Trips and invites<br/>[trip.controller.js]"]
  node_trip_routes["Trip routes<br/>[trip.routes.js]"]
  node_social["Users and friends"]
  node_chat["Group chat<br/>[chat.service.js]"]
  node_chat_routes["Chat routes<br/>[chat.routes.js]"]
  node_realtime["WebSocket delivery"]
  node_itinerary["Itinerary planning"]
  node_memory["Trip memories"]
end

subgraph group_finance["Expenses and receipts"]
  node_expense_routes["Expense routes<br/>[expense.routes.js]"]
  node_expense_controller["Expense handling"]
  node_expense_service["Expense logic<br/>[expense.service.js]"]
  node_expense_repo["Expense records"]
  node_imagekit["Image uploads"]
end

subgraph group_ai["AI services"]
  node_ai_api["AI API<br/>[main.py]"]
  node_ai_routes["AI routes"]
  node_ai_controllers["AI controllers"]
  node_ai_services["AI services"]
  node_embedding["Preference embeddings"]
  node_consensus["Group consensus"]
  node_ocr_engine["Receipt OCR<br/>[ocr_service.py]"]
end

subgraph group_storage["Persistence"]
  node_database[("Application database<br/>[prisma.client.js]")]
  node_ai_database[("AI profile store<br/>[database.py]")]
end

node_traveler(("Traveler"))
node_travel_api["Travel data API"]

node_traveler -->|"sends requests"| node_api
node_api -->|"mounts"| node_auth_routes
node_auth_routes -->|"routes auth"| node_auth
node_api -->|"mounts"| node_trip_routes
node_trip_routes -->|"routes trip actions"| node_trips
node_api -->|"mounts"| node_chat_routes
node_chat_routes -->|"routes chat"| node_chat
node_api -->|"mounts"| node_expense_routes
node_expense_routes -->|"dispatches"| node_expense_controller
node_expense_controller -->|"calls"| node_expense_service
node_expense_service -->|"uses"| node_expense_repo
node_expense_repo -->|"reads and writes"| node_database
node_expense_service -->|"requests upload auth"| node_imagekit
node_expense_service -.->|"submits receipt OCR"| node_ai_api
node_expense_service -.->|"notifies OCR result"| node_realtime
node_api -->|"attaches server"| node_realtime
node_api -->|"mounts memory routes"| node_memory
node_api -->|"mounts itinerary routes"| node_itinerary
node_api -->|"mounts user and friend routes"| node_social
node_api -.->|"separate service"| node_ai_api
node_traveler -->|"requests AI features"| node_ai_api
node_ai_api -->|"mounts routers"| node_ai_routes
node_ai_routes -->|"dispatches"| node_ai_controllers
node_ai_controllers -->|"calls"| node_ai_services
node_ai_controllers -->|"generates embeddings"| node_embedding
node_embedding -->|"saves profile vector"| node_ai_database
node_ai_controllers -->|"processes receipt"| node_ocr_engine
node_ai_controllers -->|"loads and saves consensus"| node_consensus
node_consensus -->|"reads and writes"| node_ai_database
node_ai_services -.->|"fetches travel data"| node_travel_api

click node_api "https://github.com/ansh5922/wetravel/blob/main/backend/src/index.js"
click node_auth "https://github.com/ansh5922/wetravel/blob/main/backend/src/services/auth.service.js"
click node_auth_routes "https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/auth.routes.js"
click node_trips "https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/trip.controller.js"
click node_trip_routes "https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/trip.routes.js"
click node_social "https://github.com/ansh5922/wetravel/tree/main/backend/src/controllers"
click node_chat "https://github.com/ansh5922/wetravel/blob/main/backend/src/services/chat.service.js"
click node_chat_routes "https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/chat.routes.js"
click node_realtime "https://github.com/ansh5922/wetravel/tree/main/backend/src/websocket"
click node_itinerary "https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/itinerary.controller.js"
click node_memory "https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/memory.controller.js"
click node_expense_routes "https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/expense.routes.js"
click node_expense_controller "https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/expense.controller.js"
click node_expense_service "https://github.com/ansh5922/wetravel/blob/main/backend/src/services/expense.service.js"
click node_expense_repo "https://github.com/ansh5922/wetravel/blob/main/backend/src/repositories/expense.repository.js"
click node_imagekit "https://github.com/ansh5922/wetravel/blob/main/backend/src/services/imagekit.service.js"
click node_ai_api "https://github.com/ansh5922/wetravel/blob/main/ai/app/main.py"
click node_ai_routes "https://github.com/ansh5922/wetravel/tree/main/ai/app/api/routes"
click node_ai_controllers "https://github.com/ansh5922/wetravel/tree/main/ai/app/controllers"
click node_ai_services "https://github.com/ansh5922/wetravel/tree/main/ai/app/services"
click node_embedding "https://github.com/ansh5922/wetravel/blob/main/ai/app/services/embedding_service.py"
click node_consensus "https://github.com/ansh5922/wetravel/blob/main/ai/app/repositories/consensus_repository.py"
click node_database "https://github.com/ansh5922/wetravel/blob/main/backend/src/repositories/prisma.client.js"
click node_ai_database "https://github.com/ansh5922/wetravel/blob/main/ai/app/core/database.py"
click node_ocr_engine "https://github.com/ansh5922/wetravel/blob/main/ai/app/services/ocr_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_api,node_auth,node_auth_routes toneBlue
class node_trips,node_trip_routes,node_social,node_chat,node_chat_routes,node_realtime,node_itinerary,node_memory toneAmber
class node_expense_routes,node_expense_controller,node_expense_service,node_expense_repo,node_imagekit,node_travel_api toneMint
class node_ai_api,node_ai_routes,node_ai_controllers,node_ai_services,node_embedding,node_consensus,node_ocr_engine toneRose
class node_database,node_ai_database,node_traveler toneIndigo
```

## Components

### Core backend

- [HTTP API](https://github.com/ansh5922/wetravel/blob/main/backend/src/index.js): `backend/src/index.js`
- [Accounts and auth](https://github.com/ansh5922/wetravel/blob/main/backend/src/services/auth.service.js): `backend/src/services/auth.service.js`
- [Auth routes](https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`

### Trip collaboration

- [Trips and invites](https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/trip.controller.js): `backend/src/controllers/trip.controller.js`
- [Trip routes](https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/trip.routes.js): `backend/src/routes/trip.routes.js`
- [Users and friends](https://github.com/ansh5922/wetravel/tree/main/backend/src/controllers): `backend/src/controllers`
- [Group chat](https://github.com/ansh5922/wetravel/blob/main/backend/src/services/chat.service.js): `backend/src/services/chat.service.js`
- [Chat routes](https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/chat.routes.js): `backend/src/routes/chat.routes.js`
- [WebSocket delivery](https://github.com/ansh5922/wetravel/tree/main/backend/src/websocket): `backend/src/websocket`
- [Itinerary planning](https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/itinerary.controller.js): `backend/src/controllers/itinerary.controller.js`
- [Trip memories](https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/memory.controller.js): `backend/src/controllers/memory.controller.js`

### Expenses and receipts

- [Expense routes](https://github.com/ansh5922/wetravel/blob/main/backend/src/routes/expense.routes.js): `backend/src/routes/expense.routes.js`
- [Expense handling](https://github.com/ansh5922/wetravel/blob/main/backend/src/controllers/expense.controller.js): `backend/src/controllers/expense.controller.js`
- [Expense logic](https://github.com/ansh5922/wetravel/blob/main/backend/src/services/expense.service.js): `backend/src/services/expense.service.js`
- [Expense records](https://github.com/ansh5922/wetravel/blob/main/backend/src/repositories/expense.repository.js): `backend/src/repositories/expense.repository.js`
- [Image uploads](https://github.com/ansh5922/wetravel/blob/main/backend/src/services/imagekit.service.js): `backend/src/services/imagekit.service.js`

### AI services

- [AI API](https://github.com/ansh5922/wetravel/blob/main/ai/app/main.py): `ai/app/main.py`
- [AI routes](https://github.com/ansh5922/wetravel/tree/main/ai/app/api/routes): `ai/app/api/routes`
- [AI controllers](https://github.com/ansh5922/wetravel/tree/main/ai/app/controllers): `ai/app/controllers`
- [AI services](https://github.com/ansh5922/wetravel/tree/main/ai/app/services): `ai/app/services`
- [Preference embeddings](https://github.com/ansh5922/wetravel/blob/main/ai/app/services/embedding_service.py): `ai/app/services/embedding_service.py`
- [Group consensus](https://github.com/ansh5922/wetravel/blob/main/ai/app/repositories/consensus_repository.py): `ai/app/repositories/consensus_repository.py`
- [Receipt OCR](https://github.com/ansh5922/wetravel/blob/main/ai/app/services/ocr_service.py): `ai/app/services/ocr_service.py`

### Persistence

- [Application database](https://github.com/ansh5922/wetravel/blob/main/backend/src/repositories/prisma.client.js): `backend/src/repositories/prisma.client.js`
- [AI profile store](https://github.com/ansh5922/wetravel/blob/main/ai/app/core/database.py): `ai/app/core/database.py`

### Other components

- **Traveler**
- **Travel data API**

## Connections

- Traveler → HTTP API: sends requests
- HTTP API → Auth routes: mounts
- Auth routes → Accounts and auth: routes auth
- HTTP API → Trip routes: mounts
- Trip routes → Trips and invites: routes trip actions
- HTTP API → Chat routes: mounts
- Chat routes → Group chat: routes chat
- HTTP API → Expense routes: mounts
- Expense routes → Expense handling: dispatches
- Expense handling → Expense logic: calls
- Expense logic → Expense records: uses
- Expense records → Application database: reads and writes
- Expense logic → Image uploads: requests upload auth
- Expense logic → AI API: submits receipt OCR
- Expense logic → WebSocket delivery: notifies OCR result
- HTTP API → WebSocket delivery: attaches server
- HTTP API → Trip memories: mounts memory routes
- HTTP API → Itinerary planning: mounts itinerary routes
- HTTP API → Users and friends: mounts user and friend routes
- HTTP API → AI API: separate service
- Traveler → AI API: requests AI features
- AI API → AI routes: mounts routers
- AI routes → AI controllers: dispatches
- AI controllers → AI services: calls
- AI controllers → Preference embeddings: generates embeddings
- Preference embeddings → AI profile store: saves profile vector
- AI controllers → Receipt OCR: processes receipt
- AI controllers → Group consensus: loads and saves consensus
- Group consensus → AI profile store: reads and writes
- AI services → Travel data API: fetches travel data