# massamagro/f1-trivia2 architecture

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

- Interactive diagram: https://gitdiagram.com/massamagro/f1-trivia2
- Repository: https://github.com/massamagro/f1-trivia2

## Overview

##### Project type and purpose
- This is an Android mobile application implementing a trivia-style game about Formula 1.
- It follows a layered architecture (MVVM + Repository pattern), pulls data from external REST APIs (F1 data and Wikipedia), transforms and caches it locally, and presents quizzes to the user with a leaderboard.

##### File structure
- Top-level module “app” (Android application with Gradle Kotlin DSL).
- Under app/src/main/java/com/vozmediano/f1trivia:
- data layer:
– network/api: Retrofit service interfaces (F1Service, WikiService)
– network/model: DTOs for API responses
– local: Room database (Database classes, DAOs, Entities, Converters)
– repository implementations that coordinate network ↔ local ↔ domain mapping
- domain layer:
– Repository interfaces (F1CircuitRepository, WikiRepository, etc.)
– Domain models (Quiz model and F1 data models)
– Use-case classes encapsulating business rules (e.g. WhoWonAtCircuitAndSeasonUseCase)
- ui layer:
– Activities and ViewModels organized by feature (login, main menu, game, leaderboard, settings)
– Adapters (ScoreboardAdapter)
– Theme and utility classes
- Tests: androidTest and unit test directories

##### README
- Confirms: trivia game, automatic question generation based on rules, uses open F1 API, leaderboard tracks consecutive correct answers.

##### Main components
a. UI layer
- Activities & Fragments
- ViewModels
b. Domain layer
- Use Cases
- Domain Models
- Repository Interfaces
c. Data layer
- Repository Implementations
- Network Module (Retrofit + DTOs)
- Local Module (Room DB, DAOs, Entities, Converters)
d. External services
- Ergast F1 API (or other free F1 data API)
- Wikipedia API
e. Android system
- Application class (F1TriviaApplication)
- Jetpack components (LiveData / Coroutine scope)

##### Relationships and data flows
- UI → ViewModel (user actions & state observations)
- ViewModel → Use Cases (invoke business logic)
- Use Cases → Repository Interface (abstract data access)
- Repository Impl → Network & Local modules
- Check local cache via DAOs
- Fetch fresh data via Retrofit services if needed
- DTOs ↔ Entities ↔ Domain models using Mappers
- Persist Entities in Room database
- External APIs ↔ Repository Impl
- Data flows back up to UI via LiveData or StateFlow

##### Architectural patterns & design principles
- MVVM (Separation of concerns, testable ViewModel)
- Repository pattern (abstract data sources)
- Use-case driven domain layer (single responsibility, clear business rules)
- Layered architecture (Presentation → Domain → Data)
- Network caching strategy with Room and Retrofit

##### Detailed elements
- Application startup: F1TriviaApplication initializes DI (if any)
- Repository implementations coordinating Room DAOs and Retrofit services
- Use cases representing each trivia rule/query
- UI screens (Activities) per feature: Login, Main Menu, Game, Leaderboard, Settings
- Data transformation via mappers
- Caching strategy (query local first, then API)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application System
    subgraph "Android System"
        App["F1TriviaApplication"]:::system
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        LA["LoginActivity"]:::presentation
        UA["UsernameActivity"]:::presentation
        CA["ChangeUsernameActivity"]:::presentation
        MMA["MainMenuActivity"]:::presentation
        GA["GameActivity"]:::presentation
        GVM["GameViewModel"]:::presentation
        LBA["LeaderboardActivity"]:::presentation
        SA["ScoreboardAdapter"]:::presentation
        SGA["SettingsActivity"]:::presentation
        SVM["SettingsViewModel"]:::presentation
        THEME["Color, Theme & Type"]:::presentation
        UTIL1["ScoreExtensions"]:::presentation
        UTIL2["StringExtensions"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        subgraph "Use Cases"
            direction TB
            UC1["WhoWonAtCircuitAndSeasonUseCase"]:::domain
            UC2["MostWinsByCircuitUseCase"]:::domain
            UC3["MostPodiumsByCircuitUseCase"]:::domain
            UC4["DriverByNationalityUseCase"]:::domain
        end
        subgraph "Repository Interfaces"
            direction TB
            RI1["F1CircuitRepository"]:::domain
            RI2["F1ConstructorRepository"]:::domain
            RI3["F1DriverRepository"]:::domain
            RI4["F1RaceRepository"]:::domain
            RI5["F1ResultRepository"]:::domain
            RI6["WikiRepository"]:::domain
        end
        DM["Domain Models"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        subgraph "Repository Implementations"
            direction TB
            RIM1["F1CircuitRepositoryImpl"]:::data
            RIM2["F1ConstructorRepositoryImpl"]:::data
            RIM3["F1DriverRepositoryImpl"]:::data
            RIM4["F1RaceRepositoryImpl"]:::data
            RIM5["F1ResultRepositoryImpl"]:::data
            RIM6["WikiRepositoryImpl"]:::data
        end
        subgraph "Network Module"
            direction TB
            S1["F1Service"]:::data
            S2["WikiService"]:::data
            DTO["DTOs & Response Models"]:::data
        end
        subgraph "Local Module"
            direction TB
            DB1["F1Database"]:::data
            DB2["WikiDatabase"]:::data
            DAO["DAOs"]:::data
            ENT["Entities"]:::data
            CONV["Converters"]:::data
        end
        MAPPERS["Mappers"]:::data
    end

    %% External Services
    subgraph "External Services"
        F1API["Ergast F1 API"]:::external
        WIKIAPI["Wikipedia API"]:::external
    end

    %% Connections
    App -->|init| LA
    LA -->|opens| UA
    UA -->|opens| CA
    CA -->|navigates| MMA
    MMA -->|start game| GA
    GA -->|binds| GVM
    GAMBL:GVM -->|calls| UC1
    GVM -->|calls| UC2
    GVM -->|calls| UC3
    GVM -->|calls| UC4
    UC1 -->|depends on| RI1
    UC2 -->|depends on| RI1
    UC3 -->|depends on| RI1
    UC4 -->|depends on| RI3
    RI1 -->|implemented by| RIM1
    RI2 -->|implemented by| RIM2
    RI3 -->|implemented by| RIM3
    RI4 -->|implemented by| RIM4
    RI5 -->|implemented by| RIM5
    RI6 -->|implemented by| RIM6
    RIM1 -->|uses| S1
    RIM6 -->|uses| S2
    S1 -->|fetches| F1API
    S2 -->|fetches| WIKIAPI
    RIM1 -->|queries| DB1
    RIM6 -->|queries| DB2
    DB1 -->|via| DAO
    DB2 -->|via| DAO
    ENTITYFLOW[/"DTO → Entity → Domain"/]:::annotation
    DTO -->|map| ENT
    ENT -->|map| DM
    ENT -->|persist| DB1
    ENT -->|persist| DB2
    LBA -->|uses| SA
    SGA -->|binds| SVM
    THEME -->|applies| LA
    UTIL1 -->|extends| GVM
    UTIL2 -->|extends| GVM

    %% Click Events
    click LA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/login/LoginActivity.kt"
    click UA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/login/UsernameActivity.kt"
    click CA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/login/ChangeUsernameActivity.kt"
    click MMA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/mainmenu/MainMenuActivity.kt"
    click GA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/game/GameActivity.kt"
    click GVM "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/game/GameViewModel.kt"
    click LBA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/leaderboard/LeaderboardActivity.kt"
    click SA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/leaderboard/ScoreboardAdapter.kt"
    click SGA "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/settings/SettingsActivity.kt"
    click SVM "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/settings/SettingsViewModel.kt"
    click THEME "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/theme/Color.kt"
    click THEME "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/theme/Theme.kt"
    click THEME "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/ui/theme/Type.kt"
    click UTIL1 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/util/ScoreExtensions.kt"
    click UTIL2 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/util/StringExtensions.kt"
    click RI1 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/F1CircuitRepository.kt"
    click RI2 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/F1ConstructorRepository.kt"
    click RI3 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/F1DriverRepository.kt"
    click RI4 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/F1RaceRepository.kt"
    click RI5 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/F1ResultRepository.kt"
    click RI6 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/WikiRepository.kt"
    click UC1 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/model/usecase/WhoWonAtCircuitAndSeasonUseCase.kt"
    click UC2 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/model/usecase/MostWinsByCircuitUseCase.kt"
    click UC3 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/model/usecase/MostPodiumsByCircuitUseCase.kt"
    click UC4 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/domain/model/usecase/DriverByNationalityUseCase.kt"
    click RIM1 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/F1CircuitRepositoryImpl.kt"
    click RIM2 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/F1ConstructorRepositoryImpl.kt"
    click RIM3 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/F1DriverRepositoryImpl.kt"
    click RIM4 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/F1RaceRepositoryImpl.kt"
    click RIM5 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/F1ResultRepositoryImpl.kt"
    click RIM6 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/WikiRepositoryImpl.kt"
    click S1 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/network/api/F1Service.kt"
    click S2 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/network/api/WikiService.kt"
    click DB1 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/local/F1Database.kt"
    click DB2 "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/local/WikiDatabase.kt"
    click DAO "https://github.com/massamagro/f1-trivia2/tree/master/app/src/main/java/com/vozmediano/f1trivia/data/local/dao/"
    click ENT "https://github.com/massamagro/f1-trivia2/tree/master/app/src/main/java/com/vozmediano/f1trivia/data/local/entities/"
    click CONV "https://github.com/massamagro/f1-trivia2/blob/master/app/src/main/java/com/vozmediano/f1trivia/data/local/Converters.kt"
    click MAPPERS "https://github.com/massamagro/f1-trivia2/tree/master/app/src/main/java/com/vozmediano/f1trivia/data/mappers/"

    %% Styles
    classDef presentation fill:#blue,stroke:#333,color:#fff
    classDef domain fill:#0f0,stroke:#333,color:#000
    classDef data fill:#f90,stroke:#333,color:#000
    classDef external fill:#ccc,stroke:#333,color:#000
    classDef system fill:#ddd,stroke:#333,color:#000
    classDef annotation fill:none,stroke:none,color:#000, font-style:italic
```
