# jakayus/straytoots architecture

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

- Interactive diagram: https://gitdiagram.com/jakayus/straytoots
- Repository: https://github.com/jakayus/straytoots

## Overview

- The companion iPhone app—for logging in, settings, and token setup.
- The Apple Watch app—for displaying user timelines and allowing simple interactions with “Toots” (such as Favourite, Boost, and Bookmark).

##### Main Components
a. Companions (Mobile Clients):
- iPhone App: Handles user authentication, token configuration (using the Tokens.plist) and initial login tasks.
- Apple Watch App: Provides the UI for viewing timelines and performing Toot interactions.
b. Shared Logic & Networking:
- MastodonNetworking.swift: Contains the logic for API calls to Mastodon.
- Config.swift: Likely provides configuration details such as the base URL of the Mastodon instance.
c. External Service:
- Mastodon API servers: The external API endpoints that this client communicates with for operations like verifying credentials and performing Toot actions.
d. Configuration Data:
- TokensExample.plist (and its renamed counterpart Tokens.plist): Stores access tokens and related secret information needed for authentication.

##### Relationships and Data Flow
- The iPhone app first handles authentication:
– It collects user credentials and uses the provided networking component to exchange the credentials for an access token.
- Once the token is configured (in Tokens.plist), both the iPhone and Watch apps can leverage it.
- The Watch app then uses MastodonNetworking.swift to fetch timelines and perform interactions (Favourite, Boost, Bookmark) using the Mastodon API.
- The configuration settings (potentially stored or referenced in Config.swift) determine the Mastodon instance that should be contacted.
- Data flows from the user (via the Watch or iPhone interface) to the networking layer, then to the Mastodon API, with responses updating the interface accordingly.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The design clearly separates user interface logic (in separate apps for iPhone and Watch) from networking/configuration logic (centralized in networking files).
- Modularity: The division of functionality into different files and app targets ensures that each part can be updated or improved independently.
- Dependency on External APIs: The system is built to interact with external services (Mastodon API), so error handling and response parsing are crucial parts of the networking module.

##### Relevant Technologies & Frameworks
- Swift and SwiftUI: For building the user interfaces on both iPhone and Watch.
- WatchKit: To support the Watch App.
- iOS frameworks for networking (likely URLSession or similar in MastodonNetworking.swift).
- Xcode project configuration (as seen in the .xcodeproj structure).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["Mobile User"]:::user

    %% Mobile Clients Subgraph
    subgraph "Mobile Clients"
        subgraph "iPhone App – Authentication/Settings"
            iPhoneApp["StrayTootsApp.swift"]:::appFile
            iPhoneContent["ContentView.swift"]:::appFile
            iPhoneAssets["Assets"]:::appFile
        end
        subgraph "Apple Watch App – Timeline/Toot Interactions"
            WatchApp["StrayTootsApp.swift"]:::appFile
            WatchContent["ContentView.swift"]:::appFile
        end
    end

    %% Shared Modules Subgraph
    subgraph "Shared Modules"
        Networking["MastodonNetworking Module"]:::networking
        Configuration["Configuration Module"]:::config
        Tokens["Tokens Data (Access Tokens)"]:::configData
    end

    %% External Service
    External["Mastodon API"]:::external

    %% Connections
    User -->|"launches"| iPhoneApp
    User -->|"launches"| WatchApp

    iPhoneApp -->|"sets-tokens"| Tokens
    iPhoneApp -->|"calls-API"| Networking
    WatchApp -->|"requests-data"| Networking

    Tokens -->|"supplies-token"| Networking
    Configuration -->|"provides-settings"| Networking

    Networking -->|"API-calls"| External
    External -->|"returns-data"| Networking

    %% Click Events
    click iPhoneApp "https://github.com/jakayus/straytoots/blob/main/StrayToots/StrayTootsApp.swift"
    click iPhoneContent "https://github.com/jakayus/straytoots/blob/main/StrayToots/ContentView.swift"
    click iPhoneAssets "https://github.com/jakayus/straytoots/blob/main/StrayToots/Assets.xcassets"
    click WatchApp "https://github.com/jakayus/straytoots/blob/main/StrayToots/StrayToots Watch App/StrayTootsApp.swift"
    click WatchContent "https://github.com/jakayus/straytoots/blob/main/StrayToots/StrayToots Watch App/ContentView.swift"
    click Networking "https://github.com/jakayus/straytoots/blob/main/StrayToots/MastodonNetworking.swift"
    click Configuration "https://github.com/jakayus/straytoots/blob/main/StrayToots/Config.swift"
    click Tokens "https://github.com/jakayus/straytoots/blob/main/TokensExample.plist"

    %% Styles
    classDef user fill:#f9c,stroke:#333,stroke-width:2px
    classDef appFrame fill:#bbf,stroke:#333,stroke-width:2px
    classDef appFile fill:#99d,stroke:#333,stroke-width:2px
    classDef networking fill:#cfc,stroke:#333,stroke-width:2px
    classDef config fill:#fcf,stroke:#333,stroke-width:2px
    classDef configData fill:#ffc,stroke:#333,stroke-width:2px
    classDef external fill:#fdd,stroke:#333,stroke-width:2px
```
