Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Trackurr is a modern iOS application designed for tracking recurring subscriptions and expenses. Built using Swift 5.9 and iOS 17+, it leverages the latest Apple technologies such as SwiftUI, SwiftData, and StoreKit 2. The project employs a modular architecture to ensure maintainability and testability through the use of Swift Packages and Dependency Injection via the Factory framework.
The project is structured to separate the main app target from self-contained feature modules and shared service packages. This modularity allows developers to work on isolated features like CategoriesFeature or TagsFeature while sharing a common Domain and Persistence layer.
Sources: README.md:15-31, CLAUDE.md:7-13
Development Environment Setup
To begin development on Trackurr, ensure your machine meets the minimum software requirements and that you follow the configuration steps for tooling and environment variables.
Prerequisites
- Xcode: Version 15.0 or later.
- Platform: iOS 17.0 or later.
- SwiftFormat: Required for maintaining code style; runs automatically during build phases.
Sources: README.md:81-85, CLAUDE.md:24-25
Installation Steps
- Clone the Repository:
git clone https://github.com/olbartek/trackurr-ios.git cd trackurr-ios - Install Tooling: Use Homebrew to install the necessary formatting tools.
brew install swiftformat - Configure Environment: The project uses a custom script to manage Firebase configuration files based on the bundle identifier.
- Open and Build: Open
Trackurr.xcodeprojand build (⌘R).
Sources: README.md:87-103, Scripts/copy-firebase-config.sh:1-44
Firebase Configuration Flow
The application requires a GoogleService-Info.plist file for analytics and crash reporting. The build process includes a script to copy the correct configuration file into the app bundle.
This diagram illustrates the automated script that ensures the environment-specific Firebase configuration is included in the build.
Sources: Scripts/copy-firebase-config.sh:1-44
Core Architecture
Trackurr follows a clear separation of concerns using a modular Swift Package-based structure.
Project Structure
| Layer | Description |
|---|---|
| Trackurr/ | Main application target and DI container setup. |
| Features/ | Self-contained UI modules (e.g., ExpensesFeature, SettingsFeature). |
| Packages/Domain | Pure business logic and entity definitions. |
| Packages/Services | Implementation of business services and external integrations. |
| Packages/Interfaces | Protocol definitions for services to enable mocking. |
| Persistence | SwiftData models, stores, and migration logic. |
Sources: README.md:65-79, CLAUDE.md:30-36
Persistence and Migrations
Data is managed via SwiftData with a versioned schema approach. The AppMigrationPlan handles transitions between schema versions, such as adding preferences or separating system entities for CloudKit compatibility.
The migration plan ensures data integrity across app updates, specifically handling the separation of system-seeded data from user-created data.
Sources: Trackurr/Dependencies/Persistence/Migration/AppMigrationPlan.swift:7-35
Development Workflow
Dependency Injection
Dependencies are managed using the Factory framework. This allows for compile-safe DI and easy swapping of real implementations for mocks during testing. New services should be registered in the centralized container in Trackurr/Dependencies/Container/.
Sources: CLAUDE.md:27-28, README.md:144-145
Debug Data Seeding
For testing purposes, the application provides a DataSeeder to populate the database with diverse sets of subscriptions and categories in debug builds.
| Seeding Set | Description |
|---|---|
.small | 15 fictional subscriptions. |
.large | 30 fictional subscriptions. |
.extraLarge | 50 subscriptions including stopped subs and varied dates. |
.live | 13 real-world subscription templates. |
Sources: README.md:162-179, TrackurrTests/Persistence/Seeding/DataSeederTests.swift:65-85
Common Commands
Frequent development tasks are handled via the command line or Xcode:
# Run tests on a specific simulator
xcodebuild -scheme Trackurr -destination 'platform=iOS Simulator,name=iPhone 15' test
# Build the project
xcodebuild -scheme Trackurr -destination 'platform=iOS Simulator,name=iPhone 15' build
# Upload to TestFlight (requires Fastlane)
bundle exec fastlane beta
Sources: CLAUDE.md:15-22
Testing Strategy
The project utilizes the Swift Testing framework (@Test). Tests are located near their respective modules (e.g., Features/TagsFeature/Tests/).
- Unit Tests: Focused on view models and service logic.
- Integration Tests: Focused on persistence stores and data flow.
- Mocks: Located in
Packages/Mocksto support isolated testing.
Sources: README.md:181-187, CLAUDE.md:46-48
Feature Logic Sequence
When a user interacts with a form (e.g., creating a category), the view model validates input before communicating with the store.
This sequence shows the standard interaction pattern found in the Features modules.
Conclusion
Setting up Trackurr involves configuring the Swift environment, ensuring proper tool installation like SwiftFormat, and understanding the modular dependency structure. By utilizing the provided debug seeding and following the Fastlane-supported release cycles, developers can efficiently contribute to the project while maintaining high code quality through automated testing and DI patterns.