# livekit/node-sdks architecture

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

- Interactive diagram: https://gitdiagram.com/livekit/node-sdks
- Repository: https://github.com/livekit/node-sdks

## Overview

##### Project Type and Purpose
- This is a monorepo for two complementary Node.js SDKs for LiveKit:
- *livekit-rtc* – a realtime client SDK that lets your Node apps participate in WebRTC-based audio/video/data rooms using a Rust-based core with an FFI layer.
- *livekit-server-sdk* – a server-side API client that wraps LiveKit’s Twirp/gRPC endpoints for room management, ingress/egress, tokens, and webhooks.
- It provides libraries and examples so that developers can embed LiveKit-powered video/audio/data features into their applications.

##### File-Structure Analysis
- Top-level tooling and config: Turborepo (`turbo.json`), pnpm workspaces, TS/ESLint/Prettier, GitHub workflows.
- `packages/livekit-rtc`:
- Rust submodule (`.cargo/`, `build.rs`, `Cargo.toml`) and generated protobuf code under `src/proto`.
- JavaScript/TypeScript wrappers and FFI bindings in `src/napi` & `.ts` files.
- `packages/livekit-server-sdk`:
- Pure TypeScript RPC clients, token generators, webhook receivers under `src/`.
- `examples/`: multiple demo apps showing how to use each SDK in real environments (Next.js, simple Node scripts).

##### Key README Insights
- Monorepo using pnpm & Turborepo: build orchestration across packages and examples.
- Two main deliverables: realtime SDK (with audio/video/data) and server SDK (API/management).
- Examples illustrate both server event handling (webhooks) and media publish/subscribe flows.

a. Main Components to Represent
1. **Developer Application** (e.g., your Node.js service or example apps)
2. **livekit-server-sdk** (Twirp/gRPC client layer)
3. **livekit-rtc** (FFI → Rust core → WebRTC stack)
4. **LiveKit Server Cloud / Self-hosted** (external service providing rooms, media routing)
5. **Build & Tooling** (Turborepo, pnpm workspace, submodule fetch, CI)
b. Relationships and Interactions
- Build pipeline: local code edits → pnpm install/build → package artifacts → npm publish
c. Architectural Patterns & Principles
- **Modular Monorepo**: clear separation of server vs. realtime concerns, shared configs.
- **FFI Boundary**: JS ↔ Rust for performance-critical media handling.
- **Protobuf-driven API**: shared proto definitions generate code in both packages.
- **Examples as Integration Tests**: showcases extendability and usage patterns.
d. Key Technologies & Frameworks
- TypeScript, Node.js, Rust, N-API (for FFI), Protobuf, gRPC/Twirp, WebRTC, pnpm workspaces, Turborepo.

1. Sketch out the boundary between your *app code* and the two SDK packages.
4. A side-view of the monorepo build flow: root config → package builds → CI/CD → npm registry.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Application
    subgraph "Developer Application"
        DeveloperApp["Examples\n(examples/)"]:::frontend
    end

    %% SDK Packages
    subgraph "SDK Monorepo"
        subgraph "livekit-server-sdk" 
            ls_index["index.ts"]:::server
            ls_token["AccessToken.ts"]:::server
            ls_room["RoomServiceClient.ts"]:::server
            ls_ingress["IngressClient.ts\nEgressClient.ts"]:::server
            ls_webhook["WebhookReceiver.ts"]:::server
            ls_twirp["TwirpRPC.ts"]:::server
            ls_crypto["crypto utils"]:::server
        end
        subgraph "livekit-rtc"
            rtc_proto["Generated Protos\n(src/proto/)"]:::rtc
            rtc_ffi["N-API FFI\n(src/napi/)"]:::rtc
            rtc_rust["Rust Core\n(.cargo/, Cargo.toml,\nbuild.rs)"]:::rtc
            rtc_wrapper["JS/TS Wrappers\n(src/index.ts,\nffi_client.ts, room.ts, track.ts)"]:::rtc
        end
    end

    %% External LiveKit Server
    LiveKitServer["LiveKit Server\n(Self-hosted/Cloud)"]:::external

    %% Build & Tooling
    subgraph "Build & Tooling"
        BuildTool["Turborepo & pnpm workspace\nCI/CD"]:::build
    end

    %% Relationships
    DeveloperApp -->|"uses Server SDK"| ls_index
    DeveloperApp -->|"uses Realtime SDK"| rtc_wrapper

    ls_index -->|"HTTP/Twirp"| LiveKitServer
    rtc_wrapper -->|"N-API"| rtc_ffi
    rtc_ffi -->|"calls Rust"| rtc_rust
    rtc_wrapper -->|"uses Protos"| rtc_proto
    rtc_wrapper -->|"WebRTC media"| LiveKitServer

    BuildTool -->|"builds packages"| ls_index
    BuildTool -->|"builds packages"| rtc_wrapper
    BuildTool -->|"orchestrates examples"| DeveloperApp

    %% Click Events - Developer App
    click DeveloperApp "https://github.com/livekit/node-sdks/tree/main/examples/"

    %% Click Events - livekit-server-sdk
    click ls_index "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/index.ts"
    click ls_token "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/AccessToken.ts"
    click ls_room "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/RoomServiceClient.ts"
    click ls_ingress "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/IngressClient.ts"
    click ls_ingress "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/EgressClient.ts"
    click ls_webhook "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/WebhookReceiver.ts"
    click ls_twirp "https://github.com/livekit/node-sdks/blob/main/packages/livekit-server-sdk/src/TwirpRPC.ts"

    %% Click Events - livekit-rtc
    click rtc_rust "https://github.com/livekit/node-sdks/tree/main/packages/livekit-rtc/.cargo/"
    click rtc_rust "https://github.com/livekit/node-sdks/blob/main/packages/livekit-rtc/Cargo.toml"
    click rtc_rust "https://github.com/livekit/node-sdks/blob/main/packages/livekit-rtc/build.rs"
    click rtc_proto "https://github.com/livekit/node-sdks/tree/main/packages/livekit-rtc/src/proto/"
    click rtc_ffi "https://github.com/livekit/node-sdks/tree/main/packages/livekit-rtc/src/napi/"
    click rtc_wrapper "https://github.com/livekit/node-sdks/blob/main/packages/livekit-rtc/src/index.ts"

    %% Click Events - Build & Tooling
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/turbo.json"
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/pnpm-workspace.yaml"
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/package.json"
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/tsconfig.json"
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/.eslintrc"
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/.prettierrc"
    click BuildTool "https://github.com/livekit/node-sdks/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef frontend fill:#CCF,stroke:#000,stroke-width:1px
    classDef server fill:#CFC,stroke:#060,stroke-width:1px
    classDef rtc fill:#CCF,stroke:#006,stroke-width:1px
    classDef external fill:#FCC,stroke:#600,stroke-width:1px
    classDef build fill:#EEE,stroke:#666,stroke-width:1px
```
