# mastodon/mastodon-ios architecture

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

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

## Overview

##### Project type and purpose
- This is an official iOS client application for the Mastodon social network, written primarily in Swift for UIKit/SwiftUI, with supporting targets (Share Extension, Widget, Siri Intents, Notification Service).
- It bundles its own MastodonSDK module for networking, persistence, and UI components, plus localization tooling, CI/CD scripts, and Fastlane for App Store deployment.

##### File structure
- Top‐level targets:
- Mastodon (main app)
- MastodonSDK (reusable Swift Package for API, CoreData stack, UI modules)
- MastodonIntent (Siri Intents handler)
- NotificationService (APNS decryption service extension)
- OpenInActionExtension & ShareActionExtension (macOS/iOS share extensions)
- WidgetExtension (WidgetKit variants)
- Key modular directories under each target:
- Sources/CoreDataStack, CoreData models under MastodonSDK
- Sources/MastodonCore for networking/APIService modules
- Sources/MastodonUI for reusable SwiftUI/UICollectionView components
- Mastodon/Scene, /Coordinator, /Protocol, /Diffable for MVVM + Coordinator pattern in the main app
- Configuration, localization, build scripts, and CI definitions appear in .github/, fastlane/, Localization/, crowdin.yml, etc.

##### Leverage README insights
- Confirms it’s an open‐source iOS application for Mastodon, built with Swift and distributed via the App Store.
- Documentation folder describes setup, deployment, and high‐level architecture (see How-it-works.md).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users
    User["User Device"]:::external

    %% Main App
    subgraph "Mastodon iOS App" 
        direction TB
        App["App UI (UIKit/SwiftUI)"]:::app
        Scene["Scene Modules"]:::app
        Coordinator["Coordinator (Navigation)"]:::app
        Diffable["Diffable Data Sources"]:::app
        Provider["Provider Protocols & DI"]:::app
        ExtensionUtils["Extensions & Helpers"]:::app
        Helper["Utilities"]:::app
        App -->|taps| Scene
        Scene --> Coordinator
        Coordinator --> Provider
        Provider -->|inject| Diffable
        Provider -->|inject| ExtensionUtils
        ExtensionUtils --> Helper
    end

    %% ViewModels and Services
    VM["ViewModels (Combine)"]:::app
    Service["SDK APIService"]:::sdk
    Persistence["CoreDataStack"]:::sdk
    App --> VM
    VM --> Service
    Service -->|fetch| Persistence
    Persistence -->|publish| VM
    VM -->|update UI| App

    %% MastodonSDK Package
    subgraph "MastodonSDK (Swift Package)" 
        direction TB
        APIService["Networking & APIService"]:::sdk
        CoreData["CoreDataStack"]:::sdk
        SDKEntity["Core SDK Models & Entities"]:::sdk
        MastodonUI["Reusable UI Components"]:::sdk
        Package["Package.swift"]:::sdk
        APIService --> CoreData
        APIService --> SDKEntity
        SDKEntity --> MastodonUI
    end

    VM --> APIService

    %% Extensions
    subgraph "App Extensions" 
        direction TB
        IntentExt["Siri Intents"]:::app
        NotificationExt["Notification Service"]:::app
        ShareExt["Share Action"]:::app
        OpenInExt["Open-In Action"]:::app
        WidgetExtNode["WidgetKit Extension"]:::app
        IntentExt --> APIService
        NotificationExt --> APIService
        ShareExt --> APIService
        OpenInExt --> APIService
        WidgetExtNode --> APIService
    end

    %% Apple Frameworks
    subgraph "Apple Frameworks" 
        direction TB
        UIKit["UIKit"]:::framework
        SwiftUI["SwiftUI"]:::framework
        Combine["Combine"]:::framework
        CoreDataFW["CoreData"]:::framework
        WidgetKit["WidgetKit"]:::framework
        IntentsFW["Intents"]:::framework
    end
    App --> UIKit
    App --> SwiftUI
    VM --> Combine
    Persistence --> CoreDataFW
    WidgetExtNode --> WidgetKit
    IntentExt --> IntentsFW

    %% External Services
    MastodonAPI["Mastodon Servers\n(REST API)"]:::external
    APIService -->|HTTP| MastodonAPI

    %% CI/CD & Localization
    subgraph "CI/CD & Localization" 
        direction TB
        GitHub["GitHub Actions"]:::ci
        Fastlane["Fastlane"]:::ci
        Crowdin["Crowdin Sync"]:::ci
        SwiftGenNode["SwiftGen"]:::ci
        GitHub -->|build/test| App
        GitHub -->|sync| Crowdin
        Crowdin -->|generate| Localization
        SwiftGenNode -->|generate| App
        Fastlane -->|deploy| App
    end

    %% Click events
    click App "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/"
    click Scene "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/Scene/"
    click Coordinator "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/Coordinator/"
    click Diffable "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/Diffable/"
    click Provider "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/Protocol/Provider/"
    click ExtensionUtils "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/Extension/"
    click Helper "https://github.com/mastodon/mastodon-ios/tree/develop/Mastodon/Helper/"
    click CoreData "https://github.com/mastodon/mastodon-ios/tree/develop/MastodonSDK/Sources/CoreDataStack/"
    click APIService "https://github.com/mastodon/mastodon-ios/tree/develop/MastodonSDK/Sources/MastodonCore/Service/API/"
    click SDKEntity "https://github.com/mastodon/mastodon-ios/tree/develop/MastodonSDK/Sources/MastodonSDK/Entity/"
    click MastodonUI "https://github.com/mastodon/mastodon-ios/tree/develop/MastodonSDK/Sources/MastodonUI/"
    click Package "https://github.com/mastodon/mastodon-ios/blob/develop/MastodonSDK/Package.swift"
    click IntentExt "https://github.com/mastodon/mastodon-ios/tree/develop/MastodonIntent/"
    click NotificationExt "https://github.com/mastodon/mastodon-ios/tree/develop/NotificationService/"
    click ShareExt "https://github.com/mastodon/mastodon-ios/tree/develop/ShareActionExtension/"
    click OpenInExt "https://github.com/mastodon/mastodon-ios/tree/develop/OpenInActionExtension/"
    click WidgetExtNode "https://github.com/mastodon/mastodon-ios/tree/develop/WidgetExtension/"
    click Localization "https://github.com/mastodon/mastodon-ios/tree/develop/Localization/"
    click Crowdin "https://github.com/mastodon/mastodon-ios/blob/develop/crowdin.yml"
    click SwiftGenNode "https://github.com/mastodon/mastodon-ios/blob/develop/swiftgen.yml"
    click GitHub "https://github.com/mastodon/mastodon-ios/tree/develop/.github/"
    click Fastlane "https://github.com/mastodon/mastodon-ios/tree/develop/fastlane/"

    %% Styles
    classDef app fill:#cce5ff,stroke:#004085,color:#004085
    classDef sdk fill:#d4edda,stroke:#155724,color:#155724
    classDef framework fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24
    classDef ci fill:#e2e3e5,stroke:#383d41,color:#383d41
```
