# normancao2702/cmpt362-myruns architecture

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

- Interactive diagram: https://gitdiagram.com/normancao2702/cmpt362-myruns
- Repository: https://github.com/normancao2702/cmpt362-myruns

## Overview

##### Project type and purpose
- This is an Android mobile application (“MyRuns”) for tracking exercise sessions (run, walk, climb, unknown) by sampling the device accelerometer and GPS, storing history locally in a Room database, and displaying maps via Google Maps API.

##### File structure
- Top-level “app/src/main/java/com/example/tranquangngoc_cao_myruns2” contains subpackages:
- automatic – sensor sampling, FFT, Weka classifier, global constants
- database – Room entities, DAO, database class, migrations, repository
- googleMap – ViewModel, Activities/Services for map display & location tracking
- historyFragment & historyDetail – fragment for list of past entries and detailed display
- manualActivity – manual entry UI
- startFragment, settingFragment, userProfile – UI navigation & user settings
- util – shared utilities (unit conversion, helpers)
- AndroidManifest.xml, Gradle scripts, resource directories (layouts, drawables, values) are standard.

##### README for additional insights
- Confirms features: location & speed tracking, exercise classification, photo upload, unit preferences.
- Dependencies: Android API 33+, Room database, Google Play Services (Maps), Weka for classification.

##### Main components and their relationships
a. Components
1. UI Layer
– Activities & Fragments: MainActivity (host), StartFragment, HistoryFragment, SettingsFragment, UserProfileActivity, ManualEntryActivity, DisplayEntryActivity, MapDisplayActivity, MapDetailActivity
2. ViewModels (in googleMap & possibly injected in Fragments)
3. Background Services
– SensorService: samples accelerometer, forwards data to WekaClassifier via Globals
– TrackingService: obtains location updates for mapping & distance/speed calculations
4. Automatic Classification
– FFT: feature extraction
– WekaClassifier: ML model inference (Run, Walk, Climb, Unknown)
5. Data Layer
– ExerciseDatabase (Room)
– ExerciseEntry entity & DAO
– ExerciseRepository: interface between ViewModels/Activities/Services and the database
6. External Services
– Google Maps API for map display & routing
– Android system sensors (accelerometer, location API)

b. Data flow & interactions
- User interacts with UI → triggers ViewModel methods → reads/writes via ExerciseRepository → Room database
- Background SensorService samples accelerometer → processes data (FFT) → WekaClassifier → writes classification + timestamp to database via Repository
- TrackingService collects GPS coordinates → emits updates to MapViewModel → UI map updates in MapDisplayActivity/MapDetailActivity
- SettingsFragment updates user preferences (units, notifications) stored in SharedPreferences or Globals
- HistoryFragment retrieves list of ExerciseEntry records via Repository → displays in RecyclerView

##### Architectural patterns & design principles
- MVVM (Model-View-ViewModel): separates UI (Activities/Fragments) from business logic (ViewModels) and data (Repository + Room)
- Repository pattern: abstracts Room database operations behind a clean API
- Service-based background processing: SensorService & TrackingService run as foreground services for continuous sampling
- Modular package structure: by feature (automatic, database, googleMap, history, manual, settings, etc.)

##### Relevant technologies & libraries
- Kotlin + Android Jetpack (Room, ViewModel, LiveData/DataBinding)
- Google Play Services: Maps and Location
- Weka ML library (for on-device classification)
- FFT algorithm implementation for feature extraction
- Coroutines or standard threading (if present) for async database/service tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MA["MainActivity"]:::ui
        SF["StartFragment"]:::ui
        HF["HistoryFragment"]:::ui
        SeF["SettingsFragment"]:::ui
        UP["UserProfileActivity"]:::ui
        MEA["ManualEntryActivity"]:::ui
        DEA["DisplayEntryActivity"]:::ui
        MDA["MapDisplayActivity"]:::ui
        MDTA["MapDetailActivity"]:::ui
    end

    %% ViewModel Layer
    subgraph "ViewModel Layer"
        direction TB
        MV["MapViewModel"]:::vm
    end

    %% Services Layer
    subgraph "Services"
        direction TB
        SS["SensorService"]:::service
        TS["TrackingService"]:::service
    end

    %% ML Pipeline
    subgraph "Automatic Classification"
        direction TB
        G["Globals"]:::service
        F["FFT"]:::service
        W["WekaClassifier"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ER["ExerciseRepository"]:::data
        DB["ExerciseDatabase"]:::db
        DAO["ExerciseEntryDao"]:::data
        EE["ExerciseEntry"]:::data
        DM["DatabaseMigrations"]:::data
    end

    %% External
    subgraph "External Services"
        direction TB
        SENS["Android Sensors"]:::external
        LOC["Location API"]:::external
        GMAP["Google Maps API"]:::external
        PREF["SharedPreferences"]:::external
    end

    %% UI to ViewModel and Repository
    MDA -->|"location updates"| MV
    MDTA -->|"location updates"| MV
    HF -->|"get entries"| ER
    SF -->|"start session"| ER
    SeF -->|"update settings"| PREF
    SeF -->|"load settings"| PREF
    MA -->|"nav to fragments/activities"| SF
    MA -->|"nav to fragments/activities"| HF
    MA -->|"nav to fragments/activities"| SeF
    MA -->|"nav to activities"| UP
    MA -->|"nav to activities"| MEA
    HF -->|"view detail"| DEA

    %% ViewModel to UI
    MV -->|"map data"| MDA
    MV -->|"map data"| MDTA

    %% Services interactions
    SENS -->|"accelerometer samples"| SS
    SS -->|"raw data"| F
    F -->|"features"| W
    W -->|"classified activity"| ER
    LOC -->|"GPS coordinates"| TS
    TS -->|"location updates"| MV

    %% Repository and DB
    ER -->|"CRUD operations"| DAO
    DAO -->|queries| DB
    EE -->|schema| DB
    DM -->|migrations| DB

    %% UI direct repository
    DEA -->|"load entry"| ER

    %% External APIs
    GMAP -->|"map tiles & routes"| MDA
    GMAP -->|"map tiles & routes"| MDTA

    %% Click Events
    click MA "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/MainActivity.kt"
    click SF "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/startFragment/StartFragment.kt"
    click HF "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/historyFragment/HistoryFragment.kt"
    click SeF "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/settingFragment/SettingsFragment.kt"
    click UP "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/userProfile/UserProfileActivity.kt"
    click MEA "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/manualActivity/ManualEntryActivity.kt"
    click DEA "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/historyDetail/DisplayEntryActivity.kt"
    click MDA "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/googleMap/MapDisplayActivity.kt"
    click MDTA "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngocao_myruns2/historyDetail/MapDetailActivity.kt"
    click MV "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/googleMap/MapViewModel.kt"
    click SS "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/automatic/SensorService.kt"
    click TS "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/googleMap/TrackingService.kt"
    click F "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/automatic/FFT.kt"
    click W "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/automatic/WekaClassifier.kt"
    click G "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/automatic/Globals.kt"
    click DB "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/database/ExerciseDatabase.kt"
    click EE "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/database/ExerciseEntry.kt"
    click DAO "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/database/ExerciseEntryDao.kt"
    click ER "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/database/ExerciseRepository.kt"
    click DM "https://github.com/normancao2702/cmpt362-myruns/blob/main/app/src/main/java/com/example/tranquangngoc_cao_myruns2/database/DatabaseMigrations.kt"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#1e88e5
    classDef vm fill:#c8e6c9,stroke:#43a047,color:#43a047
    classDef service fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef data fill:#e1bee7,stroke:#8e24aa,color:#8e24aa
    classDef db fill:#ce93d8,stroke:#6a1b9a,color:#6a1b9a
    classDef external fill:#cfd8dc,stroke:#607d8b,color:#455a64
```
