# tanim-10/hackfest26-gitgud architecture

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

- Interactive diagram: https://gitdiagram.com/tanim-10/hackfest26-gitgud
- Repository: https://github.com/tanim-10/hackfest26-gitgud

## Overview

1. **Repository shape**
   - This is a two-process realtime app: a **Node.js server** in `server/` and a **React/Vite client** in `client/`.
   - The architecture is intentionally thin on persistence: room state, roles, sync timing, and signaling live in the server process; the browser handles playback and UI.

2. **Server boundary**
   - `server/index.js` is the single backend entry point.
   - It runs **Express** for HTTP and **Socket.IO** for realtime messaging.
   - Its main responsibilities are room lifecycle, client membership, role changes, sync event fan-out, chat routing, latency pings, and WebRTC signaling relay.
   - There is no database or external service layer in the tree; room state appears to be in-memory and ephemeral.

3. **Client shell**
   - `client/src/main.jsx` boots the React app, and `client/src/App.jsx` is the top-level orchestration component.
   - `App.jsx` likely coordinates the main room state, selected media source, broadcaster/listener role, and the socket event subscriptions that drive the UI.
   - Styling is global and app-specific via `App.css` and `index.css`, supporting the command-center visual theme but not changing the architecture.

4. **Socket connection layer**
   - `client/src/context/SocketContext.jsx` is the shared connection boundary between React and Socket.IO.
   - It centralizes the client’s server connection so child components can consume the socket without each creating their own connection.
   - This is the main bridge for all server-driven state updates and user actions.

5. **Sync engine**
   - `client/src/hooks/useSync.js` is the client-side playback coordination layer.
   - It handles latency measurement, drift correction, countdown timing, and periodic reconciliation against broadcaster time.
   - Architecturally, this is the mechanism that keeps multiple independent browser media elements aligned after the server broadcasts control events.

6. **Media playback subsystem**
   - `client/src/components/VideoPlayer.jsx` is the core media renderer.
   - It supports multiple input modes: YouTube embeds, direct video/audio URLs, and local files.
   - For standard URLs and YouTube, each client loads the media locally and the app syncs play/pause/seek over the network.
   - For local files, the broadcaster captures a media stream and distributes it via WebRTC instead of routing binary media through the server.

7. **Room management and participant control**
   - `client/src/components/RoomManager.jsx` appears to own create/join/claim room flows.
   - `ListenerList.jsx` represents the room roster and exposes moderation actions such as promote, demote, kick, and mute.
   - These controls map directly to server-side role and membership transitions, so the client is a controller of server state rather than the source of truth.

8. **Chat and social interaction**
   - `client/src/components/ChatChannel.jsx` is a realtime in-room messaging surface.
   - Chat moderation is role-aware: the broadcaster can mute or unmute individual listeners, and the server enforces that state through socket events.
   - Chat is separate from playback synchronization, but both share the same room and client identity model.

9. **Room status and telemetry UI**
   - `BroadcastAnalytics.jsx`, `NetworkDashboard.jsx`, and `RadarVisualization.jsx` are observability-oriented panels.
   - They visualize room occupancy, playback state, network quality, and peer presence rather than controlling media directly.
   - These components consume room/socket state and turn it into operational feedback for the broadcaster.

10. **Countdown and coordinated play**
    - `SyncCountdown.jsx` is the visual layer for pre-play synchronization.
    - The flow is broadcaster action → server fan-out → countdown overlay on clients → scheduled playback start.
    - This is a key architectural boundary: the server coordinates the moment of truth, while the client executes playback locally at the agreed time.

11. **WebRTC signaling path**
    - Local file streaming uses a separate peer-to-peer data plane.
    - The server relays only signaling messages such as offer/answer/ICE and readiness notifications; it does not carry media payloads.
    - The broadcaster is the media source, listeners are WebRTC peers, and the server is the signaling broker.

12. **Room lifecycle and failure handling**
    - The server maintains the room as a live session with role ownership and disconnect handling.
    - If the broadcaster disconnects, listeners enter a grace-period state with a forced-close countdown.
    - If the broadcaster returns in time, the room continues; otherwise the server forces the room closed and returns clients to the lobby.
    - If all members leave, the room is deleted immediately.

13. **Runtime and tooling**
    - Server: Node.js with Express, Socket.IO, CORS, and UUID-based room code generation.
    - Client: React 19 with Vite, Socket.IO client, and `react-youtube`.
    - The architecture assumes modern browsers, with Chrome/Firefox/Chromium-based browsers being important for local file streaming because of `captureStream()` and WebRTC support.

14. **How to draw the architecture**
    - Draw three main areas: **browser clients**, **Socket.IO/Express server**, and a **peer-to-peer WebRTC mesh for local files**.
    - Put the server in the middle for room state and synchronization.
    - Show standard media sources flowing as “load locally on each client + sync events from server,” while local files flow as “broadcaster captureStream → WebRTC to listeners, server only signals.”

Main entry points: [`client/src/App.jsx`](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/App.jsx) (App shell), [`client/src/context/SocketContext.jsx`](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/context/SocketContext.jsx) (Socket context), [`server/index.js`](https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js) (Server app), [`client/src/components/VideoPlayer.jsx`](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/VideoPlayer.jsx) (Video player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser clients"]
  node_client_entry["App boot<br/>React entry<br/>[main.jsx]"]
  node_client_shell["App shell<br/>React orchestrator<br/>[App.jsx]"]
  node_socket_ctx(("Socket context<br/>Socket bridge<br/>[SocketContext.jsx]"))
  node_sync_hook(("Sync engine<br/>Playback sync<br/>[useSync.js]"))
  node_room_mgr["Room manager<br/>Room flow UI<br/>[RoomManager.jsx]"]
  node_video_player["Video player<br/>Media renderer<br/>[VideoPlayer.jsx]"]
  node_listener_list["Listener list<br/>Roster controls<br/>[ListenerList.jsx]"]
  node_chat_channel["Chat channel<br/>Realtime chat UI<br/>[ChatChannel.jsx]"]
  node_sync_countdown(("Countdown<br/>Play overlay<br/>[SyncCountdown.jsx]"))
  node_broadcast_analytics["Broadcast metrics<br/>Telemetry panel"]
  node_network_dashboard["Network dashboard<br/>Telemetry panel"]
  node_radar_viz(("Radar view<br/>Presence viz"))
end

subgraph group_server["Socket.IO server"]
  node_server_entry[("Server app<br/>Express + Socket.IO<br/>[index.js]")]
  node_room_state["Room state<br/>Ephemeral state<br/>[index.js]"]
  node_sync_broadcast["Sync fan-out<br/>Realtime events<br/>[index.js]"]
  node_chat_relay["Chat relay<br/>Message routing<br/>[index.js]"]
  node_signal_relay{{"Signal relay<br/>WebRTC signaling<br/>[index.js]"}}
end

subgraph group_webrtc["P2P media"]
  node_p2p_stream{{"Media mesh<br/>WebRTC path"}}
end

node_client_entry -->|"renders"| node_client_shell
node_client_shell -->|"consumes"| node_socket_ctx
node_client_shell -->|"room actions"| node_room_mgr
node_client_shell -->|"media UI"| node_video_player
node_client_shell -->|"chat UI"| node_chat_channel
node_client_shell -->|"roster UI"| node_listener_list
node_client_shell -->|"observes"| node_broadcast_analytics
node_client_shell -->|"observes"| node_network_dashboard
node_client_shell -->|"observes"| node_radar_viz
node_client_shell -->|"timed start"| node_sync_countdown
node_video_player -->|"syncs"| node_sync_hook
node_sync_hook -->|"pings"| node_socket_ctx
node_room_mgr -->|"room events"| node_socket_ctx
node_listener_list -->|"moderates"| node_socket_ctx
node_chat_channel -->|"messages"| node_socket_ctx
node_server_entry -->|"owns"| node_room_state
node_server_entry -->|"fans out"| node_sync_broadcast
node_server_entry -->|"routes"| node_chat_relay
node_server_entry -->|"signals"| node_signal_relay
node_room_state -->|"drives"| node_sync_broadcast
node_room_state -->|"authorizes"| node_chat_relay
node_signal_relay -.->|"negotiates"| node_p2p_stream
node_video_player -->|"captures local file"| node_p2p_stream
node_p2p_stream -->|"plays peer media"| node_video_player
node_sync_countdown -->|"start timing"| node_sync_broadcast
node_network_dashboard -->|"telemetry"| node_sync_hook

click node_client_entry "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/main.jsx"
click node_client_shell "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/App.jsx"
click node_socket_ctx "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/context/SocketContext.jsx"
click node_sync_hook "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/hooks/useSync.js"
click node_room_mgr "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/RoomManager.jsx"
click node_video_player "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/VideoPlayer.jsx"
click node_listener_list "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/ListenerList.jsx"
click node_chat_channel "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/ChatChannel.jsx"
click node_sync_countdown "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/SyncCountdown.jsx"
click node_broadcast_analytics "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/BroadcastAnalytics.jsx"
click node_network_dashboard "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/NetworkDashboard.jsx"
click node_radar_viz "https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/RadarVisualization.jsx"
click node_server_entry "https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js"
click node_room_state "https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js"
click node_sync_broadcast "https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js"
click node_chat_relay "https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js"
click node_signal_relay "https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.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_client_entry,node_client_shell,node_socket_ctx,node_sync_hook,node_room_mgr,node_video_player,node_listener_list,node_chat_channel,node_sync_countdown,node_broadcast_analytics,node_network_dashboard,node_radar_viz toneBlue
class node_server_entry,node_room_state,node_sync_broadcast,node_chat_relay,node_signal_relay toneAmber
class node_p2p_stream toneMint
```

## Components

### Browser clients

React/Vite app that owns playback, UI, and socket-driven room actions.

- [App boot](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/main.jsx): React entry · Bootstraps the browser application. · `client/src/main.jsx`
- [App shell](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/App.jsx): React orchestrator · Top-level client state and room flow coordination. · `client/src/App.jsx`
- [Socket context](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/context/SocketContext.jsx): Socket bridge · Shared Socket.IO connection boundary for the React tree. · `client/src/context/SocketContext.jsx`
- [Sync engine](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/hooks/useSync.js): Playback sync · Latency measurement, drift correction, countdown timing, and reconciliation. · `client/src/hooks/useSync.js`
- [Room manager](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/RoomManager.jsx): Room flow UI · Create, join, and claim room interactions. · `client/src/components/RoomManager.jsx`
- [Video player](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/VideoPlayer.jsx): Media renderer · Renders YouTube, URL, and local-file playback modes. · `client/src/components/VideoPlayer.jsx`
- [Listener list](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/ListenerList.jsx): Roster controls · Participant roster with promote, demote, kick, and mute actions. · `client/src/components/ListenerList.jsx`
- [Chat channel](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/ChatChannel.jsx): Realtime chat UI · In-room messaging surface with moderation-aware behavior. · `client/src/components/ChatChannel.jsx`
- [Countdown](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/SyncCountdown.jsx): Play overlay · Visual pre-play coordination overlay for synchronized starts. · `client/src/components/SyncCountdown.jsx`
- [Broadcast metrics](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/BroadcastAnalytics.jsx): Telemetry panel · Room occupancy and playback status feedback for the broadcaster. · `client/src/components/BroadcastAnalytics.jsx`
- [Network dashboard](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/NetworkDashboard.jsx): Telemetry panel · Displays latency and peer/network quality signals. · `client/src/components/NetworkDashboard.jsx`
- [Radar view](https://github.com/tanim-10/hackfest26-gitgud/blob/main/client/src/components/RadarVisualization.jsx): Presence viz · Visualizes peer presence and room activity. · `client/src/components/RadarVisualization.jsx`

### Socket.IO server

Express and realtime backend that owns room state, signaling, and fan-out.

- [Server app](https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js): Express + Socket.IO · Single backend entry point handling HTTP and realtime messaging. · `server/index.js`
- [Room state](https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js): Ephemeral state · In-memory room lifecycle, membership, roles, and disconnect handling. · `server/index.js`
- [Sync fan-out](https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js): Realtime events · Broadcasts play, pause, seek, countdown, and timing events to clients. · `server/index.js`
- [Chat relay](https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js): Message routing · Routes in-room chat and moderation events. · `server/index.js`
- [Signal relay](https://github.com/tanim-10/hackfest26-gitgud/blob/main/server/index.js): WebRTC signaling · Forwards offer, answer, ICE, and readiness messages for local-file peers. · `server/index.js`

### P2P media

Peer-to-peer path used for local-file media streaming.

- **Media mesh**: WebRTC path · Peer-to-peer media transport for local-file streaming between broadcaster and listeners.

## Connections

- App boot → App shell: renders · React entry mounts the top-level app.
- App shell → Socket context: consumes · App uses the shared socket connection boundary.
- App shell → Room manager: room actions · Room flow is initiated from the shell.
- App shell → Video player: media UI · Top-level state drives media mode and playback.
- App shell → Chat channel: chat UI · Chat is part of the room experience.
- App shell → Listener list: roster UI · Participant controls are surfaced in the shell.
- App shell → Broadcast metrics: observes · Broadcaster telemetry is rendered from shared room state.
- App shell → Network dashboard: observes · Network feedback is rendered from shared room state.
- App shell → Radar view: observes · Presence visualization is rendered from shared room state.
- App shell → Countdown: timed start · Countdown overlay is controlled by sync state.
- Video player → Sync engine: syncs · Playback uses latency, drift, and timing coordination.
- Sync engine → Socket context: pings · Sync logic exchanges timing events over the socket.
- Room manager → Socket context: room events · Create/join/claim actions go through the socket.
- Listener list → Socket context: moderates · Role and membership actions are sent to the server.
- Chat channel → Socket context: messages · Chat traffic uses the shared realtime connection.
- Server app → Room state: owns · Backend entry manages live room state.
- Server app → Sync fan-out: fans out · Server broadcasts synchronized playback events.
- Server app → Chat relay: routes · Server routes chat and moderation messages.
- Server app → Signal relay: signals · Server relays WebRTC negotiation messages.
- Room state → Sync fan-out: drives · Room state changes trigger sync broadcasts.
- Room state → Chat relay: authorizes · Membership and role state govern chat moderation.
- Signal relay → Media mesh: negotiates · Server helps peers establish the media path.
- Video player → Media mesh: captures local file · Broadcaster captureStream feeds the peer-to-peer media mesh.
- Media mesh → Video player: plays peer media · Listeners render the streamed media locally.
- Countdown → Sync fan-out: start timing · Countdown begins from server-coordinated play events.
- Network dashboard → Sync engine: telemetry · Network display reflects sync measurements.
