Android application

The app is available in the Play store.

Requirements

Architecture

The app is written completely in Kotlin using Jetpack Compose, Dagger/Hilt and aiming to implement a clean architecture.

Module structure

Besides the main app module, the app consists of the following library modules:

balling
common
controller
feed
heating
info
overview
refill
schedule
timedata
ventilation

The main app module contains the AndroidManifest and the main activity (As of November 2025, the app only uses one activity). The activity contains the navigation NavHost in onCreate.

None of the other modules has a dependency to the main app module.

The common module provides low-level functionalities and layout elements used in various places. The following functionalities are located in common module:

DataFetchResult: A wrapper class indicating the status of data fetching operation (Success, Error, Loading, Empty).
WebApiParams, WebApiPostRequest, WebApiPostRequestExecution, WebApiUrls: Classes and objects used for communication from the app to the server.
ControllerProfileDao, ControllerProfileDatabase: Classes which provide Room database functionality.
Various classes used for dependency injection (Hilt)
SetValsSanityCheckResult: Class used for to communicate status of set values for heating and ventilation module.
ControllerProfile: Class containing the profile data of the server (address, port, credentials, ...)
GlobalConstants: Mainly UI-related strings (non-context-related) and some minor functional constants
Composable functions for the main drop down menu
Composable functions for the theme
Composable functions for hyperlinks, text edit fields, headline
ViewNavigationRoutes: Object containing the routing information processed in main app module
ScreenshotTestHelper: Helper class for executing the instrumented snapshot testing using the emulator.

Layer structure

The code is separated into the following layers:

[module]/

├── src/main/kotlin/com/laimburggasse/aquariumcontrol/[module]/data/

│ ├── remote/ // Folder for data retrieval functionality

│ │ └── dto/ // Folder for Data Transfer Objects

│ │ └── [module][name]Import.kt

│ │ └── [module][name]Reader.kt // Implementation of GET server request

│ ├── [module][name]RepositoryImpl.kt // Repositories (implementation of interface)

├── src/main/kotlin/com/laimburggasse/aquariumcontrol/[module]/domain/

│ ├── model/ // Folder for data definition classes

│ │ └── [module][name].kt. // Classes for data definition

│ ├── repository/ // Folder containing repository interface definitions

│ │ └── [module][name]Repository.kt. // Interface defining the repository, used by view model

├── src/main/kotlin/com/laimburggasse/aquariumcontrol/[module]/presentation/

│ ├── entry/ // First screen of feature

│ ├── [components]/ // Shared code between different screens

│ ├── [screen name]/ // Folder for each screen

│ │ └── [module][name]Screen.kt // Composable showing the complete screen

│ │ └── [module][name]Composable.kt // Composable showing elements inside the screen

│ │ └── [module][name]UiEvent.kt // Sealed interface describing the communication from the composable to the view model

│ │ └── [module][name]UiState.kt // Data class describing the content to be rendered by the composable

│ │ └── [module][name]ViewModel.kt // Class implementing the view model

│ ├── navigation/ // Folder containing class and functionality related to screen navigation

│ │ └── [module]NavigationEvent.kt // One sealed class per module containing the navigation intent of the user

│ │ └── [module]Navigator.kt // Module-specific navigation functionality

│ └── build.gradle // Plugins, setting, dependencies

Screen navigation

The screen navigation is controlled by a NavHostController which is instantiated in MainActivity.

Each module adds its own navigation function to NavHostController. These functions are stored in [module]/presentation/navigation/[module]Navigator.kt.

The functions receive as parameter a specific sealed class [module]NavigationEvent. These sealed classes contain objects for each navigation event inside the module.

Example workflow for adding API communication

Implementation

Create the model: RefillState as enum

Add a reader class RefillStateReader which uses the injected interface (Retrofit)

Update the RefillStateApiService: Add a function to load the state via Retrofit

Add the label for the JSON property in WebApiParams

Add the URL for the end point in WebApiUrls

Add a wrapper RefillStateResponse for the model to allow Retrofit parsing the JSON

Update the repository interface and the repository interface implementation:

Add a flow that delivers a DataFetchResult of the RefillState
Add a function that allows the view model to trigger a refresh

Add a wrapper class RefillStateUiState Update the view model

Add a flow that delivers a RefillStateUiState based on the DataFetchResult from repository
Handle the new UI event for refreshing

Add composable RefillStateComposable for displaying the RefillState

Update RefillUiEvent with an object for the refresh

Update RefillScreen:

additional parameter (RefillStateUiState) in composable function and in previews
Added PullToRefreshBox
Added parsing of RefillUiState and display of either

   * RefillStateComposable in case of success
   * Text-based error message in case of error
   * CircularProgressIndicator in case of loading

Inject RefillUiState into RefillScreen in the MainActivity and RefillScreenTest as well as in previews of RefillScreen

(Optional) Check if RefillDataModule needs update (not required in this case)

Testing

Update existing screenshot testing

Add screenshot testing for new composable

Test strategy

The app uses different testing approaches:

Compose preview screenshot testing
Screenshot tests running as instrumented tests on emulator
Unit tests

Compose preview screenshot tests

These tests run comparably fast and device-independent.

The compose preview screenshot tests cover portrait mode/landscape mode, light/dark mode (four variants).

Limitations:

Two tests within feed module can only run in landscape mode (FeedProfileScheduleScreenTest, FeedHistoryScreenTest) due to excessive heap memory utilisation.
Info screen is not tested due to LibrariesContainer (dynamic content which cannot be mocked).

The tests are located in [module]/src/screenshotTest/kotlin/com/aquariumcontrol/[module]/.

The references are located in [module]/src/screenshotTestDebug/kotlin/com/aquariumcontrol/[module]/.

The test reports are located in build/reports/screenshotTest/preview/debug/. The test reports for the compose screenshot tests contain reference, actual and delta images.

The images are generated with ./gradlew [module]:updateDebugScreenshotTest.

The images are validated with ./gradlew [module]:validateDebugScreenshotTest.

Omitting the module will execute all tests.

Instrumented tests

The tests run comparably long and are bound to an emulator device. As of November 2025, a Pixel 5 API S is used for the instrumented test. The instrumented tests contain

screenshot testing for the complete screens (ScreenNameTest)
verification if the composable triggers the right event when tapping on buttons bound to navigation to another screen (ScreenNameUITest)

Limitations:

Info screen is not tested due to LibrariesContainer (dynamic content which cannot be mocked and also does not allow execution of instrumented test).

The test reports are located in build/reports/androidTests/connected/debug/. The test reports for the compose screenshot tests do not contain any images.

The tests are executed with ./gradlew [module]:connectedDebugAndroidTest. Omitting the module will execute all tests.

A switch called recordMode inside each test class for screenshot testing determines if the image is generated (true) or if the image is validated (false). The images are generated on the device (/data/data/com.laimburggasse.aquariumcontrol.[module].test/files/screenshots_output/) and need to be downloaded to the repository.

Unit tests

As of November 2025, there are no unit tests.

Release procedure

Update versionCode and versionName in build.gradle.kts of app module.
Create a release branch (release/[version]), checkout, commit and push.
Change to release build variant.
Build
Generate a signed App bundle
Upload to play store