# dropbox/swiftydropbox architecture

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

- Interactive diagram: https://gitdiagram.com/dropbox/swiftydropbox
- Repository: https://github.com/dropbox/swiftydropbox

## Overview

##### Project type and purpose
- This is an SDK library (not a full‐stack app) providing:
- A Swift client for Dropbox HTTP API v2
- An Objective‐C compatibility layer
- Codegen pipeline (Stone + spec)
- Test harness (unit + integration)
- Multi‐platform support (iOS, macOS, extensions, SwiftUI)
- Distribution via SPM, CocoaPods

##### Break out the main components
a. Code Generation Pipeline
- Inputs: `spec/` + `stone/` + `generate_base_client.py`
- Outputs: `Source/SwiftyDropbox/Shared/Generated/*` and `Source/SwiftyDropboxObjC/Shared/Generated/*`
- Scripts: `update_repo_check.sh`, `update_version.sh`, `Format/generate_docs.sh`
b. Core SDK Modules
- Shared Core Logic:
- Generated models & routes
- Handwritten helpers (`NetworkSession`, `OAuth`, `Utilities`)
- `SDKConstants`, `CertificatePinning`, error handlers
- Platform Adapters:
- iOS UI for OAuth (`OAuthMobile`, `LoadingViewController`)
- macOS OAuth adapter (`OAuthDesktop`)
- Client Manager:
- `DropboxClientsManager` (single & multi‐user)
- `DropboxClient` & `DropboxTeamClient`
- `DropboxTransportClientImpl` (HTTP transport)
c. Objective-C Layer
- Mirror of Swift SDK under `SwiftyDropboxObjC/Platform` & `SwiftyDropboxObjC/Shared`
- Typed Objective‐C request classes, error types, clients
d. Network & OAuth Subsystem
- `NetworkSessionManager`, `NetworkSessionConfiguration`, `NetworkTask`
- `OAuthImpl`, `AccessTokenProvider`, `AuthSession`, PKCE support
- Background sessions / reconnection logic
e. Packaging & CI
- Build definitions: `Package.swift`, `.podspec` files
- Xcode workspaces under `.swiftpm` and `TestSwiftyDropbox`
- CI workflow: `.github/workflows/ci.yml`
- Doc generation: `.jazzy.json`, `Format/generate_docs.sh`
f. Tests
- Unit Tests under `SwiftyDropboxUnitTests` (mocking via `MockDropboxTransportClient`)
- Integration Tests under `TestSwiftyDropbox/IntegrationTests` (iOS + ObjC)
- Sample apps in `TestSwiftyDropbox` (iOS, macOS, SwiftUI, Action Extension)

##### Relationships & Data Flows
- Codegen → Generated code → Core Shared module
- Handwritten Shared helpers ↔ Generated code via request/response types
- Shared Core → Platform adapters (iOS/macOS) → UI components (for auth flows)
- Application code (test or consumer) → `DropboxClientsManager` → `DropboxClient` → `DropboxTransportClientImpl` → URLSession → Dropbox API
- Tests inject `MockDropboxTransportClient` into `DropboxClient` to simulate network responses
- Objective-C layer wraps/swizzles Swift types for ObjC consumers

##### Architectural patterns & principles
- Modularity: clear separation between codegen, core logic, platform adapters, network layer, tests
- Abstraction & DI: transport and OAuth are abstracted behind protocols; clients injected for testing
- Single Responsibility: each module has a distinct role (serialization vs networking vs UI)
- Code generation + manual code co-exist, minimizing handwritten boilerplate

##### Detail level & coverage
- Every major directory’s function (e.g., `Source/SwiftyDropbox/Shared/Handwritten`, `Source/SwiftyDropboxObjC/Platform`)
- Don’t worry about every single file—group by subfolder meaning (Generated vs Handwritten)
- OAuth flows (Direct, Safari, Redirect) are shown as alternate paths under Platform adapters
- Background networking reconnection logic under network/OAuth layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Code Generation Pipeline
    subgraph "Code Generation Pipeline"
        spec["spec/"]:::codegen
        stone["stone/"]:::codegen
        gbc["generate_base_client.py"]:::codegen
        urc["update_repo_check.sh"]:::codegen
        uvs["update_version.sh"]:::codegen
        gdocs["Format/generate_docs.sh"]:::codegen
    end

    %% Generated Code
    subgraph "Generated Models & Routes"
        genSwift["Swift Generated (Source/SwiftyDropbox/Shared/Generated/)"]:::generated
        genObjC["ObjC Generated (Source/SwiftyDropboxObjC/Shared/Generated/)"]:::generated
    end

    %% Handwritten Core SDK
    subgraph "Core SDK Shared Logic"
        core["Handwritten Core (Source/SwiftyDropbox/Shared/Handwritten/)"]:::core
    end

    %% Platform Adapters
    subgraph "Platform Adapters"
        iosPlat["iOS Adapter (OAuthMobile, LoadingViewController)"]:::platform
        macPlat["macOS Adapter (OAuthDesktop)"]:::platform
    end

    %% Objective-C Layer
    subgraph "Objective-C Layer"
        objcPlat["ObjC Platform Adapters"]:::objc
        objcCore["ObjC Shared Handwritten"]:::objc
    end

    %% Network & OAuth
    subgraph "Network & OAuth Subsystem"
        network["NetworkSessionManager & Config"]:::network
        oauth["OAuthImpl & AuthSession"]:::oauth
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        pkgSwift["Package.swift"]:::packaging
        pod1["SwiftyDropbox.podspec"]:::packaging
        pod2["SwiftyDropboxObjc.podspec"]:::packaging
        ci[".github/workflows/ci.yml"]:::packaging
        jazzy[".jazzy.json"]:::packaging
        spm[".swiftpm/"]:::packaging
    end

    %% Tests & Samples
    subgraph "Tests & Sample Apps"
        unit["Unit Tests (Source/SwiftyDropboxUnitTests/)"]:::tests
        intg["Integration Tests (TestSwiftyDropbox/IntegrationTests/)"]:::tests
        sampIOS["Sample iOS (TestSwiftyDropbox/TestSwiftyDropbox_iOS/)"]:::tests
        sampMac["Sample macOS (TestSwiftyDropbox/TestSwiftyDropbox_macOS/)"]:::tests
        sampUI["Sample SwiftUI (TestSwiftyDropbox/TestSwiftyDropbox_SwiftUI/)"]:::tests
        sampExt["Sample Action Extension (TestSwiftyDropbox/TestSwiftyDropbox_ActionExtension/)"]:::tests
    end

    %% External API
    DropboxAPI["Dropbox HTTP API v2"]:::external

    %% Connections
    spec --> genSwift
    stone --> genSwift
    gbc --> genSwift
    genSwift --> core
    genObjC --> objcCore
    core --> iosPlat
    core --> macPlat
    iosPlat --> oauth
    macPlat --> oauth
    core --> network
    oauth --> network
    network --> DropboxAPI
    iosPlat --> DropboxAPI
    macPlat --> DropboxAPI
    core --> pkgSwift
    objcCore --> pod2
    pkgSwift --> ci
    pod1 --> ci
    pod2 --> ci
    ci --> jazzy
    ci --> spm
    core --> unit
    network --> intg
    oauth --> intg
    iosPlat --> sampIOS
    macPlat --> sampMac
    iosPlat --> sampUI
    iosPlat --> sampExt

    %% Click Events
    click spec "https://github.com/dropbox/swiftydropbox/tree/master/spec/"
    click stone "https://github.com/dropbox/swiftydropbox/tree/master/stone/"
    click gbc "https://github.com/dropbox/swiftydropbox/blob/master/generate_base_client.py"
    click urc "https://github.com/dropbox/swiftydropbox/blob/master/update_repo_check.sh"
    click uvs "https://github.com/dropbox/swiftydropbox/blob/master/update_version.sh"
    click gdocs "https://github.com/dropbox/swiftydropbox/blob/master/Format/generate_docs.sh"
    click genSwift "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropbox/Shared/Generated/"
    click genObjC "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropboxObjC/Shared/Generated/"
    click core "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropbox/Shared/Handwritten/"
    click network "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropbox/Shared/Handwritten/NetworkSession/"
    click oauth "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropbox/Shared/Handwritten/OAuth/"
    click iosPlat "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropbox/Platform/SwiftyDropbox_iOS/"
    click macPlat "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropbox/Platform/SwiftyDropbox_macOS/"
    click objcPlat "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropboxObjC/Platform/SwiftyDropbox_iOS/"
    click objcCore "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropboxObjC/Shared/Handwritten/"
    click pkgSwift "https://github.com/dropbox/swiftydropbox/blob/master/Package.swift"
    click pod1 "https://github.com/dropbox/swiftydropbox/blob/master/SwiftyDropbox.podspec"
    click pod2 "https://github.com/dropbox/swiftydropbox/blob/master/SwiftyDropboxObjc.podspec"
    click ci "https://github.com/dropbox/swiftydropbox/blob/master/.github/workflows/ci.yml"
    click jazzy "https://github.com/dropbox/swiftydropbox/blob/master/.jazzy.json"
    click spm "https://github.com/dropbox/swiftydropbox/tree/master/.swiftpm/"
    click unit "https://github.com/dropbox/swiftydropbox/tree/master/Source/SwiftyDropboxUnitTests/"
    click intg "https://github.com/dropbox/swiftydropbox/tree/master/TestSwiftyDropbox/IntegrationTests/"
    click sampIOS "https://github.com/dropbox/swiftydropbox/tree/master/TestSwiftyDropbox/TestSwiftyDropbox_iOS/"
    click sampMac "https://github.com/dropbox/swiftydropbox/tree/master/TestSwiftyDropbox/TestSwiftyDropbox_macOS/"
    click sampUI "https://github.com/dropbox/swiftydropbox/tree/master/TestSwiftyDropbox/TestSwiftyDropbox_SwiftUI/"
    click sampExt "https://github.com/dropbox/swiftydropbox/tree/master/TestSwiftyDropbox/TestSwiftyDropbox_ActionExtension/"

    %% Styles
    classDef codegen fill:#cce5ff,stroke:#004085,color:#004085
    classDef generated fill:#b8daff,stroke:#004085,color:#004085
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef platform fill:#ffe5b4,stroke:#c67605,color:#c67605
    classDef objc fill:#ffe5b4,stroke:#c67605,color:#c67605
    classDef network fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef oauth fill:#d6d8db,stroke:#6c757d,color:#6c757d
    classDef packaging fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef tests fill:#f1f1f1,stroke:#6c757d,color:#6c757d
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
