# livekit/sip architecture

> Architecture diagram of the GitHub repository livekit/sip, 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/livekit/sip
- Repository: https://github.com/livekit/sip

## Overview

##### Main Components
- SIP Service Entry Point: Represented by the “cmd/livekit-sip” package and its main.go file. This is where the SIP service boots up.
- SIP Logic and Protocol Handling: Shown in “pkg/sip”, including separate modules for SIP inbound/outbound, client/server, media handling for SIP, and associated tests in “pkg/siptest”.
- Media Processing: Modules under “pkg/media” (including RTP, SDP, tone generation, codecs like g711, g722, opus, and resampling). These constitute the core media pipelines for handling media streams.
- Audio Test and Mixer Components: For validating audio or mixing streams (from “pkg/audiotest” and “pkg/mixer”).
- Configuration and Error handling: “pkg/config” and “pkg/errors” indicate centralized configuration loading (reading YAML files or environment variables) and error management.
- Internal Utilities: Elements like the ring buffer in “pkg/internal” support low-level media processing.
- Service APIs: The SIP-related service logic (e.g., “pkg/service”) to integrate with external LiveKit APIs and internal dispatching.

##### Supporting External and Infrastructure Components
- LiveKit Server: The service interacts with LiveKit through API calls (for creating SIP trunks and dispatch rules) and via WebSocket connections.
- Redis: As emphasized in the README, Redis is used for both SIP session state storage and as middleware for communication between SIP service and the LiveKit server.
- Docker & Build Infrastructure: The project includes several Docker and GitHub Actions pipelines (located under .github/workflows, Dockerfiles in the build directory, and docker-compose.yaml) — represent these as deployment/build/integration components.

##### Relationships and Interactions
- How the external SIP endpoints (calling devices or providers) connect to the SIP service’s “public IP” (as noted in the README).
- Data flow: SIP messages are received by the SIP service, processed using the SIP protocols (see packages under pkg/sip) and then forwarded (or bridged) into a LiveKit room.
- Media engine (handling RTP, codecs, DTMF, etc.) to both SIP endpoints and LiveKit’s media ingestion mechanisms.
- Integrate Redis as a core component that both the SIP service and LiveKit server use to exchange session state information.

##### Incorporate Architectural Patterns and Design Principles
- Use of microservice communication patterns such as event-based Redis messaging.
- Distinguish between synchronous API interactions (e.g., creating trunks and dispatch rules via livekit-cli or API calls) versus asynchronous session state management.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Components
    EXT_SIP["External SIP Endpoints"]:::external
    LIVEKIT["LiveKit Server (External)"]:::external
    REDIS["Redis (Session State)"]:::external

    %% SIP Service Core
    subgraph "SIP Service Core"
        ENTRY["SIP Service Entry Point (cmd/livekit-sip)"]:::core
        SIP_LOGIC["SIP Logic & Protocol Handling (pkg/sip)"]:::core
        ENTRY -->|"initiates"| SIP_LOGIC
    end

    %% Media Engine
    subgraph "Media Engine"
        MEDIA["Media Processing (pkg/media)"]:::media
        AUDIO_TEST["Audio Testing (pkg/audiotest)"]:::media
        AUDIO_MIXER["Audio Mixer (pkg/mixer)"]:::media
        UTIL["Ring Buffer Utility (pkg/internal/ringbuf)"]:::media
        SIP_LOGIC -->|"media_pipeline"| MEDIA
        MEDIA -->|"utilizes"| UTIL
        MEDIA -->|"supports"| AUDIO_TEST
        MEDIA -->|"supports"| AUDIO_MIXER
    end

    %% API Integration
    subgraph "API Integration"
        SERVICE_API["Service API Integration (pkg/service)"]:::api
        SIP_LOGIC -->|"calls_services"| SERVICE_API
        SERVICE_API -->|"api_calls"| LIVEKIT
        LIVEKIT -->|"responses"| SERVICE_API
    end

    %% Configuration & Error Handling
    subgraph "Configuration & Error"
        CONFIG["Configuration Management (pkg/config)"]:::config
        ERRORS["Error Handling (pkg/errors)"]:::config
        ENTRY -->|"loads"| CONFIG
        ENTRY -->|"logs"| ERRORS
        SIP_LOGIC -->|"loads"| CONFIG
        SIP_LOGIC -->|"logs"| ERRORS
    end

    %% External Communication
    subgraph "External Communication"
        EXT_SIP -->|"SIP_traffic"| ENTRY
        SIP_LOGIC -->|"session_state"| REDIS
        SERVICE_API -->|"session_state"| REDIS
        REDIS -->|"state_updates"| SERVICE_API
    end

    %% Deployment & Build Infrastructure
    subgraph "Deployment & Build"
        DOCKER["Docker Build (build/sip/Dockerfile)"]:::deploy
        ORCHESTRATION["Container Orchestration (docker-compose.yaml)"]:::deploy
        CICD["CI/CD Pipelines (.github/workflows)"]:::deploy
    end

    %% Deployment connections
    DOCKER -->|"builds"| ENTRY
    ORCHESTRATION -->|"deploys"| ENTRY
    CICD -->|"automates"| ENTRY

    %% Class Definitions for styling
    classDef core fill:#e0f7fa,stroke:#0277bd,stroke-width:2px;
    classDef media fill:#d1c4e9,stroke:#6a1b9a,stroke-width:2px;
    classDef api fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef config fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#f57c00,stroke-width:2px;
    classDef deploy fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;

    %% Click Events
    click ENTRY "https://github.com/livekit/sip/blob/main/cmd/livekit-sip/main.go"
    click SIP_LOGIC "https://github.com/livekit/sip/tree/main/pkg/sip"
    click MEDIA "https://github.com/livekit/sip/tree/main/pkg/media"
    click AUDIO_TEST "https://github.com/livekit/sip/tree/main/pkg/audiotest"
    click AUDIO_MIXER "https://github.com/livekit/sip/tree/main/pkg/mixer"
    click CONFIG "https://github.com/livekit/sip/tree/main/pkg/config"
    click ERRORS "https://github.com/livekit/sip/tree/main/pkg/errors"
    click UTIL "https://github.com/livekit/sip/tree/main/pkg/internal/ringbuf"
    click SERVICE_API "https://github.com/livekit/sip/tree/main/pkg/service"
    click DOCKER "https://github.com/livekit/sip/tree/main/build/sip/Dockerfile"
    click ORCHESTRATION "https://github.com/livekit/sip/blob/main/docker-compose.yaml"
    click CICD "https://github.com/livekit/sip/tree/main/.github/workflows"
```
