# shinyoshiaki/node-sfu architecture

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

- Interactive diagram: https://gitdiagram.com/shinyoshiaki/node-sfu
- Repository: https://github.com/shinyoshiaki/node-sfu

## Overview

##### Project type and purpose
- This is a full‐stack monorepo for a real‐time communications SDK and demo.
- Core functionality (packages/core, packages/json-rpc, packages/utils) implements pub/sub, data/media publication, fragmentation/compression, and JSON-RPC transport.
- packages/client is an SDK wrapper around core for application code.
- packages/conference is a React+Tailwind demo web app that uses the SDK to run multi‐party video, audio, and chat.
- packages/reference-server is a lightweight JSON-RPC server for signaling.
- packages/e2e and packages/conference/e2e hold end‐to‐end tests.
- A werift submodule provides pure‐JS WebRTC stack.

##### Main components
A. Frontend Application
– packages/conference (React UI, hooks, components, ConferenceLayout, ChatPanel, VideoGrid)
– uses the client SDK for data/media operations.
B. Client SDK
– packages/client (connectionManager, publisher/subscriber, data/mediaPublication/subscription)
– depends on JSON-RPC adapter and core logic.
C. Core Library
– packages/core (room/member abstractions, data/media pub/sub implementations)
– imports werift adapter for WebRTC, JSON-RPC transport shim, util modules.
D. JSON-RPC Module
– packages/json-rpc (jsonrpc.ts, transport.ts, types) used by both core and client to encode/decode messages over WebSocket or other transports.
E. Utilities
– packages/utils (fragmentation, compression) for splitting large data frames.
F. Reference Signaling Server
– packages/reference-server (main.ts) provides a JSON-RPC over WebSocket endpoint, routes messages between members in the same room.
G. Subsystems & Tests
– Submodule werift for WebRTC peer connection stack.
– packages/e2e and conference/e2e to drive end‐to‐end scenarios via Playwright or Vitest.

##### Relationships & Data flows
- UI events in the conference app → client SDK APIs (publisher.publishData(), subscriber.subscribeMedia(), etc.)
- SDK invokes JSON-RPC transport → connects to reference-server over WebSocket → server forwards messages to peers.
- Core uses werift to establish WebRTC peer connections for media/data channels.
- Utils (fragmentation/compression) used by SDK for large‐payload handling.
- Peer‐to‐peer channels carry data/media after signaling.

##### Architectural patterns & principles
- Monorepo + packages: clear separation of concerns (core logic, protocol, SDK, demo, server, tests).
- Pub/Sub pattern for both data and media publication/subscription.
- Adapter pattern: JSON-RPC adapter, werift adapter.
- Layered design: UI → SDK → Core/Protocol → Transport → Network.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend Application
  subgraph "Frontend Application (packages/conference)"
    ConferenceApp["Conference App"]:::frontend
    ConfSrc["src"] 
    ConfComponents["src/components"]
    ConfHook1["src/hooks/useScreenShare.ts"]
    ConfHook2["src/useVideoWebRTC.ts"]
    ConfHTML["index.html"]
  end

  %% Client SDK
  subgraph "Client SDK (packages/client)"
    ClientSDK["Client SDK"]:::sdk
    CIndex["src/index.ts"]
    ConnMgr["src/connectionManager.ts"]
    Publisher["src/publisher.ts"] 
    MediaPub["src/mediaPublication.ts"]
    DataPub["src/dataPublication.ts"]
    Subscriber["src/subscriber.ts"]
    MediaSub["src/mediaSubscription.ts"]
    DataSub["src/dataSubscription.ts"]
    MsgAsmClient["src/adapters/messageAssemblerTransport.ts"]
    CJSONRPC["src/imports/json-rpc.ts"]
    CUtil["src/imports/util.ts"]
  end

  %% Core Library
  subgraph "Core Library (packages/core)"
    CoreLib["Core Library"]:::core
    CoreIndex["src/index.ts"]
    Room["src/room.ts"]
    Member["src/member.ts"]
    CoreDataPub["src/dataPublication.ts"]
    CoreDataSub["src/dataSubscription.ts"]
    CoreMediaPub["src/mediaPublication.ts"]
    CoreMediaSub["src/mediaSubscription.ts"]
    MsgAsmCore["src/adapters/messageAssemblerTransport.ts"]
    CoreJSONRPC["src/imports/json-rpc.ts"]
    CoreUtil["src/imports/util.ts"]
    CoreWerift["src/imports/werift.ts"]
  end

  %% JSON-RPC Module
  subgraph "JSON-RPC Module (packages/json-rpc)"
    JSONRPCModule["JSON-RPC Module"]:::protocol
    JIndex["src/index.ts"]
    JRPC["src/jsonrpc.ts"]
    JTrans["src/transport.ts"]
    JTypes["src/types.ts"]
  end

  %% Utilities
  subgraph "Utilities (packages/utils)"
    Utils["Utilities"]:::protocol
    Frag["src/fragmentation.ts"]
    Comp["src/compression.ts"]
    UIndex["src/index.ts"]
  end

  %% Reference Signaling Server
  subgraph "Reference Signaling Server (packages/reference-server)"
    ReferenceServer["Reference Server"]:::infra
    ServerMain["src/main.ts"]
  end

  %% WebRTC Submodule
  subgraph "WebRTC Submodule (werift)"
    Werift["werift (submodule)"]:::infra
  end

  %% End-to-End Tests
  subgraph "End-to-End Tests"
    E2E["Root E2E Tests"]:::infra
    ConfE2E["conference E2E Tests"]:::infra
  end

  %% Relationships
  ConferenceApp -->|"publishMedia()/publishData()"| ClientSDK
  ClientSDK -->|"depends on"| CoreLib
  ClientSDK -->|"uses"| Utils
  ClientSDK -->|"uses JSON-RPC"| JSONRPCModule
  JSONRPCModule -->|"JSON-RPC over WS"| ReferenceServer
  ReferenceServer -->|"routes messages"| JSONRPCModule
  CoreLib -->|"WebRTC peer connection"| Werift
  Werift -->|"RTCDataChannel"| Werift
  E2E -->|drives| ConferenceApp
  E2E -->|drives| ReferenceServer
  ConfE2E -->|drives| ConferenceApp

  %% Click Events
  click ConfSrc "https://github.com/shinyoshiaki/node-sfu/tree/v2/packages/conference/src"
  click ConfComponents "https://github.com/shinyoshiaki/node-sfu/tree/v2/packages/conference/src/components"
  click ConfHook1 "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/conference/src/hooks/useScreenShare.ts"
  click ConfHook2 "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/conference/src/useVideoWebRTC.ts"
  click ConfHTML "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/conference/index.html"
  click CIndex "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/index.ts"
  click ConnMgr "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/connectionManager.ts"
  click Publisher "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/publisher.ts"
  click MediaPub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/mediaPublication.ts"
  click DataPub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/dataPublication.ts"
  click Subscriber "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/subscriber.ts"
  click MediaSub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/mediaSubscription.ts"
  click DataSub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/dataSubscription.ts"
  click MsgAsmClient "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/adapters/messageAssemblerTransport.ts"
  click CJSONRPC "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/imports/json-rpc.ts"
  click CUtil "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/client/src/imports/util.ts"
  click CoreIndex "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/index.ts"
  click Room "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/room.ts"
  click Member "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/member.ts"
  click CoreDataPub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/dataPublication.ts"
  click CoreDataSub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/dataSubscription.ts"
  click CoreMediaPub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/mediaPublication.ts"
  click CoreMediaSub "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/mediaSubscription.ts"
  click MsgAsmCore "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/adapters/messageAssemblerTransport.ts"
  click CoreJSONRPC "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/imports/json-rpc.ts"
  click CoreUtil "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/imports/util.ts"
  click CoreWerift "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/core/src/imports/werift.ts"
  click JIndex "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/json-rpc/src/index.ts"
  click JRPC "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/json-rpc/src/jsonrpc.ts"
  click JTrans "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/json-rpc/src/transport.ts"
  click JTypes "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/json-rpc/src/types.ts"
  click Frag "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/utils/src/fragmentation.ts"
  click Comp "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/utils/src/compression.ts"
  click UIndex "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/utils/src/index.ts"
  click ServerMain "https://github.com/shinyoshiaki/node-sfu/blob/v2/packages/reference-server/src/main.ts"
  click Werift "https://github.com/shinyoshiaki/node-sfu/tree/v2/submodules/werift"
  click E2E "https://github.com/shinyoshiaki/node-sfu/tree/v2/packages/e2e"
  click ConfE2E "https://github.com/shinyoshiaki/node-sfu/tree/v2/packages/conference/e2e"

  %% Styles
  classDef frontend fill:#D0E7FF,stroke:#0366d6,stroke-width:2px
  classDef sdk fill:#DFFFE0,stroke:#2C662D,stroke-width:2px
  classDef core fill:#E0F7FF,stroke:#2079A0,stroke-width:2px
  classDef protocol fill:#FFF4E5,stroke:#D66F0F,stroke-width:2px
  classDef infra fill:#F0F0F0,stroke:#666666,stroke-width:2px
```
