How tanim-10/hackfest26-gitgud works
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: App.jsx App shell · SocketContext.jsx Socket context · index.js Server app · VideoPlayer.jsx Video player
Components 18
Browser clients
React/Vite app that owns playback, UI, and socket-driven room actions.
- App boot · Bootstraps the browser application.
client/src/main.jsx - App shell · Top-level client state and room flow coordination.
client/src/App.jsx - Socket context · Shared Socket.IO connection boundary for the React tree.
client/src/context/SocketContext.jsx - Sync engine · Latency measurement, drift correction, countdown timing, and reconciliation.
client/src/hooks/useSync.js - Room manager · Create, join, and claim room interactions.
client/src/components/RoomManager.jsx - Video player · Renders YouTube, URL, and local-file playback modes.
client/src/components/VideoPlayer.jsx - Listener list · Participant roster with promote, demote, kick, and mute actions.
client/src/components/ListenerList.jsx - Chat channel · In-room messaging surface with moderation-aware behavior.
client/src/components/ChatChannel.jsx - Countdown · Visual pre-play coordination overlay for synchronized starts.
client/src/components/SyncCountdown.jsx - Broadcast metrics · Room occupancy and playback status feedback for the broadcaster.
client/src/components/BroadcastAnalytics.jsx - Network dashboard · Displays latency and peer/network quality signals.
client/src/components/NetworkDashboard.jsx - Radar view · 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 · Single backend entry point handling HTTP and realtime messaging.
server/index.js - Room state · In-memory room lifecycle, membership, roles, and disconnect handling.
server/index.js - Sync fan-out · Broadcasts play, pause, seek, countdown, and timing events to clients.
server/index.js - Chat relay · Routes in-room chat and moderation events.
server/index.js - Signal relay · 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 · Peer-to-peer media transport for local-file streaming between broadcaster and listeners.
Connections 26
- 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.