# pion/webrtc architecture

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

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

## Overview

##### Main Components
- Core API Layer – This includes the main entry points such as the PeerConnection APIs (peerconnection.go, peerconnection_js.go, etc.) which expose the WebRTC interface.
- ICE Module – Components for ICE agent and candidates (files like ice_go.go, icecandidate.go, icegatherer.go, etc.) that handle connectivity, candidate gathering, and negotiations.
- DTLS/SRTP Layer – Files dealing with DTLS handshakes, policies, and DTLS/SRTP encryption (dtlsfingerprint.go, dtlsparameters.go, dtlstransport.go, srtp_writer_future.go, etc.).
- SCTP/DataChannels – Modules for data channel initialization and management (datachannel.go, datachannelparameters.go, sctptransport.go, etc.) to manage both reliable and unreliable channels.
- Media Engine – Components managing media negotiation, codecs, and RTP/RTCP pipeline (mediaengine.go, rtpcodec.go, rtpreceiver.go, rtpsender.go, etc.) along with packages in pkg/media, which also provide readers, writers, and sample builders.
- SDP and Signaling – Modules for session descriptions and signaling state management (sdp.go, sessiondescription.go, signalingstate.go, etc.) that handle SDP semantics and offer/answer exchanges.
- Interceptor/Mux and Internal Utilities – Various interceptors for RTP/RTCP processing and internal modules (files in internal/mux and internal/util) that support routing, error handling, and logging.
- Configuration / Setting Engine – Components like settingengine.go (and its JS variant) that allow developers to tweak behavior and extend functionality.
- Testing & Examples – A large set of examples, e2e tests, and test files scattered across directories like “e2e” and “examples”. They indicate how the pieces work together and provide context on real-world usage.

##### Relationships and Interactions
- The PeerConnection API is the central component that orchestrates other modules. It interacts directly with ICE, DTLS, and media modules.
- The ICE module is responsible for candidate gathering and connectivity checks. It works closely with the network-type and connection state components.
- DTLS is used to secure the connection between peers and is tied to the SCTP layer (for data channels) and media pipeline (for SRTP encryption).
- The media engine handles encoding/decoding and packetization of audio/video streams communicating via RTP/RTCP. It also integrates with packetizers provided in pkg directories.
- SDP and signaling components are responsible for negotiating connection parameters (offer/answer model) among peers.
- The configuration and setting engine let users configure many behaviors for ICE, DTLS, and even more fine-grained endpoints.
- Internal utility packages and interceptors glue the system together by augmenting or pre-/post-processing data flows between the major components.

##### Architectural Patterns and Design Principles
- Layered Architecture: The library is clearly separated into layers (API, connectivity, security, media processing) to foster modularity and ease of testing.
- Component-Based Design: Each major part of the WebRTC stack (ICE, DTLS, SCTP, media engine) is encapsulated into its own set of modules/packages.
- Test-Driven Development: A broad range of tests (unit tests, e2e tests) are available which show emphasis on component isolation and integration.
- Extensibility: The presence of SettingEngine and interceptor modules highlights the design for customization and extensibility.

##### Relevant Technologies, Frameworks, or Libraries
- Go and its Modules system, as emphasized in the README.
- Usage of native libraries for handling protocols (ICE, DTLS, SCTP, RTP) fully implemented in Go.
- Integration examples with third-party media libraries (x264, libvpx, GStreamer, ffmpeg) are mentioned as potential extensions.

##### Execution
- Directional flows (data flow, control flow, dependencies) are clearly marked.
- The final output should be self-explanatory to an engineer wanting to understand how Pion WebRTC implements a full WebRTC stack purely in Go.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    app("Application (External)"):::external
    ext1("External Network (STUN/TURN)"):::external

    %% Core API Layer
    subgraph "Core API Layer"
        core1("PeerConnection API"):::api
        core2("API Entry"):::api
        core3("PeerConnection_JS"):::api
    end

    %% ICE Module
    subgraph "ICE Module"
        ice1("ICE Agent"):::ice
        ice2("ICE Candidate"):::ice
        ice3("ICE Gatherer"):::ice
        ice4("ICE Transport"):::ice
    end

    %% DTLS/SRTP Layer
    subgraph "DTLS/SRTP Layer"
        dtls1("DTLS/SRTP Core"):::dtls
        dtls2("DTLS Parameters"):::dtls
        dtls3("DTLS Transport"):::dtls
        dtls4("SRTP Writer"):::dtls
    end

    %% SCTP/DataChannels
    subgraph "SCTP/DataChannels"
        sctp1("DataChannel Core"):::sctp
        sctp2("DataChannel Parameters"):::sctp
        sctp3("SCTP Transport"):::sctp
    end

    %% Media Engine
    subgraph "Media Engine"
        media1("Media Engine Core"):::media
        media2("RTP Codec"):::media
        media3("RTP Receiver"):::media
        media4("RTP Sender"):::media
        media5("Media Package"):::media
    end

    %% SDP & Signaling
    subgraph "SDP & Signaling"
        sdp1("SDP Module"):::sdp
        sdp2("Session Description"):::sdp
        sdp3("Signaling State"):::sdp
    end

    %% Configuration / Setting Engine
    subgraph "Configuration / Setting Engine"
        config1("Setting Engine"):::config
        config2("Configuration"):::config
    end

    %% Interceptors & Internal Utilities
    subgraph "Interceptors & Internal Utilities"
        int1("Interceptor"):::int
        int2("Mux Utilities"):::int
        int3("Internal Utilities"):::int
    end

    %% Testing & Examples
    subgraph "Testing & Examples"
        test1("End-to-End Tests"):::test
        test2("Examples"):::test
    end

    %% Connections
    app -->|"calls"| core1
    ext1 -->|"assists"| ice1
    core1 -->|"initiates"| ice1
    ice1 -->|"secures"| dtls1
    dtls1 -->|"enables"| sctp1
    dtls1 -->|"encrypts"| media1
    core1 -->|"negotiates"| sdp1
    core1 -->|"configures"| config1
    core1 -->|"handlesMedia"| media1
    core1 -->|"processes"| int1
    app ---|"tests"| test1

    %% Class Definitions
    classDef api fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef ice fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef dtls fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef sctp fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef media fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef sdp fill:#40E0D0,stroke:#333,stroke-width:2px;
    classDef config fill:#FF6347,stroke:#333,stroke-width:2px;
    classDef int fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef test fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef external fill:#F08080,stroke:#333,stroke-width:2px;

    %% Click Events for Core API Layer
    click core1 "https://github.com/pion/webrtc/blob/master/peerconnection.go"
    click core2 "https://github.com/pion/webrtc/blob/master/api.go"
    click core3 "https://github.com/pion/webrtc/blob/master/peerconnection_js.go"

    %% Click Events for ICE Module
    click ice1 "https://github.com/pion/webrtc/blob/master/ice_go.go"
    click ice2 "https://github.com/pion/webrtc/blob/master/icecandidate.go"
    click ice3 "https://github.com/pion/webrtc/blob/master/icegatherer.go"
    click ice4 "https://github.com/pion/webrtc/blob/master/icetransport.go"

    %% Click Events for DTLS/SRTP Layer
    click dtls1 "https://github.com/pion/webrtc/blob/master/dtlsfingerprint.go"
    click dtls2 "https://github.com/pion/webrtc/blob/master/dtlsparameters.go"
    click dtls3 "https://github.com/pion/webrtc/blob/master/dtlstransport.go"
    click dtls4 "https://github.com/pion/webrtc/blob/master/srtp_writer_future.go"

    %% Click Events for SCTP/DataChannels
    click sctp1 "https://github.com/pion/webrtc/blob/master/datachannel.go"
    click sctp2 "https://github.com/pion/webrtc/blob/master/datachannelparameters.go"
    click sctp3 "https://github.com/pion/webrtc/blob/master/sctptransport.go"

    %% Click Events for Media Engine
    click media1 "https://github.com/pion/webrtc/blob/master/mediaengine.go"
    click media2 "https://github.com/pion/webrtc/blob/master/rtpcodec.go"
    click media3 "https://github.com/pion/webrtc/blob/master/rtpreceiver.go"
    click media4 "https://github.com/pion/webrtc/blob/master/rtpsender.go"
    click media5 "https://github.com/pion/webrtc/tree/master/pkg/media"

    %% Click Events for SDP & Signaling
    click sdp1 "https://github.com/pion/webrtc/blob/master/sdp.go"
    click sdp2 "https://github.com/pion/webrtc/blob/master/sessiondescription.go"
    click sdp3 "https://github.com/pion/webrtc/blob/master/signalingstate.go"

    %% Click Events for Configuration / Setting Engine
    click config1 "https://github.com/pion/webrtc/blob/master/settingengine.go"
    click config2 "https://github.com/pion/webrtc/blob/master/configuration.go"

    %% Click Events for Interceptors & Internal Utilities
    click int1 "https://github.com/pion/webrtc/blob/master/interceptor.go"
    click int2 "https://github.com/pion/webrtc/tree/master/internal/mux"
    click int3 "https://github.com/pion/webrtc/tree/master/internal/util"

    %% Click Events for Testing & Examples
    click test1 "https://github.com/pion/webrtc/tree/master/e2e"
    click test2 "https://github.com/pion/webrtc/tree/master/examples"
```
