# helpscout/beacon-ios-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/helpscout/beacon-ios-sdk
- Repository: https://github.com/helpscout/beacon-ios-sdk

## Overview

##### Project type and purpose
- This is not a standalone app but an iOS SDK: Beacon SDK (distributed as an XCFramework) that you embed in your iOS app to provide Help Scout’s knowledge-base browsing and chat/feedback functionality.
- The README confirms this: it describes installation via CocoaPods, Swift Package Manager, Carthage (deprecated), or manual integration. It also references two example apps (Objective-C and SwiftUI) that demonstrate usage.

##### File structure
- Top-level artifacts
- Beacon.xcframework: the compiled binary for multiple architectures (ios-arm64, ios-simulator, etc.), containing:
– Framework bundles with UI resources (storyboards and nibs)
– Public headers (Beacon.h, HSBeacon.h, constants, models)
– Private headers (HSBeacon* classes, API clients, view controllers, utilities)
- Package.swift, Beacon.podspec, Cartfile/Cartfile.resolved: build/distribution manifests
- Examples/…: two sample apps showing how your host app integrates the SDK
- docs/: auto-generated API reference for public classes, enums, protocols
- UI resources (storyboards, nibs, CSS/JS for web content)
- Public API surface (public headers & Swift module interfaces)
- Private implementation headers (network clients, coordinators, view controllers, utilities)
- Third-party dependencies embedded as private headers: Starscream (WebSockets), PusherSwift, Reachability, Gifu, FBShimmering

##### README for additional insights
- “Beacon functionality we have for the web inside your iOS app”
- Need to configure email attachments and push notifications (so there’s a network & push layer)
- Examples showcase delegate points and configuration in SettingsView.swift (SwiftUI example) and HSExampleViewController in Obj-C.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Apps
    subgraph "Host iOS App" 
        direction TB
        ObjC["Objective-C Example"]:::host
        SwiftUI["SwiftUI Example"]:::host
    end

    %% Distribution Manifests
    subgraph "Distribution Manifests"
        direction TB
        Podspec["Beacon.podspec"]:::manifest
        PackageSwift["Package.swift"]:::manifest
        Cartfile["Cartfile / Cartfile.resolved"]:::manifest
    end

    %% SDK Framework
    subgraph "Beacon SDK (Beacon.xcframework)" 
        direction TB
        %% Public API
        subgraph "Public API Layer"
            direction TB
            HSBeaconPublic["Public Headers & Swift Module"]:::publicAPI
        end

        %% Coordinator
        subgraph "Coordinator Layer"
            direction TB
            Coordinator["HSBeaconCoordinator"]:::coord
        end

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            BeaconUI["Beacon.storyboardc & NIBs"]:::ui
            ChatUI["BeaconMessaging.storyboardc"]:::ui
            PrevMsgUI["BeaconPreviousMessages.storyboardc"]:::ui
            CustomFields["BeaconAttachmentCell.nib, ContactFormField.nib, DatePicker.nib"]:::ui
        end

        %% Data Models
        subgraph "Data Models"
            direction TB
            Conversation["HSBeaconConversation"]:::network
            Transcript["HSBeaconChatTranscript"]:::network
            Suggestion["HSBeaconSuggestion"]:::network
        end

        %% Network Layer
        subgraph "Network Layer"
            direction TB
            BaseAPI["HSBeaconBaseAPIClient"]:::network
            ChatAPI["HSBeaconChatAPIClient"]:::network
            DocsAPI["HSBeaconDocsAPIClient"]:::network
            CloudFrontAPI["HSBeaconCloudFrontAPIClient"]:::network
        end

        %% Utility Layer
        subgraph "Utility Layer"
            direction TB
            Cache["HSBeaconExpiryCache"]:::utils
            Serialization["HSBeaconSerializationUtilities"]:::utils
            DataDetector["HSBeaconDataDetector"]:::utils
            Keychain["HSBeaconKeychainWrapper"]:::utils
            Reachability["Reachability"]:::utils
        end

        %% Third-party
        subgraph "Third-party Libs"
            direction TB
            Starscream["Starscream"]:::third
            Pusher["PusherSwift"]:::third
            GifuLib["Gifu"]:::third
            Shimmering["FBShimmering"]:::third
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HelpScoutAPI["Help Scout REST API"]:::external
        CloudFront["CloudFront Asset Hosting"]:::external
        PusherSvc["Pusher (WebSockets)"]:::external
        APNS["APNS"]:::external
    end

    %% Connections
    ObjC -->|"init & settings"| HSBeaconPublic
    SwiftUI -->|"init & settings"| HSBeaconPublic
    HSBeaconPublic -->|"routes calls"| Coordinator
    Coordinator -->|"presents"| BeaconUI
    Coordinator -->|"presents"| ChatUI
    Coordinator -->|"presents"| PrevMsgUI
    Coordinator -->|"presents"| CustomFields
    BeaconUI -->|"fetch data"| BaseAPI
    ChatUI -->|"fetch/send"| ChatAPI
    PrevMsgUI -->|"fetch history"| DocsAPI
    CustomFields -->|"upload attachments"| CloudFrontAPI
    BaseAPI -->|"HTTPS requests"| HelpScoutAPI
    ChatAPI -->|"WebSocket"| PusherSvc
    DocsAPI -->|"HTTPS requests"| HelpScoutAPI
    CloudFrontAPI -->|"HTTPS requests"| CloudFront
    PusherSvc -->|"push events"| APNS
    HelpScoutAPI -->|response| BaseAPI
    HelpScoutAPI -->|response| DocsAPI
    PusherSvc -->|messages| ChatAPI
    BaseAPI -->|data models| Conversation
    ChatAPI -->|data models| Transcript
    DocsAPI -->|data models| Suggestion
    BaseAPI -->|caching| Cache
    BaseAPI -->|serialization| Serialization
    ChatAPI -->|network check| Reachability
    PusherSvc -->|real-time| Starscream
    ChatAPI -->|real-time| Pusher
    BeaconUI -->|UI effects| GifuLib
    BeaconUI -->|UI effects| Shimmering

    %% Click events
    click ObjC "https://github.com/helpscout/beacon-ios-sdk/tree/main/Examples/Obj-C Example"
    click SwiftUI "https://github.com/helpscout/beacon-ios-sdk/tree/main/Examples/SwiftUI Example"
    click Podspec "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.podspec"
    click PackageSwift "https://github.com/helpscout/beacon-ios-sdk/blob/main/Package.swift"
    click Cartfile "https://github.com/helpscout/beacon-ios-sdk/blob/main/Cartfile / Cartfile.resolved"
    click HSBeaconPublic "https://github.com/helpscout/beacon-ios-sdk/tree/main/Beacon.xcframework/ios-arm64/Beacon.framework/Headers/"
    click Coordinator "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconCoordinator.h"
    click BeaconUI "https://github.com/helpscout/beacon-ios-sdk/tree/main/Beacon.xcframework/ios-arm64/Beacon.framework/Beacon.storyboardc/"
    click ChatUI "https://github.com/helpscout/beacon-ios-sdk/tree/main/Beacon.xcframework/ios-arm64/Beacon.framework/BeaconMessaging.storyboardc/"
    click PrevMsgUI "https://github.com/helpscout/beacon-ios-sdk/tree/main/Beacon.xcframework/ios-arm64/Beacon.framework/BeaconPreviousMessages.storyboardc/"
    click CustomFields "https://github.com/helpscout/beacon-ios-sdk/tree/main/Beacon.xcframework/ios-arm64/Beacon.framework/"
    click Conversation "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconConversation.h"
    click Transcript "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconChatTranscript.h"
    click Suggestion "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconSuggestion.h"
    click BaseAPI "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconBaseAPIClient.h"
    click ChatAPI "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconChatAPIClient.h"
    click DocsAPI "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconDocsAPIClient.h"
    click CloudFrontAPI "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconCloudFrontAPIClient.h"
    click Cache "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconExpiryCache.h"
    click Serialization "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconSerializationUtilities.h"
    click DataDetector "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconDataDetector.h"
    click Keychain "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/HSBeaconKeychainWrapper.h"
    click Reachability "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/Reachability.h"
    click Starscream "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/Starscream.h"
    click Pusher "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/PusherSwift.h"
    click GifuLib "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/Gifu.h"
    click Shimmering "https://github.com/helpscout/beacon-ios-sdk/blob/main/Beacon.xcframework/ios-arm64/Beacon.framework/PrivateHeaders/FBShimmering.h"
    click Docs "https://github.com/helpscout/beacon-ios-sdk/tree/main/docs/"

    %% Styles
    classDef host fill:#87cefa,stroke:#333,stroke-width:1px
    classDef manifest fill:#ffffe0,stroke:#333,stroke-width:1px
    classDef publicAPI fill:#add8e6,stroke:#333,stroke-width:1px
    classDef coord fill:#90ee90,stroke:#333,stroke-width:1px
    classDef ui fill:#ffa500,stroke:#333,stroke-width:1px
    classDef network fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef utils fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef third fill:#f4a460,stroke:#333,stroke-width:1px
    classDef external fill:#f08080,stroke:#333,stroke-width:1px
```
