F1Stats

A native Android application for Formula 1 enthusiasts — browse race calendars, driver and team standings, circuit information, and save your favourite races for quick access.

Built with modern Android development practices: multi-module Clean Architecture, Jetpack Compose, Kotlin Coroutines & Flows, Koin, Room, and Compose Navigation.

Calendar	Standings	Circuits

Race Result	Driver Detail	Favourites

• Race Calendar — Full season schedule with countdown to the next GP, race details and session breakdowns
• Driver & Team Standings — Live rankings updated from the API-Sports F1 API
• Race Results — Detailed finishing order with times, fastest laps and team info
• Circuit Browser — Explore every circuit on the calendar with lap records and location data
• Favourites — Save races locally with Room; list updates reactively via Kotlin Flow
• Season Selector — Switch between historical seasons from Settings
• Dark Mode — Full dark theme support with system, light and dark options
• Background Music — Toggle the F1 theme from Settings
• Accessibility — Semantic headings, button roles, content descriptions and minimum touch targets

The project is split into four Gradle modules with strict dependency boundaries:

:app          Thin application shell — MainActivity, Koin DI modules
  :ui         Compose screens, ViewModels, theme, navigation graph, resources
    :data     Repositories, Retrofit services, Room database, DTO mappers
      :domain Pure Kotlin library — domain models, repository interfaces, use cases

Dependency flow: :app -> :ui -> :data -> :domain

Each module has a clear responsibility:

Repository interfaces live in :domain, keeping use cases and models free of any framework dependency:

:domain                          :data
  CircuitRepository (interface) <-- CircuitRepository (class implements interface)
  GetCircuitsUseCase(repo)          RetrofitService, DTOs, Mappers

Koin binds concrete implementations to their interfaces in :app:

single<ICircuitRepository> { CircuitRepository(get(), get()) }

Compose Screen -> ViewModel -> UseCase -> Repository Interface -> Retrofit / Room
                  StateFlow    suspend     concrete impl           Network / DB

1. Screen observes StateFlow from the ViewModel via collectAsStateWithLifecycle()
2. ViewModel calls a use case on viewModelScope and updates state
3. UseCase delegates to a repository interface defined in :domain
4. Repository (in :data) calls Retrofit for network data or Room for local data
5. Mappers translate network DTOs into domain models before returning

ViewModels expose a single StateFlow per observable piece of state. The UI layer collects these flows with lifecycle awareness, ensuring no unnecessary recompositions or leaked subscriptions.

Network responses are deserialized into data-layer DTOs via Gson. Mapper classes in data/mapper/ convert these into clean domain models, isolating the domain layer from API contract changes.

Key architectural decisions are documented as ADRs in docs/adr/. Highlights include:

Release builds use R8 for code shrinking, resource shrinking and obfuscation:

• :app — minifyEnabled true, shrinkResources true with project-level ProGuard rules
• :data — Consumer ProGuard rules (consumer-rules.pro) that travel with the library, preserving Gson-serialized models, Retrofit service interfaces and Room entities

The app follows core Android accessibility guidelines:

• Semantic headings — Section titles use semantics { heading() } for screen reader navigation
• Button roles — Interactive cards declare Role.Button for correct TalkBack announcements
• Content descriptions — All icons and images provide meaningful descriptions via contentDescription
• State descriptions — Toggle elements (favourite buttons) announce their current state
• Touch targets — Interactive icons wrapped in IconButton to guarantee 48dp minimum touch area

The project includes a comprehensive test suite with 142 unit tests and 10 integration tests across all four modules:

Integration tests (instrumented, requires device/emulator):

• RaceDaoTest (10 tests) — Room DAO operations: insert, retrieve, delete, conflict resolution, Flow reactivity

• MockK — Mocking framework for Kotlin (coroutine-aware coEvery/coVerify)
• Turbine — Flow testing library for asserting emissions
• kotlinx-coroutines-test — runTest, TestDispatcher, advanceUntilIdle for coroutine testing
• Koin Test — DI module verification without Android context
• Room Testing — In-memory database for DAO integration tests

./gradlew test                          # All unit tests (all modules)
./gradlew :domain:test                  # Domain layer only
./gradlew :data:test                    # Data layer only
./gradlew :ui:test                      # UI layer (ViewModels) only
./gradlew :app:test                     # DI integration tests
./gradlew :data:connectedAndroidTest    # Room DAO tests (requires device)

• Android Studio Ladybug or later
• JDK 17+
• An API key from API-Sports (free tier available)

1. Clone the repository:

   git clone https://github.com/davmm96/F1Stats.git
   cd F1Stats

2. Add your API key — the key is configured as a BuildConfig field in app/build.gradle.

3. Build and run:

   ./gradlew assembleDebug

   Or open the project in Android Studio and run on a device or emulator.

./gradlew build                  # Full build
./gradlew assembleDebug          # Debug APK
./gradlew assembleRelease        # Release APK (R8 enabled)
./gradlew test                   # Unit tests
./gradlew clean                  # Clean build artifacts

This project is licensed under the MIT License. See the LICENSE file for details.