# jensenhuangyankai/meetwhenah architecture

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

- Interactive diagram: https://gitdiagram.com/jensenhuangyankai/meetwhenah
- Repository: https://github.com/jensenhuangyankai/meetwhenah

## Overview

WhenMeetAh? coordinates group events through a Telegram bot and an embedded web UI. The flow begins when a participant starts or interacts with the bot, creates an event with a date range, shares it for others to join, and collects each participant’s selected availability. The API persists event, membership, user, and availability records in Supabase; event analysis ranks common meeting slots for the bot to present. The README documents the Telegram-to-web UI experience, while source excerpts confirm key API and selection behavior; unsampled page and bot wiring is represented conservatively.

Main entry points: [`frontend/lib/supabase.ts`](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/supabase.ts) (Supabase access), [`frontend/lib/api-client.ts`](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/api-client.ts) (API client), [`python-backend/telegram.py`](https://github.com/jensenhuangyankai/meetwhenah/blob/main/python-backend/telegram.py) (Telegram bot), [`frontend/app/api/event-analysis/route.ts`](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/event-analysis/route.ts) (Event analysis API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram bot"]
  node_telegram["Telegram bot<br/>[telegram.py]"]
  node_botdb["Bot data access<br/>[supabase_db.py]"]
end

subgraph group_webui["Embedded web UI"]
  node_eventui["Event date picker<br/>[page.jsx]"]
  node_datepicker["Date-range UI"]
  node_selectui["Availability selector<br/>[page.tsx]"]
  node_dragselector["Grid selection<br/>[DragSelector.tsx]"]
  node_area["Area selection"]
  node_selected["Selected slots<br/>[useSelected.tsx]"]
  node_websubmit["Web submission<br/>[route.ts]"]
end

subgraph group_api["Application API"]
  node_client["API client<br/>[api-client.ts]"]
  node_users["User API<br/>[route.ts]"]
  node_events["Event API<br/>[route.ts]"]
  node_members["Membership API<br/>[route.ts]"]
  node_availability["Availability API<br/>[route.ts]"]
  node_analysis["Event analysis API<br/>[route.ts]"]
end

subgraph group_data["Persistence and analysis"]
  node_utils["Slot calculations"]
  node_supabase["Supabase access<br/>[supabase.ts]"]
  node_database[("Supabase database")]
end

node_participant(("Participant"))
node_telegramservice(("Telegram platform"))

node_participant -->|"messages"| node_telegramservice
node_telegram -->|"sends replies"| node_telegramservice
node_telegram -->|"presents results"| node_participant
node_telegram -->|"opens web app"| node_eventui
node_participant -->|"sets date range"| node_eventui
node_eventui -->|"submits event"| node_client
node_participant -->|"selects slots"| node_selectui
node_selectui -->|"renders grid"| node_dragselector
node_dragselector -->|"tracks gesture"| node_area
node_dragselector -->|"checks selection"| node_selected
node_selectui -->|"submits availability"| node_websubmit
node_client -->|"requests users"| node_users
node_client -->|"requests events"| node_events
node_client -->|"requests membership"| node_members
node_client -->|"requests availability"| node_availability
node_client -->|"requests analysis"| node_analysis
node_websubmit -->|"reads and writes"| node_supabase
node_users -->|"reads and writes"| node_supabase
node_events -->|"reads and writes"| node_supabase
node_members -->|"reads and writes"| node_supabase
node_availability -->|"reads and writes"| node_supabase
node_analysis -->|"reads event data"| node_supabase
node_analysis -->|"calculates slots"| node_utils
node_supabase -->|"queries"| node_database
node_telegram -->|"uses data access"| node_botdb
node_botdb -.->|"accesses records"| node_database
node_telegram -.->|"requests best times"| node_analysis

click node_telegram "https://github.com/jensenhuangyankai/meetwhenah/blob/main/python-backend/telegram.py"
click node_eventui "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/datepicker/page.jsx"
click node_datepicker "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/datepicker/CustomDateRangePicker.jsx"
click node_selectui "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/dragselector/page.tsx"
click node_dragselector "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/dragselector/DragSelector.tsx"
click node_area "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/dragselector/useAreaSelection.tsx"
click node_selected "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/dragselector/useSelected.tsx"
click node_websubmit "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/webapp-submit/route.ts"
click node_client "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/api-client.ts"
click node_users "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/users/route.ts"
click node_events "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/events/route.ts"
click node_members "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/event-members/route.ts"
click node_availability "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/availability/route.ts"
click node_analysis "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/event-analysis/route.ts"
click node_utils "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/availability-utils.ts"
click node_supabase "https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/supabase.ts"
click node_botdb "https://github.com/jensenhuangyankai/meetwhenah/blob/main/python-backend/supabase_db.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_telegram,node_botdb toneBlue
class node_eventui,node_datepicker,node_selectui,node_dragselector,node_area,node_selected,node_websubmit toneAmber
class node_client,node_users,node_events,node_members,node_availability,node_analysis toneMint
class node_utils,node_supabase,node_database toneRose
class node_participant,node_telegramservice toneIndigo
```

## Components

### Telegram bot

- [Telegram bot](https://github.com/jensenhuangyankai/meetwhenah/blob/main/python-backend/telegram.py): `python-backend/telegram.py`
- [Bot data access](https://github.com/jensenhuangyankai/meetwhenah/blob/main/python-backend/supabase_db.py): `python-backend/supabase_db.py`

### Embedded web UI

- [Event date picker](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/datepicker/page.jsx): `frontend/app/datepicker/page.jsx`
- [Date-range UI](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/datepicker/CustomDateRangePicker.jsx): `frontend/components/datepicker/CustomDateRangePicker.jsx`
- [Availability selector](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/dragselector/page.tsx): `frontend/app/dragselector/page.tsx`
- [Grid selection](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/dragselector/DragSelector.tsx): `frontend/components/dragselector/DragSelector.tsx`
- [Area selection](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/dragselector/useAreaSelection.tsx): `frontend/components/dragselector/useAreaSelection.tsx`
- [Selected slots](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/components/dragselector/useSelected.tsx): `frontend/components/dragselector/useSelected.tsx`
- [Web submission](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/webapp-submit/route.ts): `frontend/app/api/webapp-submit/route.ts`

### Application API

- [API client](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/api-client.ts): `frontend/lib/api-client.ts`
- [User API](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/users/route.ts): `frontend/app/api/users/route.ts`
- [Event API](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/events/route.ts): `frontend/app/api/events/route.ts`
- [Membership API](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/event-members/route.ts): `frontend/app/api/event-members/route.ts`
- [Availability API](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/availability/route.ts): `frontend/app/api/availability/route.ts`
- [Event analysis API](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/app/api/event-analysis/route.ts): `frontend/app/api/event-analysis/route.ts`

### Persistence and analysis

- [Slot calculations](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/availability-utils.ts): `frontend/lib/availability-utils.ts`
- [Supabase access](https://github.com/jensenhuangyankai/meetwhenah/blob/main/frontend/lib/supabase.ts): `frontend/lib/supabase.ts`
- **Supabase database**

### Other components

- **Participant**
- **Telegram platform**

## Connections

- Participant → Telegram platform: messages
- Telegram bot → Telegram platform: sends replies
- Telegram bot → Participant: presents results
- Telegram bot → Event date picker: opens web app
- Participant → Event date picker: sets date range
- Event date picker → API client: submits event
- Participant → Availability selector: selects slots
- Availability selector → Grid selection: renders grid
- Grid selection → Area selection: tracks gesture
- Grid selection → Selected slots: checks selection
- Availability selector → Web submission: submits availability
- API client → User API: requests users
- API client → Event API: requests events
- API client → Membership API: requests membership
- API client → Availability API: requests availability
- API client → Event analysis API: requests analysis
- Web submission → Supabase access: reads and writes
- User API → Supabase access: reads and writes
- Event API → Supabase access: reads and writes
- Membership API → Supabase access: reads and writes
- Availability API → Supabase access: reads and writes
- Event analysis API → Supabase access: reads event data
- Event analysis API → Slot calculations: calculates slots
- Supabase access → Supabase database: queries
- Telegram bot → Bot data access: uses data access
- Bot data access → Supabase database: accesses records
- Telegram bot → Event analysis API: requests best times