<!-- ~ SPDX-FileCopyrightText: 2024-2026 shining-cat ~ SPDX-License-Identifier: GPL-3.0-or-later --> <!-- Project Status & Distribution -->

<!-- CI/CD & Quality Checks -->

<!-- Standards & Compliance -->

<div style="display:flex; justify-content:center; align-items:center; gap:20px;"> <img src="commonResources/src/main/res/raw/exercise_standing_skater.gif" alt="Animated picture for the Standing: The Skater exercise" style="height:180px; width:180px; object-fit:cover;"/> <img src="commonResources/src/main/res/mipmap-xhdpi/tv_banner_figure_and_clock_bicolor_secondary.png" alt="Icon of a silhouette doing an exercise below a stopwatch with a highlighted elapsed time" style="height:180px;"/> <img src="commonResources/src/main/res/raw/exercise_standing_skater.gif" alt="Animated picture for the Standing: The Skater exercise" style="height:180px; width:180px; object-fit:cover;"/> </div>

SimpleHIIT

SimpleHIIT is a HIIT (High-Intensity Interval Training) with a timer and animated exercises.

• select which types of exercises to include in a session among 8 categories
• customize work and rest periods' length
• choose the number of cycles to perform in a session
• manage multiple user profiles, pick who is participating in a session
• track your progress with built-in statistics
• 3 languages supported: English, French, Swedish
• dark and bright themes support

SimpleHIIT is available today on:

• Android mobile
• Android TV

Get SimpleHIIT:

• Download latest releases from GitHub
• Get it on F-Droid (mobile/touch devices)

Table of Contents

• Overview
• Caracteristics
• Work in Progress
• Setup for Contributors
• Threading Strategy
• Notes on UseCases
• Notes on ViewModels
• Modularization
• Credits
  • External libraries / plugins
  • References

Documentation

• CI/CD Workflows
• Deprecation Checker
• Git Hooks
• Gradle Tasks Reference
• Koin DI Naming Conventions
• Kover Code Coverage
• Ktlint Formatting Guide
• Module Dependencies
• Releases
• Threading Strategy
• Accessibility
• TODO List

Overview

This is a simple HIIT application.

• Sessions settings can be refined, like work and rest period duration, number of work period per cycle, and which exercise family to include in a session, or create and edit users.
• On the home screen one can select which user(s) are joining a session, and how many cycle(s) the session should contain.
• The session consists of an alternance of rest and exercise periods, showing an exercise as a looping gif image. A summary of the exercises done is shown at the end of the session.
• A statistics screen allows to see (and delete) basic statistics for each user.

Characteristics:

• MVVM - Clean architecture
• multi-module
• Dagger-hilt for DI
• pure kotlin
• coroutines and flows / stateflows
• Kover for test coverage report generation (see docs/KOVER_CODE_COVERAGE.md)
• Full-Compose for UI
• handle device form-factor variation (TV / mobile) in the same project
• ktlint for code style enforcement (see docs/KTLINT_FORMATTING_GUIDE.md)
• Fully FOSS - GPL-3.0-or-later license
• No proprietary dependencies, no tracking, no analytics

This is a WIP / Demo / Experimentation project: see current TODO list

Setup for Contributors

Build Requirements

This project requires JDK 21 to build. The build is configured to be portable and will use Gradle's toolchain mechanism to find or download the correct JDK, regardless of your local JAVA_HOME setting.

However, for a smooth experience, it is recommended to have a JDK 21 installation available on your system.

Git Hooks

After cloning the repository, run the git hooks setup to enable automatic handling of CI-generated commits:

./.githooks/setup.sh

This configures a pre-push hook that automatically merges remote changes (like dependency graph updates from CI) before pushing. See docs/GITHOOKS.md for details.

Threading Strategy

This project uses dispatcher injection for clean thread management across architecture layers:

• Presentation (ViewModels): Main thread
• Domain (Use Cases): Default thread
• Data (Repository): IO thread

All suspend methods are main-safe, enabling testability through TestDispatcher injection.

For complete details on threading choices and rationale, see docs/THREADING.md.

Notes on UseCases

Usecases follow a common convention:

• They are named [action]+"UseCase"
• They expose a single public method named "execute", suspending or not, with various input parameters, as needed<br/>

While I like the idea of replacing the execute method by an override of the invoke operator, I found out that it has 2 main drawbacks:

1. ~~First, and that is a big issue in my mind, overriding the invoke operator is mostly interesting because it allows one to shorten the call site code, by simply invoking the usecase. Now that last point in my opinion comes with a steep decrease in discoverability, as it will break the IDE's ability to find usages of the invoke method, thus greatly hindering navigation around the code~~ update: this seems to work now in android studio panda 2
2. Removing the "Usecase" suffix makes the task of finding names harder, as the usecase is usually invoked from inside a viewmodel's method. Now this method could very well have the same name, and the "Usecase" suffix allows keeping the same name for both: UserManagementViewModel:createUser(user) can call createUserUseCase(user). If your usecase is also named CreateUser, troubles won't be long coming

These are the reasons why I'll keep using the "traditional" structure for usecases, as I value discoverability and clarity more than conciseness.

Notes on ViewModels

ViewModels are provided with a dedicated Interactor, which is a simple convenience wrapper around all the usecases the viewmodel needs. This is mostly to reduce the list of constructor parameters in the ViewModel, and simplify the addition of any new usecase to it.<br/> Since the group of usecases needed might vary between platforms and their dedicated presentation layer, the interactor is part of the presentation layer too.

Modularization

This project follows a matrix-like modularization structure with strict clean architecture principles:

• Features (columns): Home, Settings, Session, Statistics
• Layers (rows): Presentation (UI), Domain, Data
• Platforms: Mobile and TV with shared foundation modules

The dependency graph shows the current validated module structure. Dependencies are validated on every PR, and the graph is automatically updated when changes are merged to master. Dependencies flow top-to-bottom only, with lateral dependencies restricted to common modules.

For complete details on module architecture, dependency rules, and enforcement, see docs/MODULE_DEPENDENCIES.md.

Note on creating new modules in Android Studio: AS will add these plugins to the main build.gradle.kts - remove them as they'll fail the build:

• id("com.android.library") version ...
• id("org.jetbrains.kotlin.android") version ...

Credits

All exercise pictures were made with the help of the awesome PoseMyArt free web app

External libraries / plugins

• Ben Mannes' Gradle version plugin
• [Kover - Kotlin code coverage by Jet