# shynaac/watchparty architecture

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

- Interactive diagram: https://gitdiagram.com/shynaac/watchparty
- Repository: https://github.com/shynaac/watchparty

## Overview

WatchParty is a private, socket-backed virtual theatre. Guests join or create a named room, choose a seat in a Three.js scene, and use room controls for chat, reactions, and screen sharing. The browser scene coordinates the UI and shared room state; the server’s socket handlers own room operations and dispatch updates, with in-memory room state behind them. Screen sharing combines browser capture, WebRTC peers, and socket signaling. The graph follows shown calls and documented capabilities; unsampled modules are represented only where the README or source index supports them.

Main entry points: [`scenes/scene_theatre.js`](https://github.com/shynaac/watchparty/blob/main/scenes/scene_theatre.js) (3D theatre), [`net/socketClient.js`](https://github.com/shynaac/watchparty/blob/main/net/socketClient.js) (Socket client), [`server/sockethandlers.js`](https://github.com/shynaac/watchparty/blob/main/server/sockethandlers.js) (Socket handlers), [`ui/room.js`](https://github.com/shynaac/watchparty/blob/main/ui/room.js) (Room controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Theatre experience"]
  node_app["App bootstrap<br/>[main.js]"]
  node_theatre["3D theatre<br/>[scene_theatre.js]"]
  node_theatre_model["Theatre model"]
  node_popcorn_model["Popcorn model<br/>[popcorn.glb]"]
  node_room_ui["Room controls<br/>[room.js]"]
  node_seat_ui["Seat controls<br/>[seats.js]"]
  node_panels["Panel toggles<br/>[panels.js]"]
end

subgraph group_sharing["Screen sharing"]
  node_sharing_ui["Share capture UI<br/>[room.js]"]
  node_webrtc["WebRTC peers<br/>[screenShare.js]"]
end

subgraph group_backend["Room backend"]
  node_socket_client["Socket client<br/>[socketClient.js]"]
  node_server["Socket server<br/>[index.js]"]
  node_handlers["Socket handlers<br/>[sockethandlers.js]"]
end

subgraph group_state["Room state"]
  node_room_state[("Room state<br/>[rooms.js]")]
end

node_guest(("Guest"))

node_guest -.->|"joins room"| node_room_ui
node_app -->|"loads scene"| node_theatre
node_theatre -->|"initializes"| node_room_ui
node_theatre -->|"initializes"| node_seat_ui
node_theatre -->|"initializes"| node_panels
node_theatre -->|"reads state"| node_socket_client
node_theatre -->|"loads model"| node_popcorn_model
node_theatre -.->|"uses scene asset"| node_theatre_model
node_room_ui -->|"room events"| node_socket_client
node_sharing_ui -->|"starts sharing"| node_webrtc
node_webrtc -->|"signals peers"| node_socket_client
node_socket_client -->|"connects"| node_server
node_server -->|"registers handlers"| node_handlers
node_handlers -->|"updates rooms"| node_room_state
node_handlers -->|"dispatches room events"| node_socket_client
node_handlers -->|"relays signaling"| node_webrtc

click node_app "https://github.com/shynaac/watchparty/blob/main/main.js"
click node_theatre "https://github.com/shynaac/watchparty/blob/main/scenes/scene_theatre.js"
click node_theatre_model "https://github.com/shynaac/watchparty/blob/main/assets/Movie_Theater_Scene_Refactored_6.glb"
click node_popcorn_model "https://github.com/shynaac/watchparty/blob/main/assets/popcorn.glb"
click node_room_ui "https://github.com/shynaac/watchparty/blob/main/ui/room.js"
click node_seat_ui "https://github.com/shynaac/watchparty/blob/main/ui/seats.js"
click node_panels "https://github.com/shynaac/watchparty/blob/main/ui/panels.js"
click node_socket_client "https://github.com/shynaac/watchparty/blob/main/net/socketClient.js"
click node_sharing_ui "https://github.com/shynaac/watchparty/blob/main/ui/room.js"
click node_webrtc "https://github.com/shynaac/watchparty/blob/main/net/screenShare.js"
click node_server "https://github.com/shynaac/watchparty/blob/main/server/index.js"
click node_handlers "https://github.com/shynaac/watchparty/blob/main/server/sockethandlers.js"
click node_room_state "https://github.com/shynaac/watchparty/blob/main/server/rooms.js"

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_app,node_theatre,node_theatre_model,node_popcorn_model,node_room_ui,node_seat_ui,node_panels toneBlue
class node_sharing_ui,node_webrtc toneAmber
class node_socket_client,node_server,node_handlers toneMint
class node_room_state toneRose
class node_guest toneIndigo
```

## Components

### Theatre experience

- [App bootstrap](https://github.com/shynaac/watchparty/blob/main/main.js): `main.js`
- [3D theatre](https://github.com/shynaac/watchparty/blob/main/scenes/scene_theatre.js): `scenes/scene_theatre.js`
- [Theatre model](https://github.com/shynaac/watchparty/blob/main/assets/Movie_Theater_Scene_Refactored_6.glb): `assets/Movie_Theater_Scene_Refactored_6.glb`
- [Popcorn model](https://github.com/shynaac/watchparty/blob/main/assets/popcorn.glb): `assets/popcorn.glb`
- [Room controls](https://github.com/shynaac/watchparty/blob/main/ui/room.js): `ui/room.js`
- [Seat controls](https://github.com/shynaac/watchparty/blob/main/ui/seats.js): `ui/seats.js`
- [Panel toggles](https://github.com/shynaac/watchparty/blob/main/ui/panels.js): `ui/panels.js`

### Screen sharing

- [Share capture UI](https://github.com/shynaac/watchparty/blob/main/ui/room.js): `ui/room.js`
- [WebRTC peers](https://github.com/shynaac/watchparty/blob/main/net/screenShare.js): `net/screenShare.js`

### Room backend

- [Socket client](https://github.com/shynaac/watchparty/blob/main/net/socketClient.js): `net/socketClient.js`
- [Socket server](https://github.com/shynaac/watchparty/blob/main/server/index.js): `server/index.js`
- [Socket handlers](https://github.com/shynaac/watchparty/blob/main/server/sockethandlers.js): `server/sockethandlers.js`

### Room state

- [Room state](https://github.com/shynaac/watchparty/blob/main/server/rooms.js): `server/rooms.js`

### Other components

- **Guest**

## Connections

- Guest → Room controls: joins room (evidence: `README.md`)
- App bootstrap → 3D theatre: loads scene (evidence: `main.js`)
- 3D theatre → Room controls: initializes (evidence: `scenes/scene_theatre.js`)
- 3D theatre → Seat controls: initializes (evidence: `scenes/scene_theatre.js`)
- 3D theatre → Panel toggles: initializes (evidence: `scenes/scene_theatre.js`)
- 3D theatre → Socket client: reads state (evidence: `scenes/scene_theatre.js`)
- 3D theatre → Popcorn model: loads model (evidence: `scenes/scene_theatre.js`)
- 3D theatre → Theatre model: uses scene asset (evidence: `README.md`)
- Room controls → Socket client: room events (evidence: `ui/room.js`)
- Share capture UI → WebRTC peers: starts sharing (evidence: `ui/room.js`)
- WebRTC peers → Socket client: signals peers (evidence: `net/screenShare.js`)
- Socket client → Socket server: connects (evidence: `net/socketClient.js`)
- Socket server → Socket handlers: registers handlers (evidence: `server/index.js`)
- Socket handlers → Room state: updates rooms (evidence: `server/sockethandlers.js`)
- Socket handlers → Socket client: dispatches room events (evidence: `server/sockethandlers.js`)
- Socket handlers → WebRTC peers: relays signaling (evidence: `server/sockethandlers.js`)
