# getstream/stream-video-swift architecture

> Architecture diagram of the GitHub repository getstream/stream-video-swift, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getstream/stream-video-swift
- Repository: https://github.com/getstream/stream-video-swift

## Overview

##### Project Type & Purpose
- This is an open-source iOS SDK (StreamVideo) for building video/audio calling and live streaming features.
- It provides:
- A low-level client (core library) handling signaling, WebSockets, REST, WebRTC, CallKit integration.
- Two UI layers: a SwiftUI SDK and a UIKit SDK (wrapping the SwiftUI components).
- One or more demo/sample apps (DemoApp, DemoAppUIKit, SwiftUIDemoApp).

##### High-Level File Structure Overview
- Top-level folders:
- Sources/StreamVideo – the core low-level client
- Sources/StreamVideoSwiftUI – the SwiftUI UI library
- Sources/StreamVideoUIKit – the UIKit wrapper
- DemoApp & DemoAppUIKit – sample applications integrating the SDK
- DocumentationTests – code snippets and guides
- ScreenSharing – iOS broadcast extension sample
- Tests & StreamVideoTests/StreamVideoSwiftUITests/StreamVideoUIKitTests – unit and UI tests
- CI/CD & tooling: .github workflows, Fastlane, Scripts, lint/config files

##### Main Components
a. Client Application Layer
- DemoApp (SwiftUI)
- DemoAppUIKit (UIKit)
- Optional SwiftUIDemoApp sample
b. UI SDK Layer
- StreamVideoSwiftUI
- StreamVideoUIKit (calls SwiftUI under the hood)
c. Core Library Layer (StreamVideo)
- HTTPClient (REST API calls to Stream backend)
- WebSocket Client (signaling)
- WebRTC Stack (media capture, encoding/decoding, SFU adapter, filters)
- CallKit Adapter (iOS native call integration)
- CallState & CallStateMachine (state management)
- Controllers (CallController, CallsController)
- DependencyInjection (InjectedValues)
- Models & OpenAPI generated code
- Utils (logging, queues, policies, proximity, audio session)
d. External Services
- Stream Video REST API & OpenAPI server
- Signaling & SFU servers (via WebSocket)
- STUN/TURN servers (media relay)
- Push notifications (optional)

##### Relationships & Data Flows
- App → UI SDK: App instantiates CallViewModel / CallViewController and applies UI modifiers or pushes controllers.
- UI SDK → Core: UI components invoke core APIs on StreamVideo object (e.g., create call, mute, send reaction).
- Core → HTTPClient: Core uses HTTPClient to fetch tokens or query call metadata.
- Core → WebSocket Client: Core subscribes to real-time call events over WebSocket.
- Core → WebRTC Stack: Core orchestrates media capture, encoding, SFU signaling, and rendering.
- Core → CallKit: Core integrates with iOS CallKit for system call screens.
- Core → External Services:
- REST API endpoints (connect, join call, list participants).
- WebSocket/SFU for signaling.
- STUN/TURN for NAT traversal.
- Optional: ScreenSharing extension → Core (via broadcast buffers).

##### Architectural Patterns & Principles
- Layered architecture: UI → SDK → Core → External services
- MVVM in SwiftUI: CallViewModel driving SwiftUI views
- Factory & Protocol-based injection: ViewFactory, DI with InjectedValues
- State machines: CallStateMachine & WebRTCCoordinator state machines
- Adapter patterns: CallKitAdapter, WebSocketAdapter, SFUAdapter
- OpenAPI code generation for REST models & clients

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Applications
    subgraph "Client Applications"
        direction TB
        DemoApp["DemoApp"]:::demo
        DemoAppUIKit["DemoAppUIKit"]:::demo
        SwiftUIDemoAppTests["SwiftUIDemoApp UITests"]:::demo
    end

    %% UI SDK Layer
    subgraph "UI SDK Layer"
        direction TB
        StreamVideoSwiftUI["StreamVideoSwiftUI"]:::ui
        StreamVideoUIKit["StreamVideoUIKit"]:::ui
    end

    %% Core Library Layer
    subgraph "Core Library (StreamVideo)" 
        direction TB
        Core["StreamVideo"]:::core
        HTTPClient["HTTPClient"]:::core
        WebSocketClient["WebSocket Client"]:::core
        WebRTCStack["WebRTC Stack"]:::core
        CallKitAdapter["CallKit Adapter"]:::core
        CallState["CallState & CallStateMachine"]:::core
        Controllers["Controllers"]:::core
        DI["Dependency Injection"]:::core
        Models["Models & OpenAPI"]:::core
        Utils["Utils"]:::core
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RESTAPI(("Stream Video REST API")):::external
        SignalingSFU(("WebSocket / SFU Servers")):::external
        STUNTURN(("STUN / TURN Servers")):::external
        PushNotif(("Push Notifications")):::external
    end

    %% Connections: Client to UI SDK
    DemoApp -->|"uses UI SDK"| StreamVideoSwiftUI
    DemoAppUIKit -->|"uses UI SDK"| StreamVideoUIKit
    SwiftUIDemoAppTests -->|"tests UI SDK"| StreamVideoSwiftUI

    %% UI SDK interactions
    StreamVideoUIKit -->|"wraps SwiftUI components"| StreamVideoSwiftUI
    StreamVideoSwiftUI -->|"invokes core APIs"| Core
    StreamVideoUIKit -->|"invokes core APIs"| Core

    %% Core internal composition
    Core -->|"REST calls"| HTTPClient
    Core -->|"WebSocket events"| WebSocketClient
    Core -->|"media stream"| WebRTCStack
    Core -->|"system call integration"| CallKitAdapter
    Core -->|"state management"| CallState
    Core -->|"control APIs"| Controllers
    Core -->|"injection"| DI
    Core -->|"data models"| Models
    Core -->|"helpers"| Utils

    %% Core to external
    HTTPClient -->|"REST call"| RESTAPI
    WebSocketClient -->|"signaling"| SignalingSFU
    WebRTCStack -->|"media relay"| STUNTURN
    CallKitAdapter -->|"push events"| PushNotif

    %% Click Events
    click DemoApp "https://github.com/getstream/stream-video-swift/tree/develop/DemoApp/"
    click DemoAppUIKit "https://github.com/getstream/stream-video-swift/tree/develop/DemoAppUIKit/"
    click SwiftUIDemoAppTests "https://github.com/getstream/stream-video-swift/tree/develop/SwiftUIDemoAppUITests/"
    click StreamVideoSwiftUI "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideoSwiftUI/"
    click StreamVideoUIKit "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideoUIKit/"
    click Core "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/"
    click HTTPClient "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/HTTPClient/"
    click WebSocketClient "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/WebSockets/Client/"
    click WebSocketClient "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/WebSockets/Events/"
    click WebRTCStack "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/WebRTC/"
    click CallKitAdapter "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/CallKit/"
    click CallState "https://github.com/getstream/stream-video-swift/blob/develop/Sources/StreamVideo/CallState.swift"
    click CallState "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/CallStateMachine/"
    click Controllers "https://github.com/getstream/stream-video-swift/blob/develop/Sources/StreamVideo/Controllers/CallController.swift"
    click Controllers "https://github.com/getstream/stream-video-swift/blob/develop/Sources/StreamVideo/Controllers/CallsController.swift"
    click DI "https://github.com/getstream/stream-video-swift/blob/develop/Sources/StreamVideo/DependencyInjection/InjectedValues.swift"
    click DI "https://github.com/getstream/stream-video-swift/blob/develop/Sources/StreamVideo/DependencyInjection/InjectedValuesExtensions.swift"
    click Models "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/Models/"
    click Models "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/OpenApi/generated/"
    click Utils "https://github.com/getstream/stream-video-swift/tree/develop/Sources/StreamVideo/Utils/"

    %% Styles
    classDef core fill:#E3F2FD,stroke:#2196F3,stroke-width:2px
    classDef ui fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px
    classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef demo fill:#EEEEEE,stroke:#9E9E9E,stroke-width:2px,stroke-dasharray: 5 5
```
