# uday-choudhary/synccube architecture

> Architecture diagram of the GitHub repository uday-choudhary/synccube, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uday-choudhary/synccube
- Repository: https://github.com/uday-choudhary/synccube

## Overview

##### Project Type and Purpose
- SyncCube is a full-stack, real-time web application for synchronized video watching.
- The frontend is a React/Vite SPA styled with Tailwind CSS and shadcn/ui, and the backend is a Node.js server using Socket.io for real-time events.
- Key use cases: create/join a room, input YouTube URLs, play/pause/seek in sync across clients.

##### File Structure
- Top-level:
- `server/` – Node.js Socket.io server (`index.js`, `package.json`).
- `src/` – React app (components, context, pages, hooks, lib).
- Configs: Vite (`vite.config.ts`), Tailwind (`tailwind.config.ts`), TypeScript (`tsconfig*.json`).
- `public/` – static assets (robots.txt).
- Patterns:
- SPA structure under `src/`, MVC-light (pages vs components).
- Context API for socket management (`src/context/SocketContext.jsx`).
- Utility libs in `src/lib`.
- shadcn/ui folder for reusable UI primitives.

##### Extract Architecture Insights from README
- Lists Frontend/Backend separation and real-time flow via Socket.io.
- Outlines room lifecycle: creation, join, event broadcasting, state tracking.
- Mentions ngrok for exposing local server.

##### Main Components
a. Frontend (Browser)
- React App (entry `main.jsx`/`main.tsx`, root `App.jsx`/`tsx`).
- UI layer: shadcn/ui components + custom components (HeaderNav, VideoInput, YouTubePlayer, RoomInfo, JoinRoomForm).
- Context: `SocketContext` manages `io()` connection.
- Pages: `Index`, `RoomPage`, `NotFound`.
- Hooks/utilities: `use-mobile`, `use-toast`, `utils.js/ts`.
b. Backend (Node.js Server)
- Express (implicit) + Socket.io server in `server/index.js`.
- In-memory store of room states (video URL, play/pause, timestamp).
- Event handlers: `video_play`, `video_pause`, `video_seek`, `join_room`, etc.
c. External Services
- YouTube iFrame API (embedded player).
- ngrok (for tunnel during development).
d. Infrastructure (Dev/Prod)
- Vite dev server on `localhost:8080`.
- Socket.io server on `localhost:3001`.
- Static assets served from `public/`.

##### Relationships and Data Flows
- On room creation: Frontend emits `create_room` → Server generates ID + stores video URL → emits back `room_created`.
- On join: Frontend emits `join_room` → Server adds socket to room, sends current state → Frontend sets up player.
- Playback events: Frontend emits `video_play`/`video_pause`/`video_seek` → Server broadcasts to all sockets in room → Frontends update player state.
- New joiners request current state from the server.
- UI feedback: connection status, user count via `room_users` events.

##### Architectural Patterns & Principles
- Separation of Concerns: UI components vs context vs utils vs pages
- Real-time Pub/Sub via Socket.io rooms
- Stateless frontend, stateful server for sync coordination
- Responsive design (use of `use-mobile` hook)

1. Sketch three tiers: Client Browser, Backend Server, External Services.
8. Validate against README flow: room creation, join, event broadcast, new-user sync.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser
    subgraph "Client Browser" 
        direction TB
        Main["Main.jsx/tsx"]:::frontend
        App["App.jsx/tsx"]:::frontend
        subgraph "UI Components"
            direction TB
            HeaderNav["HeaderNav"]:::frontend
            JoinRoomForm["JoinRoomForm"]:::frontend
            RoomInfo["RoomInfo"]:::frontend
            VideoInput["VideoInput"]:::frontend
            YouTubePlayer["YouTubePlayer"]:::frontend
        end
        subgraph "Pages"
            direction TB
            IndexPage["IndexPage"]:::frontend
            RoomPage["RoomPage"]:::frontend
            NotFoundPage["NotFoundPage"]:::frontend
        end
        subgraph "Context & Utils"
            direction TB
            SocketContext["SocketContext"]:::frontend
            useMobile["useMobile"]:::frontend
            useToast["useToast"]:::frontend
            Utils["Utils"]:::frontend
        end
    end

    %% Backend Server
    subgraph "Backend Server"
        direction TB
        SocketServer["Socket.io Server<br/>(port 3001)"]:::backend
        RoomStore["Room State Store"]:::store
        EventHandlers["Event Handlers<br/>(video_play, video_pause, video_seek,<br/>join_room, create_room)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        YouTubeAPI["YouTube iFrame API"]:::external
        ngrok["ngrok"]:::external
    end

    %% Connections
    App -->|"wraps"| HeaderNav
    App -->|"wraps"| JoinRoomForm
    App -->|"wraps"| RoomInfo
    App -->|"wraps"| VideoInput
    App -->|"wraps"| YouTubePlayer
    App -->|"routes to"| IndexPage
    App -->|"routes to"| RoomPage
    App -->|"routes to"| NotFoundPage
    Main -->|"renders"| App

    %% Socket Flow
    SocketContext -->|"WebSocket connection"| SocketServer
    SocketServer -->|"stores state"| RoomStore
    SocketServer -->|"handles events"| EventHandlers
    EventHandlers -->|"updates"| RoomStore

    %% Event Emissions
    VideoInput -->|"create_room / join_room"| SocketContext
    RoomPage -->|"emit video_play / video_pause / video_seek"| SocketContext
    SocketServer -.->|"broadcast events (video_*)"| SocketContext:::dashed
    SocketContext -->|"update UI"| VideoInput
    SocketContext -->|"update UI"| YouTubePlayer
    YouTubePlayer -->|"load video"| YouTubeAPI
    ngrok ---|"tunnel to localhost:3001"| SocketServer

    %% Legend
    subgraph Legend
        direction TB
        F["Frontend Components"]:::frontend
        B["Backend Components"]:::backend
        E["External Services"]:::external
        S["State Store"]:::store
        D["Broadcast (Socket.io)"]:::dashed
    end

    %% Click Events
    click Main "https://github.com/uday-choudhary/synccube/blob/main/src/main.jsx"
    click App "https://github.com/uday-choudhary/synccube/blob/main/src/App.jsx"
    click SocketContext "https://github.com/uday-choudhary/synccube/blob/main/src/context/SocketContext.jsx"
    click HeaderNav "https://github.com/uday-choudhary/synccube/blob/main/src/components/HeaderNav.jsx"
    click JoinRoomForm "https://github.com/uday-choudhary/synccube/blob/main/src/components/JoinRoomForm.jsx"
    click RoomInfo "https://github.com/uday-choudhary/synccube/blob/main/src/components/RoomInfo.jsx"
    click VideoInput "https://github.com/uday-choudhary/synccube/blob/main/src/components/VideoInput.jsx"
    click YouTubePlayer "https://github.com/uday-choudhary/synccube/blob/main/src/components/YouTubePlayer.jsx"
    click IndexPage "https://github.com/uday-choudhary/synccube/blob/main/src/pages/Index.jsx"
    click RoomPage "https://github.com/uday-choudhary/synccube/blob/main/src/pages/RoomPage.jsx"
    click NotFoundPage "https://github.com/uday-choudhary/synccube/blob/main/src/pages/NotFound.jsx"
    click useMobile "https://github.com/uday-choudhary/synccube/blob/main/src/hooks/use-mobile.tsx"
    click useToast "https://github.com/uday-choudhary/synccube/blob/main/src/hooks/use-toast.ts"
    click Utils "https://github.com/uday-choudhary/synccube/blob/main/src/lib/utils.js"
    click SocketServer "https://github.com/uday-choudhary/synccube/blob/main/server/index.js"
    click YouTubeAPI "https://github.com/uday-choudhary/synccube/tree/main/external/YouTubeAPI"
    click ngrok "https://github.com/uday-choudhary/synccube/tree/main/external/ngrok"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#22863A,color:#22863A;
    classDef external fill:#FFF5B1,stroke:#DBAB09,color:#DBAB09;
    classDef store fill:#E0F2FF,stroke:#005ADC,color:#005ADC;
    classDef dashed stroke-dasharray: 4 2;
```
