Debug Feature: Generate Random Words

Relevant source files

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

• README.md
• app/src/main/java/com/vocabri/ui/main/viewmodel/MainViewModel.kt
• domain/src/main/java/com/vocabri/domain/usecase/debug/GenerateRandomWordUseCase.kt
• domain/src/main/java/com/vocabri/domain/repository/DebugRepository.kt
• data/src/main/java/com/vocabri/data/repository/debug/DebugRepositoryImpl.kt
• data/src/main/java/com/vocabri/data/datasource/debug/DebugDataSource.kt
• data/src/main/java/com/vocabri/data/datasource/debug/DebugDataSourceImpl.kt
• data/src/main/java/com/vocabri/data/di/DataModule.kt
• app/src/main/java/com/vocabri/di/AppModule.kt

The "Generate Random Words" feature is a debug helper designed to facilitate development and testing by allowing for the quick population of the local database. Users can trigger this feature by long-pressing the + button on the main screen, which generates and saves a new, randomized word entry.

This functionality spans across all major architectural layers of the application: UI (ViewModel), Domain (Use Cases), and Data (Repositories and Data Sources). It provides a practical way to test dictionary-related features without manually entering data.

Sources: README.md, app/src/main/java/com/vocabri/ui/main/viewmodel/MainViewModel.kt:50-59

Architecture and Data Flow

The feature is initiated by a user interaction in the UI and flows through the domain and data layers to generate a word, which is then passed back up and saved into the database using the standard word-adding flow.

The following sequence diagram illustrates the end-to-end process, from the user's long-press gesture to the final database insertion.

Component Breakdown

The feature is composed of several key classes, each with a distinct responsibility, following a clean architecture pattern.

This diagram shows the class relationships for the debug generation logic.

UI Layer: MainViewModel

The MainViewModel is the entry point for this feature. It listens for a long-click event and orchestrates the generation and saving of the word.

• handleEvent(MainEvent.OnPlusButtonLongClick): This function is called when the user performs a long-press. It triggers the onPlusButtonLongClick private method.
• onPlusButtonLongClick():
  1. Calls generateRandomWordUseCase.execute() to obtain a Word object.
  2. Launches a coroutine to call addWordsUseCase.execute(word), which saves the generated word to the database.
  3. It includes error handling to log exceptions, such as if the word already exists.

Sources: app/src/main/java/com/vocabri/ui/main/viewmodel/MainViewModel.kt:45-59

Domain Layer: GenerateRandomWordUseCase

This use case acts as a simple intermediary between the ViewModel and the Data layer. Its sole purpose is to abstract the DebugRepository and expose a method to get a random word.

• execute(): Word: This function calls debugRepository.getRandomWord() and returns the result.

Sources: domain/src/main/java/com/vocabri/domain/usecase/debug/GenerateRandomWordUseCase.kt:38-41

Data Layer: Repository and Data Source

DebugRepositoryImpl

This class implements the DebugRepository interface. It delegates the call to the DebugDataSource.

• getRandomWord(): Word: Calls debugDataSource.generateRandomWord() to get the word object.

Sources: data/src/main/java/com/vocabri/data/repository/debug/DebugRepositoryImpl.kt:34-38

DebugDataSourceImpl

This is the core of the generation logic. It contains methods to create a random Word object with randomized properties.

• generateRandomWord(): Word: Randomly selects one of four parts of speech (Noun, Verb, Adjective, or Adverb) and calls the corresponding private generation method.
• Private Generators: Methods like generateRandomNoun(), generateRandomVerb(), etc., construct a Word subtype with randomized data.
• Helper Methods:
  • generateRandomTranslations(): Creates a list of 1 to 3 random translations.
  • generateRandomExamples(): Creates a list of 0 to 2 random examples.
  • randomStringOrNull(): Has a 50% chance to return a random string or null.
  • randomGenderOrNull(): Has a 25% chance to return MASCULINE, FEMININE, NEUTER, or null.

Sources: data/src/main/java/com/vocabri/data/datasource/debug/DebugDataSourceImpl.kt:39-165

Generated Word Properties

The DebugDataSourceImpl generates words with the following randomized attributes:

Part of Speech	Property	Generation Logic	Source File & Lines
Noun	text	"Noun_" + random_string(4)	DebugDataSourceImpl.kt:53
	translations	1-3 random Translation objects	DebugDataSourceImpl.kt:54, 119-126
	examples	0-2 random Example objects	DebugDataSourceImpl.kt:55, 131-138
	gender	MASCULINE, FEMININE, NEUTER, or null (25% chance each)	DebugDataSourceImpl.kt:56, 158-165
	pluralForm	null or "pl_" + random_string() (50% chance)	DebugDataSourceImpl.kt:57, 150-154
Verb	text	"Verb_" + random_string(4)	DebugDataSourceImpl.kt:68
	conjugation	null or "conj_" + random_string() (50% chance)	DebugDataSourceImpl.kt:71, 150-154
	management	null or "mgmt_" + random_string() (50% chance)	DebugDataSourceImpl.kt:72, 150-154
Adjective	text	"Adj_" + random_string(4)	DebugDataSourceImpl.kt:83
	comparative	null or "comp_" + random_string() (50% chance)	DebugDataSourceImpl.kt:86, 150-154
	superlative	null or "sup_" + random_string() (50% chance)	DebugDataSourceImplkt:87, 150-154
Adverb	text	"Adv_" + random_string(4)	DebugDataSourceImpl.kt:98
	comparative	null or "comp_" + random_string() (50% chance)	DebugDataSourceImpl.kt:101, 150-154
	superlative	null or "sup_" + random_string() (50% chance)	DebugDataSourceImpl.kt:102, 150-154

Source: data/src/main/java/com/vocabri/data/datasource/debug/DebugDataSourceImpl.kt

Dependency Injection

The components of this feature are wired together using Koin. The dataModule provides the data layer implementations, which are then consumed by the domain and app layers.

// From data/src/main/java/com/vocabri/data/di/DataModule.kt
val dataModule = module {
    // ...
    singleOf(::DebugDataSourceImpl) { bind<DebugDataSource>() }
    singleOf(::DebugRepositoryImpl) { bind<DebugRepository>() }
    // ...
}

// From app/src/main/java/com/vocabri/di/AppModule.kt
val appModule = module {
    viewModelOf(::MainViewModel)
    // ...
}

Sources: data/src/main/java/com/vocabri/data/di/DataModule.kt:47-49, app/src/main/java/com/vocabri/di/AppModule.kt:33

This diagram shows how Koin resolves the dependencies for this feature.

Summary

The "Generate Random Words" feature is a well-encapsulated debug tool that follows the project's clean architecture. It is triggered from the MainViewModel, flows through a dedicated use case, repository, and data source to generate a random Word object, and then uses the existing AddWordUseCase to persist it. This design makes it an effective and non-intrusive utility for development and testing.