# livekit/python-sdks architecture

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

## Overview

##### And Represent the Main Components
- Client Application(s): Represent the upper layer where developers use the SDK.
- LiveKit RTC Component (found in the “livekit-rtc” directory): This layer handles real-time media, audio, and video streaming, and provides event handling for room events (e.g., participant connection, track subscription, etc.) using asynchronous patterns. It includes components like video stream, audio mixer, and event emitter.
- LiveKit API Component (in “livekit-api”): This provides access token generation, room management, and other server-side interactions using asynchronous HTTP clients (aiohttp, asyncio). It wraps REST/API endpoints for services such as room service, egress/ingress, SIP, and agent dispatch.
- LiveKit Protocol Component (in “livekit-protocol”): Underneath, this defines the protocol (e.g., via proto files and Python type hints) that standardizes the communication and message formats between the client and server components.
- Examples & Helpers: The examples directory illustrates common usage patterns (e.g., connecting to a room, handling RPC, data streaming, face landmark detection), and provides a “live” view of integration with the above components.

##### Relationships and Interactions
- A client application uses the “livekit” package (RTC) to initiate connection to a video room, handling events such as participant connections and track publications.
- The client can also interface with “livekit-api” to generate tokens or manage rooms by making API requests.
- All the RTT and API interactions follow a defined protocol (structure and messaging) as set out in the “livekit-protocol” package.

##### Architectural Patterns & Design Principles
- Modularity: Three distinct packages (API, RTC, Protocol) allow separation of concerns.
- Asynchronous Communication: The usage of asyncio and aiohttp in the API layer, as well as event-driven patterns in RTC, are central design decisions.
- Protocol-Driven Interoperability: The “protocol” package ensures that all components adhere to standard message formats through protocol buffers (with auto-generated code/scripts like generate_proto.sh).
- Extensibility & Loose Coupling: The design (e.g., registration of RPC methods and event handlers) facilitates modular extension in client applications.

##### Relevant Technologies, Frameworks, and Patterns
- Python and its asyncio framework.
- aiohttp for API-related calls.
- Protocol buffers (in the protocol directory) to define message contracts.
- Use of type checking tools (Mypy, Ruff, etc.) as indicated in the configuration files.
- CI/CD workflows are implemented in GitHub Actions (located under .github/workflows) but these can be optionally noted as part of the “deployment/quality control” slice if required.

○ Data flow from the client to the RTC module (e.g., initiating connection, subscribing to tracks).
○ API calls from the client (or server operator) to the LiveKit API endpoints.
○ The “protocol” layer linking between RTC and API modules.

##### Detail and Clarity
- Within the API module, include parts that handle token generation, room creation, and service-specific communications (e.g., egress, ingress).
- Don’t hesitate to show interdependencies; for instance, the RTC module triggers callbacks (like “on_track_subscribed”) that may result in handling media streams or performing RPC calls.
- Cross-component interactions (for example, the client using both the RTC and API libraries, with shared credentials or tokens issued by the API module).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        A["Client Application"] 
    end

    %% LiveKit RTC Module
    subgraph "RTC Module"
        R0["LiveKit RTC"]
        R1["Video Streaming"]
        R2["Audio Mixer"]
        R3["Event Emitter"]
        R0 --> R1
        R0 --> R2
        R0 --> R3
    end

    %% LiveKit API Module
    subgraph "API Module"
        A0["LiveKit API"]
        A1["Token Generation"]
        A2["Room Management"]
        A0 --> A1
        A0 --> A2
    end

    %% LiveKit Protocol Layer
    subgraph "Protocol Layer"
        P["LiveKit Protocol"]
    end

    %% Data Flows and Relationships
    A -->|"establishMediaStream"| R1
    A -->|"APIRequests"| A2
    R0 -->|"protocolIntegration"| P
    A0 -->|"protocolInterface"| P
    R3 -->|"emitEvents"| P

    %% Click Events
    click A "https://github.com/livekit/python-sdks/tree/main/examples/"
    click R0 "https://github.com/livekit/python-sdks/tree/main/livekit-rtc/livekit/rtc/"
    click A0 "https://github.com/livekit/python-sdks/tree/main/livekit-api/livekit/api/"
    click P "https://github.com/livekit/python-sdks/tree/main/livekit-protocol/livekit/protocol/"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef rtc fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef api fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef protocol fill:#FFB6C1,stroke:#333,stroke-width:2px;

    class A client;
    class R0,R1,R2,R3 rtc;
    class A0,A1,A2 api;
    class P protocol;
```
