How onebusaway/onebusaway-ios works
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).