# Android Bible Architecture > Architecture patterns, layer rules, and project conventions for the Bible Android app. Use when adding new features, refactoring, designing new screens, or making architectural decisions. Covers Koin DI patterns, ViewModel conventions, Room schema rules, Gradle Kotlin DSL with version catalogs, and Compose navigation. Triggers on architecture, new feature, koin module, viewmodel, navigation, bible screen, bible module, module scanner. - Skill: `welitonevoc/android-bible-architecture` (Agent Skill) - Install (CLI): `npx skillmds@latest add welitonevoc/android-bible-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/welitonevoc/android-bible-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: welitonevoc (https://skillmd.com/u/welitonevoc) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/welitonevoc/android-bible-architecture --- # Android Bible App — Architecture Guide > **Stack:** Kotlin · Jetpack Compose · Room · Koin · Coroutines/Flow · Gradle Kotlin DSL (Compile SDK 35) --- ## 🏗️ Layer Architecture ``` ┌─────────────────────────────────────────────────┐ │ UI Layer (Jetpack Compose) │ │ BibleScreen.kt, ModulePickerScreen.kt, etc. │ │ State: collectAsStateWithLifecycle() │ └────────────────────┬────────────────────────────┘ │ UiState (sealed/data class) ┌────────────────────▼────────────────────────────┐ │ ViewModel Layer │ │ BibleViewModel, ModuleViewModel, etc. │ │ viewModelScope + StateFlow │ └────────────────────┬────────────────────────────┘ │ Domain Models (pure data) ┌────────────────────▼────────────────────────────┐ │ Repository Layer │ │ BibleRepository, ModuleRepository │ │ Coordinates Room ↔ Engine │ └──────────┬──────────────────────┬───────────────┘ │ │ ┌──────────▼──────────┐ ┌────────▼──────────────┐ │ Room (Installed │ │ Engine Layer │ │ Modules, Notes, │ │ SimpleFileOffline │ │ Bookmarks) │ │ BibleEngine.kt │ │ ModuleDao.kt │ │ MySwordFormatParser │ └─────────────────────┘ └───────────────────────┘ ``` **Hard Rules:** - No DAO calls directly in a `@Composable` — always via ViewModel - No `Context` in ViewModel (use `AndroidViewModel` only if truly needed) - No Compose imports in Repository or Engine - Engine parsers have zero Android framework dependencies --- ## 📁 Project Structure Convention ``` app/ ├── src/main/ │ ├── java/com/yourpackage/bible/ │ │ ├── data/ │ │ │ ├── db/ │ │ │ │ ├── AppDatabase.kt Room database │ │ │ │ ├── dao/ModuleDao.kt DAO interfaces │ │ │ │ └── entity/ModuleEntity.kt Entities │ │ │ ├── engine/ │ │ │ │ ├── SimpleFileOfflineBibleEngine.kt │ │ │ │ └── MySwordFormatParser.kt │ │ │ └── repository/ │ │ │ ├── BibleRepository.kt │ │ │ └── ModuleRepository.kt │ │ ├── di/ │ │ │ └── PlatformSwordKoinModule.kt All Koin modules │ │ ├── ui/ │ │ │ ├── bible/ │ │ │ │ ├── BibleScreen.kt Composable │ │ │ │ └── BibleViewModel.kt ViewModel │ │ │ ├── modules/ │ │ │ │ ├── ModulePickerScreen.kt │ │ │ │ └── ModuleViewModel.kt │ │ │ └── theme/ │ │ │ ├── Color.kt │ │ │ ├── Theme.kt │ │ │ └── Type.kt │ │ └── MainActivity.kt │ └── res/ │ └── values/strings.xml PT-BR strings ├── build.gradle.kts └── ... gradle/ └── libs.versions.toml ← Version catalog (single source of truth) ``` --- ## 🔧 Koin DI Convention (PlatformSwordKoinModule.kt) ### Structure Rules: ```kotlin // PlatformSwordKoinModule.kt val databaseModule = module { single { Room.databaseBuilder(androidContext(), AppDatabase::class.java, "bible_app.db") .fallbackToDestructiveMigrationOnDowngrade() .build() } single { get().moduleDao() } single { get().bookmarkDao() } } val engineModule = module { // Engine is a factory — each call gets a fresh instance for a specific file factory { (filePath: String) -> SimpleFileOfflineBibleEngine(filePath) } // Parser is stateless — single instance is fine single { MySwordFormatParser() } } val repositoryModule = module { single { BibleRepository(get(), get()) } single { ModuleRepository(get(), get()) } } val viewModelModule = module { viewModel { BibleViewModel(get(), get()) } viewModel { (filePath: String) -> ModuleViewModel(get(), filePath) } } // Application.kt startKoin startKoin { androidContext(this@App) modules(databaseModule, engineModule, repositoryModule, viewModelModule) } ``` ### Scope Decision Guide: | Use `single { }` | Use `factory { }` | Use `viewModel { }` | |-----------------|-------------------|---------------------| | Room database | Per-file engine | Screen ViewModels | | DAOs | Per-request objects | Scoped to nav entry | | Repositories | Test fakes | | | Format parser | | | --- ## 📊 Room Schema Rules ### Migrations (MANDATORY for production) ```kotlin // AppDatabase.kt @Database( entities = [ModuleEntity::class, BookmarkEntity::class, NoteEntity::class], version = 2, // Increment on schema change exportSchema = true // Required! Exports to /schemas/ ) abstract class AppDatabase : RoomDatabase() { abstract fun moduleDao(): ModuleDao } // Companion object companion object { val MIGRATION_1_2 = object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { database.execSQL("ALTER TABLE modules ADD COLUMN language TEXT NOT NULL DEFAULT 'pt'") } } } ``` **Schema export config in `build.gradle.kts`:** ```kotlin ksp { arg("room.schemaLocation", "$projectDir/schemas") } ``` --- ## 🎨 Compose UI Conventions ### UiState Pattern (MANDATORY) ```kotlin // For each screen, define a sealed class sealed class BibleUiState { object Loading : BibleUiState() data class Success( val currentModule: ModuleEntity, val verses: List, val currentBook: Int, val currentChapter: Int, val availableModules: List ) : BibleUiState() data class Error(val message: String) : BibleUiState() object NoModulesInstalled : BibleUiState() } ``` ### Screen Anatomy (Standard Structure) ```kotlin @Composable fun BibleScreen( viewModel: BibleViewModel = koinViewModel(), modifier: Modifier = Modifier ) { val uiState by viewModel.uiState.collectAsStateWithLifecycle() when (val state = uiState) { is BibleUiState.Loading -> BibleLoadingContent() is BibleUiState.Success -> BibleContent(state, viewModel::onAction, modifier) is BibleUiState.Error -> BibleErrorContent(state.message) is BibleUiState.NoModulesInstalled -> NoModulesContent() } } ``` ### Bible Text Rendering ```kotlin // Use AnnotatedString for rich text — avoid WebView @Composable fun VerseText(verse: ParsedVerse, fontSize: TextUnit = 16.sp) { val annotatedString = remember(verse) { buildAnnotatedString { verse.segments.forEach { segment -> when (segment) { is TextSegment.Plain -> append(segment.text) is TextSegment.Bold -> withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append(segment.text) } is TextSegment.RedLetter -> withStyle(SpanStyle(color = Color.Red)) { append(segment.text) } // ... etc } } } } Text(text = annotatedString, fontSize = fontSize) } ``` --- ## 📦 Gradle Version Catalog (libs.versions.toml) ### How to Add a New Library: ```toml # Step 1: Add version in [versions] [versions] room = "2.6.1" koin = "3.5.3" compose-bom = "2024.02.00" # Step 2: Add library in [libraries] [libraries] room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" } room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" } room-ksp = { group = "androidx.room", name = "room-compiler", version.ref = "room" } koin-android = { group = "io.insert-koin", name = "koin-android", version.ref = "koin" } koin-compose = { group = "io.insert-koin", name = "koin-androidx-compose", version.ref = "koin" } # Step 3: Reference in build.gradle.kts [plugins] ksp = { id = "com.google.devtools.ksp", version = "1.9.22-1.0.17" } ``` ```kotlin // build.gradle.kts (app) dependencies { implementation(libs.room.runtime) implementation(libs.room.ktx) ksp(libs.room.ksp) implementation(libs.koin.android) implementation(libs.koin.compose) } ``` **Rule:** Never use a version string directly in `build.gradle.kts`. Always add to catalog first. --- ## 🔗 Compose Navigation Setup ```kotlin // NavGraph.kt @Composable fun BibleNavGraph(navController: NavHostController) { NavHost(navController, startDestination = "bible") { composable("bible") { BibleScreen() } composable( route = "modules", enterTransition = { slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.Up) }, exitTransition = { slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.Down) } ) { ModulePickerScreen(onModuleSelected = { navController.popBackStack() }) } composable("search") { SearchScreen() } } } ``` --- ## ✅ Feature Addition Checklist When adding a new feature (e.g., Bookmarks, Notes, Daily Verse): - [ ] **Entity**: New `@Entity` class with `@PrimaryKey` - [ ] **DAO**: Interface with `Flow<>` for observations, `suspend` for writes - [ ] **Database**: Register entity in `@Database(entities = [...])`, increment version, add `Migration` - [ ] **Repository**: New repository class, inject DAO via Koin - [ ] **Koin Module**: Register in appropriate Koin module (single/factory/viewModel) - [ ] **ViewModel**: New ViewModel with `StateFlow`, use `viewModelScope` - [ ] **UiState**: Sealed class covering Loading/Success/Error - [ ] **Screen**: `@Composable` using `collectAsStateWithLifecycle()` - [ ] **Navigation**: Route added to `NavGraph` - [ ] **Strings**: PT-BR strings in `strings.xml` (no hardcoded text) - [ ] **Build**: `./gradlew assembleDebug` passes