# irdkwmnsb/webrtc-grabber architecture

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

- Interactive diagram: https://gitdiagram.com/irdkwmnsb/webrtc-grabber
- Repository: https://github.com/irdkwmnsb/webrtc-grabber

## Overview

##### Main Components
- Grabber: A stand-alone Electron-based application (in packages/grabber) that runs on the contestants’ PCs. It performs screen (and webcam) capture and initiates a connection via a configured signaling URL.
- Signaling Server: Built primarily from the code in packages/relay (specifically, the cmd/signalling module and associated internal packages). It is a stateful server (originally described as an “express http server” with Socket.io endpoints) responsible for managing peer registration, delivering ICE configuration details (with TURN server info), and coordinating connection setup between Grabbers and viewers.
- TURN Server: Implemented in packages/go-turn, this lightweight Go-based TURN server is deployed to handle NAT traversal by relaying multimedia packets between peers when direct connections are not possible.

##### File Structure and Build Artifacts
- The top-level directories such as “packages” (with sub-directories for grabber, go-turn, relay, and player-common) indicate a modular design with separate responsibilities.
- The “debian” and “rpm” directories include packaging scripts for different Linux distributions—illustrating that deployment artifacts have been customized per target platform.
- Workflow files in “.github/workflows” suggest CI/CD pipelines for building and releasing each component.
- In the “packages/relay” directory, assets (HTML files and JavaScript code) support the browser-based video streaming interface (“players”), in addition to the signaling server functionality.

##### Component Relationships and Data Flow
- Grabber → Signaling Server: The Grabber application initiates a connection to the signaling server by pinging it at an interval defined in its configuration file (e.g., every 3 seconds). It also receives a “peerConfig” (including ICE server details) from the signaling server.
- Signaling Server → TURN Server: The signaling server supplies TURN configuration (including TURN server URL, username, and credential) in the ICE configuration to enable NAT traversal. In cases where direct peer-to-peer communication is not feasible, TURN relays audio/video packets.
- Optional Connections: Viewers (or “players”, which may leverage code under packages/player-common and assets from packages/relay/asset) connect to the signaling server to obtain the list of active Grabbers and to establish connections.

##### Architectural Patterns and Principles
- Modularity: Each major function (capture, signaling, TURN) is separated into its own module with dedicated configuration and build instructions.
- Microservices / Component-based: Although deployed as separate binaries or Docker containers (see docker-compose.yml and Dockerfiles), the components interact through clear, well-defined protocols (HTTP/WebSocket for signaling; TURN for media relay).
- NAT/Network Traversal: The use of a TURN server is central to handling network restrictions, and the configuration files make it evident that ICE-based connection strategies are applied.
- Build and Deployment: The use of CI/CD workflows in GitHub Actions and packaging scripts for both Debian and RPM platforms signifies a deployment plan that caters for various environments.

a. A layout that separates the system into “Client” and “Server/Infrastructure” layers.
b. On the client side:
– Place “Grabber (Screen & Webcam Capture)” with a note “Electron application – configured via packages/grabber/config.json”.
– Add the “Viewer/Player” component (if applicable) represented by assets served for browser-based streams.
c. In the server/infrastructure layer:
– From “Grabber” to “Signaling Server”: label it “Connection initiation, pings, and ICE negotiation”.
– From “Signaling Server” back to “Grabber”: label it “Peer config with ICE / TURN details”.
e. Optionally, add an “Infrastructure/Deployment” note indicating the CI/CD pipelines (GitHub workflows, Docker Compose) and packaging aspects (debian, rpm).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        Grabber["Grabber (Electron App)\n(Screen & Webcam Capture)"]
        subgraph "Viewer/Player"
            PlayerCommon["Player Common"]
            RelayAsset["Relay Asset"]
        end
    end

    %% Server/Infrastructure Layer
    subgraph "Server/Infrastructure Layer"
        Signaling["Signaling Server\n(Express+Socket.io)\nEndpoints:'/peer','/admin'"]
        SignalingConfig["Signaling Config\n(packages/relay/conf/config.json)"]
        Turn["TURN Server\n(Go-based)"]
        Deployment["Deployment/CI-CD\n(GitHub Actions, Debian, RPM)"]
    end

    %% Connections
    Grabber -->|"Connection initiation, pings, and ICE negotiation"| Signaling
    Signaling -->|"Peer config with ICE/TURN details"| Grabber
    Signaling -->|"TURN server configuration/reference"| Turn
    Turn -->|"Media/Data packet relay"| Grabber
    Turn -->|"Media/Data packet relay"| PlayerCommon
    Turn -->|"Media/Data packet relay"| RelayAsset
    Signaling -->|"Uses config"| SignalingConfig

    %% Click Events
    click Grabber "https://github.com/irdkwmnsb/webrtc-grabber/tree/main/packages/grabber"
    click Signaling "https://github.com/irdkwmnsb/webrtc-grabber/tree/main/packages/relay/cmd/signalling"
    click SignalingConfig "https://github.com/irdkwmnsb/webrtc-grabber/blob/main/packages/relay/conf/config.json"
    click Turn "https://github.com/irdkwmnsb/webrtc-grabber/tree/main/packages/go-turn"
    click PlayerCommon "https://github.com/irdkwmnsb/webrtc-grabber/tree/main/packages/player-common"
    click RelayAsset "https://github.com/irdkwmnsb/webrtc-grabber/tree/main/packages/relay/asset"

    %% Styles
    classDef client fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef server fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef infrastructure fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    
    class Grabber,PlayerCommon,RelayAsset client;
    class Signaling,SignalingConfig,Turn server;
    class Deployment infrastructure;
```
