Home

Relevant source files

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

• README.md
• app/src/main/AndroidManifest.xml
• app/src/main/java/com/vocabri/VocabriApplication.kt
• app/src/main/java/com/vocabri/di/AppModule.kt
• data/src/main/java/com/vocabri/data/di/DataModule.kt
• app/src/main/java/com/vocabri/ui/main/viewmodel/MainViewModel.kt
• app/src/main/res/values/strings.xml
• app/src/main/res/xml/backup_rules.xml
• build-logic/convention/src/main/kotlin/ProjectConventionPlugin.kt

Vocabri is a modern, offline-first Android application designed for building a personal vocabulary. The app allows users to add words with detailed information such as translations, usage examples, and part-of-speech specific metadata. It is built with a forward-looking architecture that includes a Kotlin Multiplatform shared module, paving the way for future iOS support.

The core of the application is a local SQLDelight database, ensuring functionality without an internet connection. The user interface is constructed with Jetpack Compose and Material 3, providing a contemporary look and feel. The project emphasizes code quality through a suite of tools and a modular structure.

Sources: README.md:10-12, 25-33

Project Architecture

The project is organized into several distinct Gradle modules, promoting a clean separation of concerns. This modular structure facilitates maintainability, scalability, and the future development of a multiplatform application.

Sources: README.md:36-37

The diagram below illustrates the dependency flow between the main modules.

This diagram shows the high-level module dependencies within the Vocabri project.

Module Descriptions

Module	Description
app	The main Android application module. It contains the Jetpack Compose UI, navigation graph, ViewModels, and the Koin appModule for dependency injection.
domain	Contains the core business logic, including domain models, repository interfaces (contracts), and use cases (e.g., adding, observing, deleting words).
data	Implements the data layer. It includes the SQLDelight database schema and queries, data source implementations, and repository implementations.
core	A set of utility modules. core/logger provides logging abstractions over Kermit, and core/utils contains common utilities like an ID generator abstraction.
shared	A Kotlin Multiplatform module, currently targeting Android and prepared for future iOS framework generation.
build-logic	Contains custom Gradle convention plugins for managing build configurations, code style (Spotless), static analysis (Detekt), and code coverage (Kover).

Sources: README.md:38-47, build-logic/convention/src/main/kotlin/ProjectConventionPlugin.kt

Core Technologies

Vocabri is built using a modern tech stack focused on Kotlin-based, declarative, and reactive principles.

Category	Technology	Description
Language	Kotlin (JDK 21)	The primary programming language for the entire project.
UI	Jetpack Compose, Material 3	For building the app's user interface declaratively.
Dependency Injection	Koin	Used for managing dependencies across all modules.
Concurrency	Kotlin Coroutines	For handling asynchronous operations and managing reactive data flows.
Persistence	SQLDelight 2.x	Provides a type-safe SQL layer over a local SQLite database, enabling an offline-first approach.
Multiplatform	Kotlin Multiplatform	A shared module is in place for future iOS support.
Code Quality	Spotless, Detekt, Kover	Tools for code formatting, static analysis, and code coverage reporting.

Sources: README.md:25-33

Application Startup & Dependency Injection

The application's entry point and dependency graph are initialized when the app starts.

The process begins with the VocabriApplication class, which is declared in the manifest. This class is responsible for setting up the Koin dependency injection framework, which in turn wires together all the components from the various modules.

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

The following sequence diagram shows the Koin initialization flow.

Koin Modules

• dataModule: Provides all data-layer dependencies. This includes the VocabriDatabase instance (configured with AndroidSqliteDriver), repository implementations (WordRepositoryImpl), data sources, and a UuidIdGenerator.
  Sources: data/src/main/java/com/vocabri/data/di/DataModule.kt:44-62
• appModule: Provides application-layer dependencies, primarily the ViewModels for each screen (e.g., MainViewModel, DictionaryViewModel, AddWordViewModel). It also provides an AndroidResourcesRepository to bridge domain logic with Android resources.
  Sources: app/src/main/java/com/vocabri/di/AppModule.kt:31-48
• domainModule: Provides use cases that encapsulate business logic (not shown in a dedicated file, but referenced in README.md).
  Sources: README.md:40

The VocabriApplication class orchestrates the loading of these modules:

// app/src/main/java/com/vocabri/VocabriApplication.kt:34-39
startKoin {
    log.i { "Initializing Koin with application context and modules" }
    androidLogger()
    androidContext(this@VocabriApplication)
    modules(
        dataModule,
        domainModule,
        appModule,
    )
}

Key Features

Vocabri provides a focused set of features for vocabulary building, with more planned for the future.

Feature	Status	Description
Add Words	Implemented	Add words with multiple translations, usage examples, and part-of-speech metadata (e.g., noun gender, verb forms).
Browse Dictionary	Implemented	View words grouped by part of speech or as a single list.
Delete Words	Implemented	Remove words from the dictionary via the detailed list view.
Offline-First	Implemented	All data is stored locally in an SQLDelight database.
Debug: Add Random Word	Implemented	A helper for development that generates and saves a random word on a long-press of the '+' button.
Training Mode	Planned	Future support for quizzes, flashcards, and spaced repetition.
Search & Filter	Planned	A "Discover" experience with search and filtering capabilities.
Edit Words	Planned	Functionality to edit existing word entries.
Cloud Sync	Planned	Optional synchronization of the user's dictionary to the cloud.

Sources: README.md:14-23

Debug Feature: Generate Random Word

A special debug feature allows for quickly populating the database. A long-press on the floating action button on the main screen triggers this flow.

This diagram shows the flow for the debug feature of adding a random word.

Sources: README.md:20, app/src/main/java/com/vocabri/ui/main/viewmodel/MainViewModel.kt:38-49

Data Persistence and Backup

The application is designed to be offline-first, with all user data stored locally.

• Database: The app uses a local SQLite database named vocabri.db. SQLDelight manages the schema and provides type-safe queries.
• Backup: Android's Auto Backup feature is configured to include the database and user preferences.

The backup rules are defined in backup_rules.xml and data_extraction_rules.xml.

Domain	Path	Included in Backup
database	vocabri.db	Yes
sharedpref	user_preferences.xml	Yes
file	cache/	No
file	code_cache/	No

Sources: README.md:19, data/src/main/java/com/vocabri/data/di/DataModule.kt:47-53, app/src/main/res/xml/backup_rules.xml:26-38