# posthog/posthog-ios architecture

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

- Interactive diagram: https://gitdiagram.com/posthog/posthog-ios
- Repository: https://github.com/posthog/posthog-ios

## Overview

Based on our analysis of the file tree and README, PostHog iOS is an analytics SDK designed for iOS (with additional examples for macOS, tvOS, watchOS, and even Objective-C integrations). Its purpose is to provide comprehensive event tracking (including autocapture, screen views, session replay, and other telemetry) and the efficient uploading of analytics data to the PostHog backend.

##### Main components
- Core SDK Modules – These are the libraries that are included in the “PostHog” directory. They include modules such as:
– Application Lifecycle Tracking (e.g., ApplicationLifecyclePublisher.swift and PostHogAppLifeCycleIntegration.swift)
– Autocapture functionality (files in the Autocapture subfolder and SwiftUI/UIView extensions)
– Replay and Screen Views (in PostHog/Replay and PostHog/Screen Views)
– Core API and event batching (files like PostHogApi.swift, PostHogQueue.swift, PostHogFileBackedQueue.swift, and PostHogBatchUploadInfo.swift)
– Configuration and storage management (e.g., PostHogConfig.swift, PostHogStorage.swift, PostHogStorageManager.swift)
- Integration Layers – This includes the modules/tools for integrating with varied application types:
– SwiftUI integrations (PostHog/SwiftUI folder and various view modifiers)
– Objective-C examples (PostHogObjCExample)
– Multiple example apps provided (such as PostHogExample, PostHogExampleAutocapture, PostHogExampleExternalSDK, etc.) to show different integration scenarios and usage patterns.
- Utility Classes – Helpers and internal utilities that facilitate data compression, error handling, logging, and network session management (files in PostHog/Utils).

##### Relationships and interactions
- The SDK initializes as part of the host app’s startup. From AppDelegate or SceneDelegate, initialization routines wire up the SDK configuration and dependency injection (see DI.swift).
- As user interactions occur, various integration modules (for autocapture, screen views, etc.) record events. These are processed in the SDK and queued.
- A batching and network layer (often utilizing queues and file-backed storage) collects and then periodically uploads events to the PostHog backend.
- The lifecycle, replay, and UI-triggered events connect with the event processor modules. For example, a “Replay” module intercepts events and view snapshots, while autocapture modules hook into UI components.
- Unit tests (under PostHogTests) verify the behavior among these components, ensuring the reliability of interactions.

##### Architectural patterns and design principles
- Modular design: The SDK splits functionality into discrete modules (e.g., Autocapture, Replay, Screen Views) that communicate with a central event queuing and network subsystem.
- Dependency Injection: Configuration elements are managed via DI.swift, allowing the SDK to be flexible and testable.
- Separation of concerns: Each component (event capture, storage, and networking) is isolated, making it easier to extend or replace parts of the system.
- Example-driven integration: Multiple “example” projects cater to different use cases (SPM, CocoaPods, Objective-C) which demonstrate isolation and encapsulation of the SDK.

##### Relevant technologies and frameworks
- Swift and Objective-C interop (shown by the presence of Swift code and ObjC examples).
- Use of Xcode (configured projects and schemes inside PostHog.xcodeproj), and support for Swift Package Manager and CocoaPods (as indicated by Package.swift and the podspec).
- Unit testing frameworks and CI configured via GitHub Actions (inside .github/workflows).

##### Instructing the principal software engineer
- Expand into internal components, grouping them by functionality (e.g., event capture, processing, storage, transport, and integration examples).
- Use annotations to point out where dependency injection, modularity, and error handling strategies are implemented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["iOS Host App (AppDelegate/SceneDelegate)"]:::external
    Init["Initialization & Configuration (DI.swift)"]:::init
    A -->|"Initialize"| Init

    subgraph "Core SDK Modules"
        subgraph "Event Capture Modules"
            Lifecycle1["ApplicationLifecyclePublisher"]:::core
            Lifecycle2["PostHogAppLifeCycleIntegration"]:::core
            Autocapture["Autocapture Functionality"]:::core
            Replay["Replay Module"]:::core
            ScreenViews["Screen Views Module"]:::core
        end
        ConfigStore["Configuration & Storage Management"]:::core
        Processing["API & Event Batching"]:::core
    end

    NET["Network Upload"]:::core

    subgraph "Integration Layers"
        SwiftUIIntegration["SwiftUI Integration"]:::integration
        ObjCExample["Objective-C Example"]:::integration
        ExampleApps["Example Applications"]:::integration
    end

    Utility["Utility Classes"]:::utility

    Init -->|"Configure"| Lifecycle1
    Init -->|"Configure"| Lifecycle2
    Init -->|"Configure"| Autocapture
    Init -->|"Configure"| Replay
    Init -->|"Configure"| ScreenViews
    Init -->|"Configure"| ConfigStore
    Init -->|"DependencyInjection"| Processing

    Lifecycle1 -->|"EventData"| Processing
    Lifecycle2 -->|"EventData"| Processing
    Autocapture -->|"EventData"| Processing
    Replay -->|"EventData"| Processing
    ScreenViews -->|"EventData"| Processing
    ConfigStore -->|"StorageConfig"| Processing

    Processing -->|"BatchEvents"| NET

    SwiftUIIntegration -->|"EmbedSDK"| Init
    ObjCExample -->|"EmbedSDK"| Init
    ExampleApps -->|"EmbedSDK"| Init

    Utility -->|"Support"| Processing

    click Lifecycle1 "https://github.com/posthog/posthog-ios/blob/main/PostHog/App Life Cycle/ApplicationLifecyclePublisher.swift"
    click Lifecycle2 "https://github.com/posthog/posthog-ios/blob/main/PostHog/App Life Cycle/PostHogAppLifeCycleIntegration.swift"
    click Autocapture "https://github.com/posthog/posthog-ios/tree/main/PostHog/Autocapture"
    click Replay "https://github.com/posthog/posthog-ios/tree/main/PostHog/Replay"
    click ScreenViews "https://github.com/posthog/posthog-ios/tree/main/PostHog/Screen Views"
    click Processing "https://github.com/posthog/posthog-ios/blob/main/PostHog/PostHogApi.swift"
    click ConfigStore "https://github.com/posthog/posthog-ios/blob/main/PostHog/PostHogConfig.swift"
    click SwiftUIIntegration "https://github.com/posthog/posthog-ios/tree/main/PostHog/SwiftUI"
    click ObjCExample "https://github.com/posthog/posthog-ios/tree/main/PostHogObjCExample"
    click ExampleApps "https://github.com/posthog/posthog-ios/tree/main/PostHogExample"
    click Utility "https://github.com/posthog/posthog-ios/tree/main/PostHog/Utils"

    classDef external fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef init fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef core fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef integration fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef utility fill:#f5cba7,stroke:#333,stroke-width:2px;
```
