Home

Trackurr is a modern iOS application designed for managing and tracking recurring subscriptions and expenses. Built using SwiftUI and SwiftData, it provides a native experience for monitoring billing cycles, category breakdowns, and spending insights. The application leverages a modular architecture, utilizing Swift Packages to separate domain logic, services, and UI features.

Sources: README.md:1-20, CLAUDE.md:8-12

Core Architecture

The project follows a modular architecture with a clear separation of concerns. It utilizes Factory for dependency injection, ensuring that services and stores are testable and decoupled from the UI. The persistence layer is powered by SwiftData, which handles local storage and integrates with CloudKit for private database synchronization.

Sources: README.md:43-52, CLAUDE.md:25-30

Project Structure

The repository is organized into distinct layers to maintain high cohesion and low coupling:

• App Target (Trackurr/): Contains the main entry point and global dependency configurations.
• Features (Features/): Self-contained modules (e.g., ExpensesFeature, CategoriesFeature) that encapsulate specific user workflows.
• Packages (Packages/): Shared logic including Domain models, Interfaces for services, and SharedUI for reusable components.

Sources: README.md:54-66, CLAUDE.md:8-12

Application Bootstrapping

The application entry point initializes the dependency injection container and persistence stack before launching the root view.

@main
struct TrackurrApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            DependenciesProvider {
                PersistenceProvider {
                    AppRootView()
                }
            }
        }
    }
}

Sources: Trackurr/TrackurrApp.swift:10-23

Persistence and Data Management

Trackurr uses a sophisticated persistence strategy involving schema migrations and data seeding to ensure a consistent experience across app updates.

Schema Migration Plan

The application implements a multi-stage migration plan (AppMigrationPlan) to handle schema evolutions across eight versions. These migrations include lightweight updates for new entities and custom stages for complex data transformations, such as separating system entities from CloudKit synchronization.

Sources: Trackurr/Dependencies/Persistence/Migration/AppMigrationPlan.swift:7-89

The diagram shows the sequential migration stages from the initial schema to the current version.
Sources: Trackurr/Dependencies/Persistence/Migration/AppMigrationPlan.swift:19-35

Data Seeding

Upon the first launch or after a reset, the DataSeeder populates the database with system-default categories and payment methods. This ensures the app is immediately usable.

Sources: TrackurrTests/Persistence/Seeding/DataSeederTests.swift:52-110

Key Features and Components

Subscription Tracking

The core of the application is the ability to track subscriptions with granular billing details. This includes support for various billing cycles (weekly, monthly, yearly, custom) and payment reminders via local notifications.

Sources: README.md:27-40, Features/ExpensesFeature/Sources/ExpensesFeature/Views/SubscriptionDetail/SubscriptionDetailView.swift:132-155

The sequence diagram illustrates the data flow when viewing subscription details, involving calculation of next renewal dates and spending analytics.
Sources: Features/ExpensesFeature/Sources/ExpensesFeature/Views/SubscriptionDetail/SubscriptionDetailView.swift:63-65, TrackurrTests/Persistence/Stores/SubscriptionStoreTests.swift:102-115

Dashboard and Insights

The app provides spending breakdowns and upcoming renewal schedules. It calculates:

• Monthly Equivalent: The normalized cost per month for subscriptions with different cycles.
• Yearly Total: Projected annual spending.
• Spending History: A timeline of past payments and expected future renewals.

Sources: Features/ExpensesFeature/Sources/ExpensesFeature/Views/SubscriptionDetail/SubscriptionDetailView.swift:175-220

Summary

Trackurr is architected to be a scalable and maintainable iOS application. By leveraging modern Swift technologies like SwiftData for persistence and a modular package-based structure, the project ensures clear separation between UI, business logic, and data layers. The inclusion of comprehensive migration plans and data seeding mechanisms further provides a robust foundation for long-term development and user data integrity.