# ravadakaran/tripsync-ai-real-time-collaborative-travel-planning architecture

> Architecture diagram of the GitHub repository ravadakaran/tripsync-ai-real-time-collaborative-travel-planning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning
- Repository: https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning

## Overview

TripSync AI is a collaborative travel-planning application: travelers create or join a trip room, build a shared itinerary, and coordinate votes, budgets, and recommendations. The React client talks to a single FastAPI backend; its process-local room authority handles shared state and real-time collaboration, with PostgreSQL providing persistence. Major product branches also cover grounded Concierge suggestions, conflicts, analytics, and dataset administration. The README documents the product flow and capabilities; some API and real-time implementation details were not sampled, so those connections are shown only where documented or indexed.

Main entry points: [`backend/app/main.py`](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/main.py) (FastAPI Application), [`frontend/src/main.jsx`](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/main.jsx) (React Workspace), [`backend/app/realtime/rooms.py`](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/realtime/rooms.py) (Room Authority), [`backend/app/concierge/service.py`](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/service.py) (Grounded Concierge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Traveler Workspace"]
  node_client_app["React Workspace<br/>[main.jsx]"]
  node_trip_views["Trip Overview<br/>[TripOverview.jsx]"]
  node_board_view["Shared Board<br/>[BoardGrid.jsx]"]
  node_planning_view["Voting and Budget UI<br/>[PlanningPanel.jsx]"]
  node_concierge_view["Concierge UI<br/>[ConciergePanel.jsx]"]
  node_dashboard_view["Dashboard UI<br/>[Dashboard.jsx]"]
  node_admin_view["Dataset Admin UI<br/>[DatasetAdmin.jsx]"]
end

subgraph group_core["Trip Coordination"]
  node_trip_api["Trip API<br/>[trips.py]"]
  node_room_authority["Room Authority<br/>[rooms.py]"]
  node_socket_gateway["Realtime Gateway<br/>[gateway.py]"]
  node_lifecycle["Board Lifecycle<br/>[lifecycle.py]"]
  node_moderation["Room Moderation<br/>[moderation.py]"]
  node_voting["Voting Elections<br/>[service.py]"]
  node_budget["Budget Allocation<br/>[engine.py]"]
end

subgraph group_assist["Planning Assistance"]
  node_catalog_api["Catalog API<br/>[catalog.py]"]
  node_concierge_api["Concierge API<br/>[concierge.py]"]
  node_concierge["Grounded Concierge<br/>[service.py]"]
  node_constraints["Travel Constraints<br/>[constraints.py]"]
  node_preferences["Traveler Preferences<br/>[preferences.py]"]
  node_rag["Retrieval and Generation<br/>[rag.py]"]
  node_conflicts["Schedule Conflicts<br/>[conflicts.py]"]
end

subgraph group_platform["Backend Services"]
  node_api_server["FastAPI Application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_insights["Insights and Data"]
  node_phase_api["Phase Three API<br/>[phase3.py]"]
  node_recommendations["Recommendations<br/>[service.py]"]
  node_recommendation_model["Hybrid Ranking<br/>[engine.py]"]
  node_analytics["Session Analytics<br/>[service.py]"]
  node_dataset_import["Dataset Ingestion<br/>[importer.py]"]
  node_dataset_schema["Dataset Schema<br/>[schema.py]"]
end

node_traveler(("Traveler"))
node_local_model["Local Inference Service"]

node_traveler -->|"uses"| node_client_app
node_client_app -->|"requests"| node_api_server
node_api_server -->|"mounts"| node_auth_api
node_api_server -->|"mounts"| node_trip_api
node_api_server -->|"mounts"| node_catalog_api
node_api_server -->|"mounts"| node_concierge_api
node_api_server -->|"mounts"| node_phase_api
node_api_server -->|"initializes"| node_room_authority
node_api_server -->|"connects"| node_postgres
node_api_server -->|"configures client"| node_local_model
node_client_app -->|"renders"| node_trip_views
node_client_app -->|"renders"| node_board_view
node_client_app -->|"renders"| node_planning_view
node_client_app -->|"renders"| node_concierge_view
node_client_app -->|"renders"| node_dashboard_view
node_client_app -->|"renders"| node_admin_view
node_trip_api -.->|"coordinates rooms"| node_room_authority
node_socket_gateway -.->|"dispatches events"| node_room_authority
node_room_authority -->|"applies lifecycle"| node_lifecycle
node_room_authority -->|"uses elections"| node_voting
node_room_authority -->|"uses allocations"| node_budget
node_moderation -->|"moderates"| node_room_authority
node_voting -->|"detects conflicts"| node_conflicts
node_concierge_api -.->|"requests suggestions"| node_concierge
node_concierge -->|"filters candidates"| node_constraints
node_concierge -->|"loads preferences"| node_preferences
node_concierge -->|"grounds answers"| node_rag
node_phase_api -.->|"serves recommendations"| node_recommendations
node_recommendations -->|"ranks candidates"| node_recommendation_model
node_phase_api -.->|"serves analytics"| node_analytics
node_phase_api -.->|"stages datasets"| node_dataset_import
node_dataset_import -.->|"validates with"| node_dataset_schema
node_room_authority -.->|"persists room state"| node_postgres

click node_client_app "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/main.jsx"
click node_trip_views "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/workspace/TripOverview.jsx"
click node_board_view "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/board/BoardGrid.jsx"
click node_planning_view "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/votes/PlanningPanel.jsx"
click node_concierge_view "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/board/ConciergePanel.jsx"
click node_dashboard_view "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/dashboard/Dashboard.jsx"
click node_admin_view "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/admin/DatasetAdmin.jsx"
click node_api_server "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/auth.py"
click node_trip_api "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/trips.py"
click node_catalog_api "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/catalog.py"
click node_concierge_api "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/concierge.py"
click node_phase_api "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/phase3.py"
click node_room_authority "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/realtime/rooms.py"
click node_socket_gateway "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/realtime/gateway.py"
click node_lifecycle "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/board/lifecycle.py"
click node_moderation "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/rooms/moderation.py"
click node_voting "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/voting/service.py"
click node_budget "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/budget/engine.py"
click node_concierge "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/service.py"
click node_constraints "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/constraints.py"
click node_preferences "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/preferences.py"
click node_rag "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/rag.py"
click node_conflicts "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/conflicts.py"
click node_recommendations "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/recommendations/service.py"
click node_recommendation_model "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/recommendations/engine.py"
click node_analytics "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/analytics/service.py"
click node_dataset_import "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/datasets/importer.py"
click node_dataset_schema "https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/datasets/schema.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_client_app,node_trip_views,node_board_view,node_planning_view,node_concierge_view,node_dashboard_view,node_admin_view toneBlue
class node_trip_api,node_room_authority,node_socket_gateway,node_lifecycle,node_moderation,node_voting,node_budget toneAmber
class node_catalog_api,node_concierge_api,node_concierge,node_constraints,node_preferences,node_rag,node_conflicts toneMint
class node_api_server,node_auth_api,node_postgres toneRose
class node_phase_api,node_recommendations,node_recommendation_model,node_analytics,node_dataset_import,node_dataset_schema,node_traveler,node_local_model toneIndigo
```

## Components

### Traveler Workspace

- [React Workspace](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Trip Overview](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/workspace/TripOverview.jsx): `frontend/src/workspace/TripOverview.jsx`
- [Shared Board](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/board/BoardGrid.jsx): `frontend/src/board/BoardGrid.jsx`
- [Voting and Budget UI](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/votes/PlanningPanel.jsx): `frontend/src/votes/PlanningPanel.jsx`
- [Concierge UI](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/board/ConciergePanel.jsx): `frontend/src/board/ConciergePanel.jsx`
- [Dashboard UI](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/dashboard/Dashboard.jsx): `frontend/src/dashboard/Dashboard.jsx`
- [Dataset Admin UI](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/frontend/src/admin/DatasetAdmin.jsx): `frontend/src/admin/DatasetAdmin.jsx`

### Trip Coordination

- [Trip API](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/trips.py): `backend/app/api/trips.py`
- [Room Authority](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/realtime/rooms.py): `backend/app/realtime/rooms.py`
- [Realtime Gateway](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/realtime/gateway.py): `backend/app/realtime/gateway.py`
- [Board Lifecycle](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/board/lifecycle.py): `backend/app/board/lifecycle.py`
- [Room Moderation](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/rooms/moderation.py): `backend/app/rooms/moderation.py`
- [Voting Elections](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/voting/service.py): `backend/app/voting/service.py`
- [Budget Allocation](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/budget/engine.py): `backend/app/budget/engine.py`

### Planning Assistance

- [Catalog API](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/catalog.py): `backend/app/api/catalog.py`
- [Concierge API](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/concierge.py): `backend/app/api/concierge.py`
- [Grounded Concierge](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/service.py): `backend/app/concierge/service.py`
- [Travel Constraints](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/constraints.py): `backend/app/concierge/constraints.py`
- [Traveler Preferences](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/preferences.py): `backend/app/concierge/preferences.py`
- [Retrieval and Generation](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/rag.py): `backend/app/concierge/rag.py`
- [Schedule Conflicts](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/concierge/conflicts.py): `backend/app/concierge/conflicts.py`

### Backend Services

- [FastAPI Application](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- **PostgreSQL**

### Insights and Data

- [Phase Three API](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/api/phase3.py): `backend/app/api/phase3.py`
- [Recommendations](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/recommendations/service.py): `backend/app/recommendations/service.py`
- [Hybrid Ranking](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/recommendations/engine.py): `backend/app/recommendations/engine.py`
- [Session Analytics](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/analytics/service.py): `backend/app/analytics/service.py`
- [Dataset Ingestion](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/datasets/importer.py): `backend/app/datasets/importer.py`
- [Dataset Schema](https://github.com/ravadakaran/tripsync-ai-real-time-collaborative-travel-planning/blob/main/backend/app/datasets/schema.py): `backend/app/datasets/schema.py`

### Other components

- **Traveler**
- **Local Inference Service**

## Connections

- Traveler → React Workspace: uses (evidence: `README.md`)
- React Workspace → FastAPI Application: requests (evidence: `README.md`)
- FastAPI Application → Authentication API: mounts (evidence: `backend/app/main.py`)
- FastAPI Application → Trip API: mounts (evidence: `backend/app/main.py`)
- FastAPI Application → Catalog API: mounts (evidence: `backend/app/main.py`)
- FastAPI Application → Concierge API: mounts (evidence: `backend/app/main.py`)
- FastAPI Application → Phase Three API: mounts (evidence: `backend/app/main.py`)
- FastAPI Application → Room Authority: initializes (evidence: `backend/app/main.py`)
- FastAPI Application → PostgreSQL: connects (evidence: `backend/app/main.py`)
- FastAPI Application → Local Inference Service: configures client (evidence: `backend/app/main.py`)
- React Workspace → Trip Overview: renders (evidence: `frontend/src/main.jsx`)
- React Workspace → Shared Board: renders (evidence: `frontend/src/main.jsx`)
- React Workspace → Voting and Budget UI: renders (evidence: `frontend/src/main.jsx`)
- React Workspace → Concierge UI: renders (evidence: `frontend/src/main.jsx`)
- React Workspace → Dashboard UI: renders (evidence: `frontend/src/main.jsx`)
- React Workspace → Dataset Admin UI: renders (evidence: `frontend/src/main.jsx`)
- Trip API → Room Authority: coordinates rooms
- Realtime Gateway → Room Authority: dispatches events
- Room Authority → Board Lifecycle: applies lifecycle (evidence: `backend/app/realtime/rooms.py`)
- Room Authority → Voting Elections: uses elections (evidence: `backend/app/realtime/rooms.py`)
- Room Authority → Budget Allocation: uses allocations (evidence: `backend/app/realtime/rooms.py`)
- Room Moderation → Room Authority: moderates (evidence: `backend/app/rooms/moderation.py`)
- Voting Elections → Schedule Conflicts: detects conflicts (evidence: `backend/app/voting/service.py`)
- Concierge API → Grounded Concierge: requests suggestions
- Grounded Concierge → Travel Constraints: filters candidates (evidence: `backend/app/concierge/service.py`)
- Grounded Concierge → Traveler Preferences: loads preferences (evidence: `backend/app/concierge/service.py`)
- Grounded Concierge → Retrieval and Generation: grounds answers (evidence: `backend/app/concierge/service.py`)
- Phase Three API → Recommendations: serves recommendations
- Recommendations → Hybrid Ranking: ranks candidates (evidence: `backend/app/recommendations/service.py`)
- Phase Three API → Session Analytics: serves analytics
- Phase Three API → Dataset Ingestion: stages datasets
- Dataset Ingestion → Dataset Schema: validates with
- Room Authority → PostgreSQL: persists room state