# minhdeepzaizler/werun architecture

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

- Interactive diagram: https://gitdiagram.com/minhdeepzaizler/werun
- Repository: https://github.com/minhdeepzaizler/werun

## Overview

##### Project type and purpose
- This is a single-module Android mobile application (“WeRun”) written in Kotlin.
- Purpose: track and display running data (location, distance, history), integrate weather info, social features (friends), background music control (Spotify), and push notifications.

##### File structure
- Root module with Gradle build files; one Android “app” module.
- Inside app/src/main/java/com/example/werun:
– data/ → domain models (User, Friend, RunData), repository interfaces and Firebase-backed implementations (UserRepository, HomeRepository, etc.), and a REST client (WeatherAPIService).
– services/ → background Android Services for location tracking, notification listening, and music control (Spotify and local media).
– di/ → a module that provides Firebase SDK instances via Dependency Injection.
– ui/ → Jetpack Compose UI: screens (auth, home, run, friends, history, profile, landing), ViewModels, navigation graph, reusable components, theme definitions.
– utils/ → helper functions (e.g. mapping raw GPS data).
- app/src/main/res → drawables, layouts (Compose), XML config for data backups and Firebase.
- External libs: Mapbox SDK, Firebase (via google-services.json), Spotify App Remote AAR.

##### README insights
- Tech stack: Kotlin, Android, Jetpack Compose, Coroutines/Flow, Firebase (Auth + Firestore/RTDB), Mapbox, Spotify App Remote, external Weather API.
- Architectural hints: MVVM pattern (UI→ViewModel→Repository), Repository pattern, DI for external SDKs.

– Presentation Layer (Android Client)
· UI Screens (Compose)
· ViewModels
– Domain/Data Layer
· Repositories
· Models (User, RunData, WeatherData)
– Background Services
· LocationTrackingService (GPS sensor)
· NotificationListener
· MusicMediaManager & SpotifyMusicManager
– Dependency Injection Module (FirebaseModule)
– External Services
· Firebase (Auth, Firestore/RTDB)
· Mapbox API
· Spotify Remote API
· Weather REST API
– Device Resources
· GPS Sensor
· Media Session

– UI → ViewModel (user events)
– ViewModel → Repository (data fetch/save)
– Repository ↔ Firebase / Weather API (network calls)
– LocationTrackingService → Repository (periodic GPS updates)
– NotificationListener → ViewModel / Repository (incoming notifications)
– Music managers ↔ Spotify SDK & local media player
– DI Module provides SDK instances to Repositories and Services

c. Architectural patterns & principles
– MVVM: clear separation of concerns
– Repository pattern: abstracts data sources
– Dependency Injection: decouples SDK instantiation
– Single-Activity / Navigation Graph: Compose navigation via NavGraph.kt
– Background processing: Android Services for long-running tasks

d. Key technologies / frameworks
– Kotlin + Coroutines/Flow
– Jetpack Compose (UI)
– Firebase SDK (Auth, Firestore)
– Mapbox SDK (maps)
– Spotify App Remote (music control)
– REST client for Weather API
– Gradle/Kotlin DSL for build scripts

##### Depth over breadth
- Every major package or layer—don’t just show “App → Firebase,” but break out Services, Repositories, ViewModels, and the UI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer (UI)
    subgraph "Presentation Layer" 
        direction TB
        UI_Screens["UI Screens"]:::ui
        ViewModels["ViewModels"]:::ui
        NavGraph["Navigation Graph"]:::ui
        Components["Reusable UI Components"]:::ui
        Theme["Theme Definitions"]:::ui
    end

    %% Domain/Data Layer
    subgraph "Domain & Data Layer"
        direction TB
        Models["Domain Models"]:::domain
        WeatherClient["Weather REST Client"]:::domain
        Repositories["Repositories"]:::domain
    end

    %% Background Services
    subgraph "Background Services"
        direction TB
        LocationService["LocationTrackingService"]:::service
        NotificationService["NotificationListener"]:::service
        MusicManager["MusicMediaManager"]:::service
        SpotifyManager["SpotifyMusicManager"]:::service
    end

    %% Dependency Injection
    DI_Module["FirebaseModule (DI)"]:::di

    %% External Services
    subgraph "External Services"
        direction TB
        Firebase["Firebase Auth & Firestore/RTDB"]:::external
        Mapbox["Mapbox SDK"]:::external
        SpotifySDK["Spotify App Remote"]:::external
        WeatherAPI["Weather API"]:::external
    end

    %% Device Resources
    subgraph "Device Resources"
        direction TB
        GPS["GPS Sensor"]:::resource
        MediaSession["Media Session"]:::resource
    end

    %% Connections: UI → ViewModel
    UI_Screens -->|"user events"| ViewModels
    Components --> ViewModels
    NavGraph --> UI_Screens

    %% ViewModel → Repository
    ViewModels -->|"fetch/save data"| Repositories

    %% Models and client
    Models --> Repositories
    WeatherClient --> Repositories

    %% Repositories ↔ External
    Repositories -->|"Firestore SDK"| Firebase
    Repositories -->|"HTTP REST"| WeatherAPI

    %% Services → Repository / ViewModel
    LocationService -->|"location updates"| Repositories
    LocationService --> GPS
    NotificationService --> Repositories
    NotificationService --> ViewModels
    MusicManager --> MediaSession
    MusicManager --> Repositories
    SpotifyManager --> SpotifySDK
    SpotifyManager --> Repositories

    %% DI provides to repos and services
    DI_Module --> Repositories
    DI_Module --> LocationService
    DI_Module --> NotificationService
    DI_Module --> MusicManager
    DI_Module --> SpotifyManager

    %% Mapbox integration in Home screen
    Mapbox --> Repositories

    %% Styles
    classDef ui fill:#a4f9a4,stroke:#333,stroke-width:1px
    classDef domain fill:#a4c8f0,stroke:#333,stroke-width:1px
    classDef service fill:#f0b870,stroke:#333,stroke-width:1px
    classDef di fill:#d6a4f0,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef resource fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2

    %% Click Events
    click UI_Screens "https://github.com/minhdeepzaizler/werun/tree/master/app/src/main/java/com/example/werun/ui/screens"
    click ViewModels "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/ui/screens/auth/LoginViewModel.kt"
    click ViewModels "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/ui/screens/home/HomeViewModel.kt"
    click NavGraph "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/ui/navigation/NavGraph.kt"
    click Components "https://github.com/minhdeepzaizler/werun/tree/master/app/src/main/java/com/example/werun/ui/components"
    click Theme "https://github.com/minhdeepzaizler/werun/tree/master/app/src/main/java/com/example/werun/ui/theme"
    click Models "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/User.kt"
    click Models "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/Friend.kt"
    click Models "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/model/RunData.kt"
    click Models "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/WeatherData.kt"
    click WeatherClient "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/WeatherAPIService.kt"
    click Repositories "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/repository/FirebaseRunRepository.kt"
    click Repositories "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/repository/FriendsRepository.kt"
    click Repositories "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/repository/HomeRepository.kt"
    click Repositories "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/data/repository/UserRepository.kt"
    click DI_Module "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/di/FirebaseModule.kt"
    click LocationService "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/services/LocationTrackingService.kt"
    click NotificationService "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/services/NotificationListener.kt"
    click MusicManager "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/services/MusicMediaManager.kt"
    click SpotifyManager "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/services/SpotifyMusicManager.kt"
    click GPS "https://github.com/minhdeepzaizler/werun/blob/master/app/src/main/java/com/example/werun/utils/toLocationPoint.kt"
    click SpotifySDK "https://github.com/minhdeepzaizler/werun/blob/master/app/libs/spotify-app-remote-release-0.8.0.aar"
    click Firebase "https://github.com/minhdeepzaizler/werun/blob/master/app/google-services.json"
```
