Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• gradle/libs.versions.toml
• app/src/main/AndroidManifest.xml
• app/src/main/java/com/vocabri/VocabriApplication.kt
• build-logic/convention/src/main/kotlin/ProjectConventionPlugin.kt
• data/src/main/java/com/vocabri/data/di/DataModule.kt
• build-logic/convention/src/main/kotlin/com/vocabri/JvmVersionConfig.kt
• build-logic/convention/src/main/kotlin/com/vocabri/SpotlessConfiguration.kt
• build-logic/convention/src/main/kotlin/com/vocabri/DetektConfiguration.kt
• build-logic/convention/src/main/kotlin/com/vocabri/KoverConfiguration.kt
• app/src/main/java/com/vocabri/di/AppModule.kt

This guide provides instructions on how to set up, build, and run the Vocabri project. Vocabri is a modern, offline-first Android application designed for building a personal vocabulary. It utilizes a multi-module architecture with Kotlin, Jetpack Compose, and SQLDelight.

The project is structured to support future expansion, including an iOS app via a Kotlin Multiplatform shared module. This document covers system requirements, project structure, and common development tasks.

Sources: README.md:1-12, 28-31

Requirements

To build and run the Vocabri project, your development environment must meet the following requirements:

Component	Version
Android Studio	Latest stable
JDK	21
Android minSdk	24
Android compileSdk	36

Sources: README.md:33-36, gradle/libs.versions.toml:2-4, build-logic/convention/src/main/kotlin/com/vocabri/JvmVersionConfig.kt:28

Initial Setup

1. Clone the repository:

   git clone https://github.com/deledzis/Vocabri.git
   

2. Open in Android Studio: Open the cloned repository folder in Android Studio.
3. Gradle Sync: Allow Gradle to sync the project. This will download all necessary dependencies and configure the project automatically. A google-services.json file is included for convenience.

Sources: README.md:38-40, 47-48

Project Structure

The project follows a multi-module architecture to separate concerns and promote scalability. The main modules are app, domain, data, core, and shared.

This diagram shows the dependency flow between the primary modules in the Vocabri project.

Sources: README.md:19-26

Module	Description
app	The main Android application module. Contains Compose UI, navigation, ViewModels, and app-level DI.
domain	Contains domain models, repository interfaces, and business logic (use cases).
data	Implements repositories, data sources, and the SQLDelight database.
core	Contains shared utilities like logger abstractions (core/logger) and an ID generator (core/utils).
shared	A Kotlin Multiplatform module intended for sharing code with a future iOS app.
build-logic	Custom Gradle convention plugins for configuring the build, code quality tools, and testing.

Sources: README.md:19-26

Application Initialization

The application's entry point is VocabriApplication, which is responsible for initializing the Koin dependency injection framework. It loads modules from the app, data, and domain layers.

This sequence diagram illustrates the Koin initialization process when the application starts.

Sources: app/src/main/java/com/vocabri/VocabriApplication.kt:29-41, app/src/main/AndroidManifest.xml:21

Building and Running

You can build and run the application using either Android Studio or the Gradle wrapper from the command line.

• Android Studio: Select the app configuration from the run configurations dropdown and click the 'Run' button.
• Command Line:
  • To build a debug APK:

    ./gradlew :app:assembleDebug
    

  • To install the debug APK on a connected device or emulator:

    ./gradlew :app:installDebug
    

The main entry point for the UI is MainActivity.

Sources: README.md:41-43, app/src/main/AndroidManifest.xml:29

Debug Features

A debug helper is available to quickly populate the database. Long-press the + button on the main screen to generate and save a random word. This action is handled by MainViewModel, which uses GenerateRandomWordUseCase.

Sources: README.md:16-17, 45-46, app/src/main/java/com/vocabri/ui/main/viewmodel/MainViewModel.kt:35-37, 40-51

Development Tasks

The project includes several Gradle tasks for maintaining code quality, running tests, and generating reports. These are configured via custom convention plugins in the build-logic module.

Sources: build-logic/convention/src/main/kotlin/ProjectConventionPlugin.kt:28-33

Task	Command	Description - -
Code Formatting	./gradlew spotlessApply	Formats Kotlin, XML, JSON, YAML, and Markdown files according to the project's style guide using Spotless with ktlint. -
Static Analysis	./gradlew detekt	Runs static code analysis on Kotlin files using Detekt to find potential issues. Configuration is in .detekt/detekt-config.yml. -
Unit Tests	./gradlew test	Executes all JVM unit tests in the project. -
UI Tests	./gradlew :app:connectedAndroidTest	Runs instrumented UI tests on a connected Android device or emulator. -
Code Coverage	./gradlew koverHtmlReport	Generates an aggregated HTML code coverage report using Kover. Exclusions are defined in KoverConfiguration.kt. -

Sources: README.md:52-58, build-logic/convention/src/main/kotlin/com/vocabri/SpotlessConfiguration.kt, build-logic/convention/src/main/kotlin/com/vocabri/DetektConfiguration.kt, build-logic/convention/src/main/kotlin/com/vocabri/KoverConfiguration.kt

Database

The application uses SQLDelight for local persistence.

• Database Name: vocabri.db
• Schema Location: data/src/main/sqldelight
• Driver: AndroidSqliteDriver is used to create the database instance.

The database is initialized in the dataModule for Koin.

Sources: README.md:65-68, data/src/main/java/com/vocabri/data/di/DataModule.kt:38-45