# howardchung/watchparty architecture

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

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

## Overview

##### And Isolate the Main Components
- Frontend (User Interface)
- Located mainly in the “src” and “public” directories.
- Built with React and TypeScript.
- Comprises various UI components for video playback, chat (text and video), controls, settings, and virtual browser experience.
- Backend (Server Application)
- Found in the “server” directory.
- Written in TypeScript/Node.js; handles room management, playback synchronization, chat functionality, and integration with external services.
- Contains utility modules for interacting with Redis (for real-time messaging/cache), PostgreSQL (for room persistence/state), and external APIs.
- Database & Data Storage
- PostgreSQL is configured through the “sql” folder.
- Room persistence, user data, and other stateful information are managed here.
- Caching / Real-Time Data Channels
- Redis integration (look in “server/utils/redis.ts”).
- Manages real-time state propagation (such as synchronized play, pause, and seek actions).
- External Services and APIs
- Firebase for user authentication (plus admin configurations for server verification).
- YouTube API for video search functionality.
- Additional services like Magnet links via WebTorrent and support for HLS streams.
- Virtual Browser / Docker-Based Service
- The “server/vm” subdirectory combined with “dev/browseparty” scripts indicates support for launching virtual browser instances.
- The system can manage instances via Docker (and on various cloud providers such as DigitalOcean, Hetzner, Scaleway).
- Includes a separate “vmWorker” that handles instance management.

##### Component Relationships and Interactions
- The WEB CLIENT (frontend) communicates with the BACKEND via HTTP/WebSocket connections.
- The BACKEND acts as the central coordinator:
- It receives events from connected clients (e.g., play, pause, seek events) and synchronizes these across rooms.
- It communicates with PostgreSQL to manage persistent room data.
- It interacts with Redis for caching and possibly session pub/sub.
- It calls external APIs such as YouTube and validates user sessions with Firebase.
- It triggers the Virtual Browser Service either on Docker or via cloud-based APIs.
- The Virtual Browser component (managed in the “server/vm” folder) or associated workers accept commands from the backend to launch and control containerized browser sessions.
- Administration and configuration scripts (found in the “dev” folder) support deployment, local testing, and maintenance routines.

##### Architectural Patterns and Key Design Principles
- Separation of Concerns: The codebase clearly divides responsibilities between frontend and backend, with specialized directories for UI components, server APIs, databases, and external integrations.
- Micro-Services/Modular Services: The virtual browser functionality is almost like its own service (with dedicated vm folders and worker scripts). Similarly, the handling of user authentication and video search uses third-party services.
- Real-Time Synchronization: Use of Redis and server coordination ensures that state updates (video synchronization) flow effectively in real time.
- Containerization & Virtualization: Docker files and VM-related scripts indicate the application leverages container orchestration as part of its scalability and modularity.

##### Technologies and Frameworks
- Frontend: React, TypeScript, and Vite.
- Backend: Node.js with TypeScript; likely using express-style routings and integrations for real-time data (WebSockets).
- Data Storage: PostgreSQL for persistent data (with SQL migrations and schema definitions) and Redis for caching/real-time pub/sub.
- Containerization: Docker integrations for virtual browser sessions.
- External APIs: YouTube API for video search and Firebase for authentication and user management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend"
        F1["React Client (src)"]:::frontend
        F2["Static Assets (public)"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend"
        B1["Node.js Server (server/server.ts)"]:::backend
    end

    %% Database & Cache Subgraph
    subgraph "Database & Cache"
        D1["PostgreSQL Database"]:::database
        D2["Redis Cache (server/utils/redis.ts)"]:::cache
    end

    %% External Services Subgraph
    subgraph "External Services"
        E1["Firebase Auth (server/utils/firebase.ts)"]:::external
        E2["YouTube API (server/utils/youtube.ts)"]:::external
    end

    %% Virtual Browser Service Subgraph
    subgraph "Virtual Browser Service"
        V1["Docker-based Virtual Browser (server/vm)"]:::virtual
        V2["VM Worker (server/vmWorker.ts)"]:::virtual
        V3["Dev Scripts (dev/browseparty)"]:::virtual
    end

    %% Connections
    F1 -->|"HTTP/WebSocket"| B1
    F2 -->|"HTTP/WebSocket"| B1

    B1 -->|"storesRoomState"| D1
    B1 -->|"cachesSyncEvents"| D2
    B1 -->|"usesAuth"| E1
    B1 -->|"fetchesVideoInfo"| E2
    B1 -->|"launchesVM"| V1
    B1 -->|"managesWorker"| V2
    B1 -->|"invokesDevScripts"| V3

    %% Click Events
    click F1 "https://github.com/howardchung/watchparty/tree/master/src"
    click F2 "https://github.com/howardchung/watchparty/tree/master/public"
    click B1 "https://github.com/howardchung/watchparty/blob/master/server/server.ts"
    click D1 "https://github.com/howardchung/watchparty/tree/master/sql"
    click D2 "https://github.com/howardchung/watchparty/blob/master/server/utils/redis.ts"
    click E1 "https://github.com/howardchung/watchparty/blob/master/server/utils/firebase.ts"
    click E2 "https://github.com/howardchung/watchparty/blob/master/server/utils/youtube.ts"
    click V1 "https://github.com/howardchung/watchparty/tree/master/server/vm"
    click V2 "https://github.com/howardchung/watchparty/blob/master/server/vmWorker.ts"
    click V3 "https://github.com/howardchung/watchparty/tree/master/dev/browseparty"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C2F0C2,stroke:#333,stroke-width:2px;
    classDef database fill:#F7C8C8,stroke:#333,stroke-width:2px;
    classDef cache fill:#F2C2F0,stroke:#333,stroke-width:2px;
    classDef external fill:#FFF7AA,stroke:#333,stroke-width:2px;
    classDef virtual fill:#E8E8E8,stroke:#333,stroke-width:2px;
```
