# querysmith-sys/groupwatch architecture

> Architecture diagram of the GitHub repository querysmith-sys/groupwatch, 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/querysmith-sys/groupwatch
- Repository: https://github.com/querysmith-sys/groupwatch

## Overview

GroupWatch is a browser-based watch-together app: a user creates or joins a room, shares a YouTube video, and watches it synchronized with other participants while chatting. The Next.js home page creates rooms through the Express API or routes users to a room; the watch page checks room existence before mounting the live client. The client and Socket.io server exchange room, chat, video-sharing, and host playback events. Room membership and host identity live in an in-memory map. README capabilities are included; some frontend event wiring is only partially sampled, so uncertain links are omitted.

Main entry points: [`group-watch/app/watch/[id]/WatchClient.tsx`](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/WatchClient.tsx) (Watch interface), [`group-watch-socket/socket/handlers.ts`](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/socket/handlers.ts) (Socket event handlers), [`group-watch-socket/services/room.service.ts`](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/services/room.service.ts) (Room operations), [`group-watch/app/watch/[id]/page.tsx`](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/page.tsx) (Room validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_home["Create or join<br/>[page.tsx]"]
  node_room_page["Room validation<br/>[page.tsx]"]
  node_watch_client["Watch interface<br/>[WatchClient.tsx]"]
  node_host_context["Host state<br/>[hostContext.tsx]"]
end

subgraph group_room_backend["Rooms and membership"]
  node_api_server["HTTP and socket server<br/>[server.ts]"]
  node_room_api["Room API<br/>[room.ts]"]
  node_room_service["Room operations<br/>[room.service.ts]"]
  node_room_store[("In-memory rooms<br/>[room.service.ts]")]
end

subgraph group_live["Live collaboration"]
  node_socket_handlers["Socket event handlers<br/>[handlers.ts]"]
end

subgraph group_video["Video playback"]
  node_youtube_player["YouTube player<br/>[WatchClient.tsx]"]
end

node_participants(("Participants"))
node_youtube{{"YouTube Iframe API"}}

node_participants -->|"create or join"| node_home
node_home -->|"POST create"| node_room_api
node_room_api -->|"creates room"| node_room_service
node_room_service -->|"stores room"| node_room_store
node_home -->|"navigates"| node_room_page
node_participants -->|"opens room"| node_room_page
node_room_page -->|"checks room"| node_room_api
node_room_api -->|"checks existence"| node_room_service
node_room_page -->|"mounts if valid"| node_watch_client
node_watch_client -->|"reads host state"| node_host_context
node_watch_client -->|"opens socket"| node_api_server
node_api_server -->|"dispatches events"| node_socket_handlers
node_socket_handlers -->|"manages membership"| node_room_service
node_room_service -->|"reads and updates"| node_room_store
node_watch_client -->|"sends room events"| node_socket_handlers
node_socket_handlers -->|"broadcasts room events"| node_watch_client
node_watch_client -->|"sends chat"| node_socket_handlers
node_socket_handlers -->|"broadcasts chat"| node_watch_client
node_watch_client -->|"shares video"| node_socket_handlers
node_socket_handlers -->|"broadcasts video"| node_watch_client
node_watch_client -->|"loads API"| node_youtube
node_watch_client -->|"creates player"| node_youtube_player
node_youtube_player -->|"reports playback"| node_watch_client
node_watch_client -->|"sends playback action"| node_socket_handlers
node_socket_handlers -->|"checks host"| node_room_service
node_socket_handlers -->|"relays host action"| node_watch_client
node_participants -->|"chats and watches"| node_watch_client

click node_home "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/page.tsx"
click node_room_page "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/page.tsx"
click node_watch_client "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/WatchClient.tsx"
click node_host_context "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/context/hostContext.tsx"
click node_api_server "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/server.ts"
click node_room_api "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/api/room.ts"
click node_room_service "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/services/room.service.ts"
click node_room_store "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/services/room.service.ts"
click node_socket_handlers "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/socket/handlers.ts"
click node_youtube_player "https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/WatchClient.tsx"

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_room_page,node_watch_client,node_host_context toneBlue
class node_api_server,node_room_api,node_room_service,node_room_store toneAmber
class node_socket_handlers,node_youtube toneMint
class node_youtube_player toneRose
class node_participants toneIndigo
```

## Components

### Web experience

- [Create or join](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/page.tsx): `group-watch/app/page.tsx`
- [Room validation](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/page.tsx): `group-watch/app/watch/[id]/page.tsx`
- [Watch interface](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/WatchClient.tsx): `group-watch/app/watch/[id]/WatchClient.tsx`
- [Host state](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/context/hostContext.tsx): `group-watch/app/context/hostContext.tsx`

### Rooms and membership

- [HTTP and socket server](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/server.ts): `group-watch-socket/server.ts`
- [Room API](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/api/room.ts): `group-watch-socket/api/room.ts`
- [Room operations](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/services/room.service.ts): `group-watch-socket/services/room.service.ts`
- [In-memory rooms](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/services/room.service.ts): `group-watch-socket/services/room.service.ts`

### Live collaboration

- [Socket event handlers](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch-socket/socket/handlers.ts): `group-watch-socket/socket/handlers.ts`

### Video playback

- [YouTube player](https://github.com/querysmith-sys/groupwatch/blob/main/group-watch/app/watch/%5Bid%5D/WatchClient.tsx): `group-watch/app/watch/[id]/WatchClient.tsx`

### Other components

- **Participants**
- **YouTube Iframe API**

## Connections

- Participants → Create or join: create or join
- Create or join → Room API: POST create
- Room API → Room operations: creates room
- Room operations → In-memory rooms: stores room
- Create or join → Room validation: navigates
- Participants → Room validation: opens room
- Room validation → Room API: checks room
- Room API → Room operations: checks existence
- Room validation → Watch interface: mounts if valid
- Watch interface → Host state: reads host state
- Watch interface → HTTP and socket server: opens socket
- HTTP and socket server → Socket event handlers: dispatches events
- Socket event handlers → Room operations: manages membership
- Room operations → In-memory rooms: reads and updates
- Watch interface → Socket event handlers: sends room events
- Socket event handlers → Watch interface: broadcasts room events
- Watch interface → Socket event handlers: sends chat
- Socket event handlers → Watch interface: broadcasts chat
- Watch interface → Socket event handlers: shares video
- Socket event handlers → Watch interface: broadcasts video
- Watch interface → YouTube Iframe API: loads API
- Watch interface → YouTube player: creates player
- YouTube player → Watch interface: reports playback
- Watch interface → Socket event handlers: sends playback action
- Socket event handlers → Room operations: checks host
- Socket event handlers → Watch interface: relays host action
- Participants → Watch interface: chats and watches