# zastrich/webrtcstream architecture

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

- Interactive diagram: https://gitdiagram.com/zastrich/webrtcstream
- Repository: https://github.com/zastrich/webrtcstream

## Overview

##### Project type and purpose
- This is a lightweight full-stack, real-time media application that implements a WebRTC “mesh” broadcast: one broadcaster streams video/audio to multiple watchers.
- The Node.js server (app.js) serves static pages, handles HTTPS/WebSocket signaling, and orchestrates WebRTC peer-to-peer connections.

##### File structure
- Top-level files:
- app.js – main server (Express + HTTPS + WebSocket signaling)
- cert.pem, key.pem – TLS certificate + key for HTTPS/WSS
- Dockerfile/.dockerignore – containerization support
- package.json/lock – Node dependencies
- public/ directory: static client assets
- broadcast.html/.js – broadcaster UI and signaling logic
- watch.html (index.html)/watch.js – watcher UI and signaling logic
- styles.css – shared styling
- Renovate, ESLint, Git files – maintenance/config, not part of runtime flow.

##### Extract insights from the README
- Project exposes port 4000 for HTTPS + WSS
- Two run modes: direct Node or Docker container
- No database, no external STUN/TURN configured (can note default Google STUN).

a. Main components
- HTTPS/WebSocket Signaling Server (Node.js in a Docker container)
- Broadcaster Client (browser)
- Watcher Clients (browsers) – one or many
- (Optional) STUN server for ICE (default or custom)
b. Relationships & data flow
1. Clients load static HTML/JS/CSS over HTTPS from the server.
2. Broadcaster & watchers establish a WebSocket (WSS) connection to the server for signaling.
3. Broadcaster emits “offer” via WSS → server → all watchers.
4. Watchers send “answer” via WSS → server → broadcaster.
5. Both sides exchange ICE candidates via WSS.
6. Once handshake completes, a direct P2P WebRTC media stream (video/audio) flows from broadcaster → each watcher.
c. Architectural patterns & principles
– Client-Server separation: server only handles static asset delivery and signaling, media never flows through it.
– Peer mesh: each watcher opens a separate P2P connection with the broadcaster.
– Secure communications: HTTPS + WSS over TLS.
d. Key technologies/frameworks
– Node.js + Express (HTTPS server)
– ws or socket.io (WebSocket signaling)
– WebRTC APIs in browser (RTCPeerConnection, getUserMedia)
– Docker (container image and deployment)

##### Critical details to capture
- TLS termination on the server (cert.pem/key.pem).
- WebSocket namespace or events (offer/answer/candidate).
- P2P mesh topology (one-to-many).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Backend
    subgraph "Backend" 
        direction TB
        Server["Dockerized Node.js Server"]:::backend
        subgraph "Server Files"
            direction TB
            AppJS["app.js"]:::backend
            CertPem["cert.pem"]:::backend
            KeyPem["key.pem"]:::backend
            DockerfileNode["Dockerfile"]:::backend
            Dockerignore[".dockerignore"]:::backend
            PackageJSON["package.json"]:::backend
            PackageLock["package-lock.json"]:::backend
            README["README.md"]:::backend
        end
    end

    %% Static Assets
    subgraph "Static Assets" 
        direction TB
        BroadcastHTML["broadcast.html"]:::frontend
        BroadcastJS["broadcast.js"]:::frontend
        IndexHTML["index.html"]:::frontend
        WatchJS["watch.js"]:::frontend
        StylesCSS["styles.css"]:::frontend
    end

    %% Frontend Clients
    subgraph "Frontend Clients"
        direction TB
        Broadcaster["Broadcaster Browser"]:::frontend
        Watchers["Watcher Browsers"]:::frontend
    end

    %% STUN Server
    STUN["STUN Server"]:::network

    %% Connections: Static asset delivery
    Broadcaster -->|"HTTPS GET static assets"|Server
    Watchers -->|"HTTPS GET static assets"|Server

    %% Connections: Signaling
    Broadcaster -.->|"WSS Signaling (offer/answer/candidate)"|Server
    Watchers -.->|"WSS Signaling (answer/candidate)"|Server

    %% ICE discovery via STUN
    Broadcaster -.->|"ICE Discovery"|STUN
    Watchers -.->|"ICE Discovery"|STUN

    %% Media flow
    Broadcaster -->|"WebRTC Media Stream"|Watchers

    %% Click Events
    click AppJS "https://github.com/zastrich/webrtcstream/blob/master/app.js"
    click CertPem "https://github.com/zastrich/webrtcstream/blob/master/cert.pem"
    click KeyPem "https://github.com/zastrich/webrtcstream/blob/master/key.pem"
    click DockerfileNode "https://github.com/zastrich/webrtcstream/tree/master/Dockerfile"
    click Dockerignore "https://github.com/zastrich/webrtcstream/blob/master/.dockerignore"
    click PackageJSON "https://github.com/zastrich/webrtcstream/blob/master/package.json"
    click PackageLock "https://github.com/zastrich/webrtcstream/blob/master/package-lock.json"
    click README "https://github.com/zastrich/webrtcstream/blob/master/README.md"
    click BroadcastHTML "https://github.com/zastrich/webrtcstream/blob/master/public/broadcast.html"
    click BroadcastJS "https://github.com/zastrich/webrtcstream/blob/master/public/broadcast.js"
    click IndexHTML "https://github.com/zastrich/webrtcstream/blob/master/public/index.html"
    click WatchJS "https://github.com/zastrich/webrtcstream/blob/master/public/watch.js"
    click StylesCSS "https://github.com/zastrich/webrtcstream/blob/master/public/styles.css"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef network fill:#FFA500,stroke:#000,stroke-width:1px
```
