# getstream/stream-chat-swift architecture

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

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

## Overview

##### Project Type and Purpose
- This is a multi-module iOS SDK repository for Stream Chat, providing:
- A low-level client (LLC) for pure networking and local state (Sources/StreamChat).
- A UIKit UI SDK (Sources/StreamChatUI).
- Demo and example iOS apps (DemoApp, Examples, StreamChatSample, StreamChatUITestsApp).
- Integration scripts, CI/CD workflows, and tests.

##### High-Level Components
a. External Services
– Stream Chat REST API (HTTPS).
– Stream Chat WebSocket endpoint.
– CDN for attachments.
b. Core SDK Layers
1. APIClient
- HTTP client, WebSocket client, endpoints, encoders/decoders (Sources/StreamChat/APIClient & /WebSocketClient).
2. Controllers & State Layer
- ChatClient facade, Controllers (ChannelController, MessageController, etc.), Combine/SwiftUI bindings (Sources/StreamChat/Controllers & /StateLayer).
3. Repositories & Workers
- Data syncing, offline queue, background upload/download (Sources/StreamChat/Repositories & /Workers).
4. Database
- CoreData models, DTOs, DatabaseContainer, DataStore (Sources/StreamChat/Database).
5. Utilities
- Logging, pagination, markdown parsing, audio, image loading (Sources/StreamChat/Utils).
c. UI SDK (UIKit)
- Reusable chat UI components: channel list, message list, composer, attachments, reactions (Sources/StreamChatUI).
d. Demo & Examples
- DemoApp: an iOS application wiring ChatClient → Controllers → UI components.
- Examples: sample apps (MessengerClone, SlackClone, YouTubeClone, etc.).

##### Component Relationships and Data Flow
- ChatClient (configuration) → APIClient (HTTP/WS)
↳ WebSocket events → Event Middlewares → Controllers/StateLayer
↳ HTTP requests → Endpoint modules → Repositories → Database
- Controllers expose Combine publishers / SwiftUI bindings
↳ UI SDK components subscribe to controllers/state
- Workers pick up tasks (upload, sync) in the background and update Database/State
- DatabaseContainer persists local state; Controllers observe DB changes
- UI layer renders based on Controller outputs; user actions flow back to ChatClient

##### Architectural Patterns and Principles
- Layered architecture: Networking → Repository/Workers → Controllers/State → UI
- MVVM-ish or MVC: Controllers act as view-models for UI SDK
- Repository pattern: isolates data sources (network vs. cache)
- Observer pattern: DatabaseObserver for state updates
- Middleware pipeline: process WS events through EventMiddlewares
- Dependency injection via ChatClientConfig and factory methods

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        REST_API["Stream Chat REST API"]:::external
        WS_Endpoint["Stream Chat WebSocket"]:::external
        CDN["CDN for Attachments"]:::external
    end

    %% Core SDK Layers
    subgraph "Core SDK"
        direction TB
        ChatClient["ChatClient (Facade)"]:::state
        subgraph "Networking Layer"
            direction TB
            APIClient["APIClient (HTTP)"]:::networking
            WebSocketClient["WebSocketClient"]:::networking
            EventMiddlewares["EventMiddlewares"]:::networking
        end
        subgraph "Repositories & Workers"
            direction TB
            Repositories["Repositories"]:::data
            Workers["Workers"]:::data
        end
        subgraph "Database"
            direction TB
            DatabaseContainer["DatabaseContainer (CoreData)"]:::data
            DataStore["DataStore"]:::data
        end
        Controllers["Controllers & StateLayer"]:::state
        Utils["Utilities"]:::data
    end

    %% UI SDK
    UI["StreamChatUI Components"]:::ui

    %% Demo & Examples
    subgraph "Demo & Examples"
        direction TB
        DemoApp["DemoApp"]:::demo
        Examples["Examples"]:::demo
        MessengerClone["MessengerClone"]:::demo
        SlackClone["SlackClone"]:::demo
        YouTubeClone["YouTubeClone"]:::demo
        iMessageClone["iMessageClone"]:::demo
    end

    %% Integration & Scripts
    subgraph "Configuration & CI/CD"
        direction TB
        Scripts["Scripts"]:::demo
        CocoaPods["Integration/CocoaPods"]:::demo
        SPM["Integration/SPM"]:::demo
        PackageSwift["Package.swift"]:::demo
        PodspecChat["StreamChat.podspec"]:::demo
        PodspecUI["StreamChatUI.podspec"]:::demo
    end

    %% Testing
    TestMock["Test Mock Server"]:::external

    %% Data Flows
    ChatClient -->|"uses"| APIClient
    ChatClient -->|"uses WS"| WebSocketClient
    APIClient -->|"HTTP Requests"| REST_API
    WebSocketClient -->|"WS Events"| WS_Endpoint
    WS_Endpoint -->|->| EventMiddlewares
    EventMiddlewares -->|dashed| Controllers
    APIClient -->|"calls"| Repositories
    Repositories -->|"sync"| DatabaseContainer
    Workers -->|"background tasks"| DatabaseContainer
    DatabaseContainer -->|"observes"| Controllers
    Controllers -->|"publishes"| UI
    UI -.->|"user actions"| Controllers
    Controllers -.->|"invokes"| ChatClient
    Utils -->|supports| APIClient
    Utils -->|supports| Controllers

    %% Integration flows
    DemoApp -->|imports| ChatClient
    DemoApp -->|renders| UI
    Examples -->|samples| ChatClient
    Testscripts -->|CI kicks off| Scripts

    %% Click Events
    click ChatClient "https://github.com/getstream/stream-chat-swift/blob/develop/Sources/StreamChat/ChatClient.swift"
    click ChatClient "https://github.com/getstream/stream-chat-swift/blob/develop/Sources/StreamChat/ChatClientFactory.swift"
    click APIClient "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/APIClient"
    click WebSocketClient "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/WebSocketClient"
    click EventMiddlewares "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/WebSocketClient/EventMiddlewares"
    click Controllers "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/Controllers"
    click Controllers "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/StateLayer"
    click Repositories "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/Repositories"
    click Workers "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/Workers"
    click DatabaseContainer "https://github.com/getstream/stream-chat-swift/blob/develop/Sources/StreamChat/Database/DatabaseContainer.swift"
    click DataStore "https://github.com/getstream/stream-chat-swift/blob/develop/Sources/StreamChat/Database/DataStore.swift"
    click Utils "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/Utils"
    click Utils "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChat/Audio"
    click UI "https://github.com/getstream/stream-chat-swift/tree/develop/Sources/StreamChatUI"
    click DemoApp "https://github.com/getstream/stream-chat-swift/tree/develop/DemoApp/"
    click Examples "https://github.com/getstream/stream-chat-swift/tree/develop/Examples/EdgeCases"
    click MessengerClone "https://github.com/getstream/stream-chat-swift/tree/develop/Examples/MessengerClone"
    click SlackClone "https://github.com/getstream/stream-chat-swift/tree/develop/Examples/SlackClone"
    click YouTubeClone "https://github.com/getstream/stream-chat-swift/tree/develop/Examples/YouTubeClone"
    click iMessageClone "https://github.com/getstream/stream-chat-swift/tree/develop/Examples/iMessageClone"
    click Scripts "https://github.com/getstream/stream-chat-swift/tree/develop/Scripts/"
    click CocoaPods "https://github.com/getstream/stream-chat-swift/tree/develop/Integration/CocoaPods/"
    click SPM "https://github.com/getstream/stream-chat-swift/tree/develop/Integration/SPM/"
    click PackageSwift "https://github.com/getstream/stream-chat-swift/blob/develop/Package.swift"
    click PodspecChat "https://github.com/getstream/stream-chat-swift/blob/develop/StreamChat.podspec"
    click PodspecUI "https://github.com/getstream/stream-chat-swift/blob/develop/StreamChatUI.podspec"
    click TestMock "https://github.com/getstream/stream-chat-swift/tree/develop/TestTools/StreamChatTestMockServer"

    %% Styles
    classDef external fill:#D0E8FF,stroke:#0273B7,color:#000
    classDef networking fill:#FFDDA0,stroke:#E68A00,color:#000
    classDef data fill:#A0DFA0,stroke:#208000,color:#000
    classDef state fill:#E0A0E0,stroke:#A000A0,color:#000
    classDef ui fill:#A0DFDF,stroke:#009393,color:#000
    classDef demo fill:#D3D3D3,stroke:#888888,color:#000
```
