# onebusaway/onebusaway-ios architecture

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

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

## Overview

##### Main Components
- Apps & Targets: Include the multiple iOS application projects such as CatalystTest, KiedyBus, MTA, OneBusAway, and the widget/extension projects (OBAWidget and TodayView). These represent the “front-end” or client side of the system.
- Framework Modules:
– OBAKit: This is the primary framework that encapsulates UI components, navigation, mapping, analytics, alerts, and transit-specific functionalities.
– OBAKitCore: Acts as the core backend layer for models, networking, data migration, and utility functions. It contains lower-level functionalities that support OBAKit.
- Shared Library/Components: The Apps/Shared directory contains shared code for analytics, common client logic, notifications, configuration, etc.
- Test Suites: There are comprehensive unit tests (OBAKitTests) and UI tests to validate behavior of both frameworks and apps.
- Third-Party Libraries: The project includes several integrated third-party modules (AwesomeSpotlight, Polyline, ProgressHUD, Visual Effects Shadow, etc.) which can be depicted as external dependencies.

##### Relationships and Interactions
- Each iOS application project (found under Apps) uses the OBAKit framework and may depend on OBAKitCore for lower-level features.
- The framework modules interact with shared components: for example, analytics and push notifications are found in “Apps/Shared” and referenced by the apps and frameworks.
- External scripts (in the scripts directory) operate as auxiliary build or maintenance procedures (e.g., generating docs, running swiftlint, updating package dependencies, or regenerating protobuf models).
- Third-party integrations are embedded within the core frameworks—indicate them as external dependencies that get linked within the modules.

##### Architectural Patterns and Design Principles
- Modular Design: The clear separation into frameworks (OBAKit and OBAKitCore) promotes reusability and easier white-label customization.
- White-Label Setup: The structure of having multiple app targets using the same underlying frameworks demonstrates an architectural pattern that emphasizes customization without code forking.
- MVC/MVVM Elements: Many UI components (view controllers, view models) in OBAKit follow design patterns common in iOS (for example, the mapping, alerts, and onboarding flows).
- Testability: Comprehensive unit and UI test directories indicate a design that values loosely coupled components and test-driven development.

##### Relevant Technologies and Tools
- Swift and Objective-C interoperability – small Objective-C files exist for compatibility.
- XcodeGen for project file generation.
- Swift Package Manager for managing third-party dependencies.
- Jazzy and Sourcekitten for automatically generating documentation.
- Transifex (via the tx client) for localization.

- Nodes/Components with clear labels: “iOS App – KiedyBus”, “iOS App – MTA”, “OBAKit Framework”, “OBAKitCore Framework”, “Shared Analytics & Notifications”, “Third-Party Libraries”, “Test Suites”, and “Build/Dev Tools”.
- It’s a good idea to add a separate layer (or boundary) for external services (like localization with Transifex) and a build pipeline area (CI/CD via GitHub Actions using the .github/workflows folder).
- Lastly, annotate each component with key technologies (Swift, XcodeGen, Swift Package Manager) and note any architectural pattern (such as MVC/MVVM within the UI components).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% iOS Apps
    subgraph "iOS Apps"
        appCatalyst["iOS App – CatalystTest"]:::app
        appKiedy["iOS App – KiedyBus"]:::app
        appMTA["iOS App – MTA"]:::app
        appOneBus["iOS App – OneBusAway"]:::app
    end

    %% Widgets & Extensions
    subgraph "Widgets & Extensions"
        widgetOBA["iOS Widget – OBAWidget"]:::app
        extensionToday["iOS Today Extension – TodayView"]:::app
    end

    %% Frameworks
    subgraph "Frameworks"
        frameworkOBAKit["OBAKit Framework"]:::framework
        frameworkOBAKitCore["OBAKitCore Framework"]:::framework
    end

    %% Shared Components
    subgraph "Shared Components"
        sharedAN["Shared Analytics & Notifications"]:::shared
    end

    %% Test Suites
    subgraph "Test Suites"
        testOBAKit["OBAKitTests"]:::test
        testOBAKitUI["OBAKitUITests"]:::test
    end

    %% Build/Dev Tools
    subgraph "Build/Dev Tools"
        devTools["Build/Dev Tools"]:::dev
    end

    %% External Dependencies & Build Config
    subgraph "External Dependencies & Build Config"
        externalDep["External Dependencies & Build Config"]:::external
    end

    %% Relationships: Apps and Extensions use OBAKit Framework
    appCatalyst -->|"uses"| frameworkOBAKit
    appKiedy -->|"uses"| frameworkOBAKit
    appMTA -->|"uses"| frameworkOBAKit
    appOneBus -->|"uses"| frameworkOBAKit
    widgetOBA -->|"uses"| frameworkOBAKit
    extensionToday -->|"uses"| frameworkOBAKit

    %% Relationships: OBAKit depends on OBAKitCore and Shared Components
    frameworkOBAKit -->|"dependsOn"| frameworkOBAKitCore
    frameworkOBAKit -->|"integrates"| sharedAN

    %% Relationships: Build/Dev Tools support Frameworks
    devTools -->|"supports"| frameworkOBAKit
    devTools -->|"supports"| frameworkOBAKitCore

    %% Relationships: External Dependencies feed into Build Tools
    externalDep -->|"configures"| devTools

    %% Relationships: Test Suites target the Frameworks
    testOBAKit -->|"tests"| frameworkOBAKit
    testOBAKitUI -->|"tests"| frameworkOBAKitCore

    %% Styles
    classDef app fill:#e0f7fa,stroke:#333,stroke-width:2px;
    classDef framework fill:#fff9c4,stroke:#333,stroke-width:2px;
    classDef shared fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef test fill:#ffcdd2,stroke:#333,stroke-width:2px;
    classDef dev fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef external fill:#b2ebf2,stroke:#333,stroke-width:2px;

    %% Click Events
    click appCatalyst "https://github.com/onebusaway/onebusaway-ios/tree/main/Apps/CatalystTest"
    click appKiedy "https://github.com/onebusaway/onebusaway-ios/tree/main/Apps/KiedyBus"
    click appMTA "https://github.com/onebusaway/onebusaway-ios/tree/main/Apps/MTA"
    click appOneBus "https://github.com/onebusaway/onebusaway-ios/tree/main/Apps/OneBusAway"
    click widgetOBA "https://github.com/onebusaway/onebusaway-ios/tree/main/OBAWidget"
    click extensionToday "https://github.com/onebusaway/onebusaway-ios/tree/main/TodayView"
    click frameworkOBAKit "https://github.com/onebusaway/onebusaway-ios/tree/main/OBAKit"
    click frameworkOBAKitCore "https://github.com/onebusaway/onebusaway-ios/tree/main/OBAKitCore"
    click sharedAN "https://github.com/onebusaway/onebusaway-ios/tree/main/Apps/Shared"
    click testOBAKit "https://github.com/onebusaway/onebusaway-ios/tree/main/OBAKitTests"
    click testOBAKitUI "https://github.com/onebusaway/onebusaway-ios/tree/main/OBAKitUITests"
    click devTools "https://github.com/onebusaway/onebusaway-ios/tree/main/scripts"
    click externalDep "https://github.com/onebusaway/onebusaway-ios/tree/main/.github/workflows"
```
