# mirsinghh/hackupc2025 architecture

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

- Interactive diagram: https://gitdiagram.com/mirsinghh/hackupc2025
- Repository: https://github.com/mirsinghh/hackupc2025

## Overview

Midpoint is a group trip-planning web app. Users sign in, create or join a group, submit travel preferences, and view group members’ preferences before requesting AI-generated destination suggestions. Suggested destinations have a results view, while separate endpoints provide flight and car-hire searches; group invitations and an AI chat endpoint are additional capabilities. The graph follows the sampled page and API behavior; wiring inside unsampled components, including the suggestion button and group modal, is not asserted.

Main entry points: [`frontend/src/app/page.tsx`](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/page.tsx) (Home & groups), [`frontend/src/app/groups/[id]/page.tsx`](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/groups/%5Bid%5D/page.tsx) (Group details), [`frontend/src/app/api/trip/submit/route.ts`](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/trip/submit/route.ts) (Save preferences), [`frontend/src/app/api/suggest-trip/route.ts`](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/suggest-trip/route.ts) (Suggestion API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity_groups["Identity & groups"]
  node_home["Home &amp; groups<br/>[page.tsx]"]
  node_group_page["Group details<br/>[page.tsx]"]
  node_group_list["Group list<br/>[GroupList.tsx]"]
  node_group_modal["Group modal<br/>[GroupModal.tsx]"]
  node_user_model[("User records<br/>[user.ts]")]
  node_group_model[("Group records<br/>[groups.ts]")]
  node_database[("MongoDB<br/>[mongodb.js]")]
  node_auth["Auth0 session<br/>[auth0.ts]"]
  node_invite_api["Invitation API<br/>[route.ts]"]
end

subgraph group_trip_planning["Trip planning"]
  node_preferences["Preferences form<br/>[page.tsx]"]
  node_submit_api["Save preferences<br/>[route.ts]"]
end

subgraph group_recommendations["Recommendations"]
  node_suggest_button["Suggestion control<br/>[SuggestButton.tsx]"]
  node_suggest_api["Suggestion API<br/>[route.ts]"]
  node_prompt_builder["Prompt builder<br/>[promptBuilder.ts]"]
  node_gemini_helper["Gemini client<br/>[gemini.ts]"]
  node_result_page["Trip results<br/>[page.tsx]"]
  node_chat_api["Chat API<br/>[route.ts]"]
end

subgraph group_integrations["External services"]
  node_email_service["Email service"]
  node_gemini_service["Gemini"]
  node_flight_api["Flight search API<br/>[route.ts]"]
  node_car_api["Car hire API<br/>[route.ts]"]
  node_skyscanner["Skyscanner"]
end

node_traveler(("Traveler"))

node_traveler -->|"opens"| node_home
node_home -->|"checks session"| node_auth
node_home -->|"connects"| node_database
node_home -->|"finds or updates"| node_user_model
node_home -->|"queries or creates"| node_group_model
node_home -->|"renders"| node_group_list
node_group_list -->|"opens"| node_group_modal
node_traveler -->|"opens"| node_group_page
node_group_page -->|"connects"| node_database
node_group_page -->|"loads group"| node_group_model
node_group_page -->|"loads members"| node_user_model
node_group_page -->|"renders"| node_suggest_button
node_traveler -->|"submits"| node_preferences
node_preferences -->|"posts preferences"| node_submit_api
node_submit_api -->|"checks session"| node_auth
node_submit_api -->|"connects"| node_database
node_submit_api -->|"updates preferences"| node_user_model
node_suggest_button -->|"requests suggestions"| node_suggest_api
node_suggest_api -->|"builds prompt"| node_prompt_builder
node_suggest_api -->|"requests response"| node_gemini_helper
node_gemini_helper -->|"calls"| node_gemini_service
node_traveler -->|"views"| node_result_page
node_traveler -->|"sends message"| node_chat_api
node_chat_api -->|"generates response"| node_gemini_service
node_traveler -->|"searches flights"| node_flight_api
node_flight_api -->|"creates and polls"| node_skyscanner
node_traveler -->|"searches car hire"| node_car_api
node_car_api -->|"forwards search"| node_skyscanner
node_traveler -->|"invites members"| node_invite_api
node_invite_api -->|"sends email"| node_email_service

click node_home "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/page.tsx"
click node_group_page "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/groups/%5Bid%5D/page.tsx"
click node_group_list "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/components/GroupList.tsx"
click node_group_modal "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/components/GroupModal.tsx"
click node_user_model "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/models/user.ts"
click node_group_model "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/models/groups.ts"
click node_database "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/mongodb.js"
click node_auth "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/auth0.ts"
click node_invite_api "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/send-invitations/route.ts"
click node_preferences "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/preferences/page.tsx"
click node_submit_api "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/trip/submit/route.ts"
click node_suggest_button "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/components/SuggestButton.tsx"
click node_suggest_api "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/suggest-trip/route.ts"
click node_prompt_builder "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/promptBuilder.ts"
click node_gemini_helper "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/gemini.ts"
click node_result_page "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/trip-result/page.tsx"
click node_chat_api "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/chat/route.ts"
click node_flight_api "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/flight/search/route.ts"
click node_car_api "https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/skyscanner/route.ts"

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_home,node_group_page,node_group_list,node_group_modal,node_user_model,node_group_model,node_database,node_auth,node_invite_api toneBlue
class node_preferences,node_submit_api toneAmber
class node_suggest_button,node_suggest_api,node_prompt_builder,node_gemini_helper,node_result_page,node_chat_api toneMint
class node_email_service,node_gemini_service,node_flight_api,node_car_api,node_skyscanner toneRose
class node_traveler toneIndigo
```

## Components

### Identity & groups

- [Home & groups](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Group details](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/groups/%5Bid%5D/page.tsx): `frontend/src/app/groups/[id]/page.tsx`
- [Group list](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/components/GroupList.tsx): `frontend/src/components/GroupList.tsx`
- [Group modal](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/components/GroupModal.tsx): `frontend/src/components/GroupModal.tsx`
- [User records](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/models/user.ts): `frontend/src/lib/models/user.ts`
- [Group records](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/models/groups.ts): `frontend/src/lib/models/groups.ts`
- [MongoDB](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/mongodb.js): `frontend/src/lib/mongodb.js`
- [Auth0 session](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/auth0.ts): `frontend/src/lib/auth0.ts`
- [Invitation API](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/send-invitations/route.ts): `frontend/src/app/api/send-invitations/route.ts`

### Trip planning

- [Preferences form](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/preferences/page.tsx): `frontend/src/app/preferences/page.tsx`
- [Save preferences](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/trip/submit/route.ts): `frontend/src/app/api/trip/submit/route.ts`

### Recommendations

- [Suggestion control](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/components/SuggestButton.tsx): `frontend/src/components/SuggestButton.tsx`
- [Suggestion API](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/suggest-trip/route.ts): `frontend/src/app/api/suggest-trip/route.ts`
- [Prompt builder](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/promptBuilder.ts): `frontend/src/lib/promptBuilder.ts`
- [Gemini client](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/lib/gemini.ts): `frontend/src/lib/gemini.ts`
- [Trip results](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/trip-result/page.tsx): `frontend/src/app/trip-result/page.tsx`
- [Chat API](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/chat/route.ts): `frontend/src/app/api/chat/route.ts`

### External services

- **Email service**
- **Gemini**
- [Flight search API](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/flight/search/route.ts): `frontend/src/app/api/flight/search/route.ts`
- [Car hire API](https://github.com/mirsinghh/hackupc2025/blob/main/frontend/src/app/api/skyscanner/route.ts): `frontend/src/app/api/skyscanner/route.ts`
- **Skyscanner**

### Other components

- **Traveler**

## Connections

- Traveler → Home & groups: opens
- Home & groups → Auth0 session: checks session
- Home & groups → MongoDB: connects
- Home & groups → User records: finds or updates
- Home & groups → Group records: queries or creates
- Home & groups → Group list: renders
- Group list → Group modal: opens
- Traveler → Group details: opens
- Group details → MongoDB: connects
- Group details → Group records: loads group
- Group details → User records: loads members
- Group details → Suggestion control: renders
- Traveler → Preferences form: submits
- Preferences form → Save preferences: posts preferences
- Save preferences → Auth0 session: checks session
- Save preferences → MongoDB: connects
- Save preferences → User records: updates preferences
- Suggestion control → Suggestion API: requests suggestions
- Suggestion API → Prompt builder: builds prompt
- Suggestion API → Gemini client: requests response
- Gemini client → Gemini: calls
- Traveler → Trip results: views
- Traveler → Chat API: sends message
- Chat API → Gemini: generates response
- Traveler → Flight search API: searches flights
- Flight search API → Skyscanner: creates and polls
- Traveler → Car hire API: searches car hire
- Car hire API → Skyscanner: forwards search
- Traveler → Invitation API: invites members
- Invitation API → Email service: sends email