How aviirajsharma/zenki-kmp works
1. Repository shape
- This is a Kotlin Multiplatform mobile app targeting Android and iOS.
- The architecture is split between thin platform shells (androidApp, iosApp) and a large shared module (shared) that contains most UI, state, data access, and business logic.
2. Platform entry points
- androidApp/MainActivity.kt is the Android launch point.
- iosApp/iOSApp.swift and iosApp/ContentView.swift are the iOS launch points, with the iOS-specific Kotlin bridge in shared/src/iosMain/.../MainViewController.kt.
- These shells mostly exist to host the shared app UI and provide platform bootstrapping.
3. Shared UI layer
- The main UI is built in Compose Multiplatform inside shared/src/commonMain/kotlin/.../ui.
- Core app structure lives in App.kt, navigation in navigation/AppNavigation.kt, and shared scaffolding in ui/core (AppScaffold, bottom navigation, snackbar, top-level tabs).
- The app uses a theme system under theme/ with explicit support for theme mode toggling.
4. Feature screens
- The screen layer is organized by feature: home, deck, card, study, quiz, ai, and settings.
- This suggests a flashcard/study product with deck management, study and quiz modes, card editing, and AI-assisted generation.
- CreateDeckDialog and the various screens indicate a task-oriented, multi-screen user flow rather than a single-page app.
5. State and screen logic
- Each major screen has a corresponding ViewModel in ui/viewmodel.
- ViewModels mediate between UI and repositories, and likely own screen state, user actions, and data loading.
- This gives a clear separation between Compose UI rendering and application state orchestration.
6. Domain/data boundary
- Repositories in data/repository form the main abstraction between screens/viewmodels and the underlying data sources.
- There are repositories for decks, flashcards, study sessions, and theme mode.
- This is the main boundary to diagram: UI/ViewModels call repositories, not databases or services directly.
7. Local persistence
- The local data model is defined under data/local/entity with Deck, Flashcard, StudySession, AppMetadata, and a derived view model DeckWithCount.
- DAO interfaces under data/local/dao define access for each entity type.
- DatabaseProvider exists in common code with platform-specific actual implementations in androidMain and iosMain, so persistence is shared conceptually but wired per platform.
8. Remote/AI integration
- data/remote/GroqService.kt and platform-specific HttpClientProvider files indicate a remote API integration, very likely for AI content generation.
- The ai feature screen and AiGenerateViewModel connect this remote service into the app flow.
- In the architecture diagram, this is the main external boundary: shared app → HTTP client → Groq service/API.
9. Dependency injection / composition root
- di/AppModule.kt is the shared composition root for wiring repositories, data sources, and services.
- This is where the app’s object graph is assembled so the UI layer can stay decoupled from concrete implementations.
- It likely binds the database provider, HTTP client, repositories, and view models together.
10. Platform-specific implementations
- shared/src/androidMain/... and shared/src/iosMain/... contain the actual platform implementations for things like the database and HTTP client.
- Platform.android.kt and Platform.ios.kt provide platform identity/info used by shared code.
- These source sets are the key boundary where shared abstractions become Android- or iOS-specific code.
11. Assets and resources
- Shared Compose resources live under shared/src/commonMain/composeResources.
- Android has its own resources in androidApp/src/main/res, while iOS uses Assets.xcassets and Info.plist.
- These are presentation assets rather than business logic, but they matter for the final app packaging on each platform.
12. Overall data flow
- Typical flow is: screen → viewmodel → repository → local database and/or remote service → repository → viewmodel → screen.
- Navigation and scaffolding stay in the shared UI layer, while persistence and network are abstracted behind repository and provider boundaries.
- The Android/iOS apps are primarily launch/hosting layers around the shared Kotlin logic and UI.
Main entry points: AppModule.kt App module · AppNavigation.kt Navigation · DatabaseProvider.kt Local DB · FlashcardRepository.kt Card repo
Components 31
Platform shells
Android and iOS entry points plus platform-specific wiring
- Android app · Android launch activity that hosts the shared app UI
androidApp/src/main/kotlin/com/avirajsharma/zenki/MainActivity.kt - iOS app · SwiftUI host that launches the shared Kotlin UI
iosApp/iosApp/iOSApp.swift - iOS view · SwiftUI content view that embeds the shared app controller
iosApp/iosApp/ContentView.swift - Main VC · iOS Kotlin bridge that creates the shared app view controller
shared/src/iosMain/kotlin/com/avirajsharma/zenki/MainViewController.kt - Platform impls · Android and iOS actual implementations for platform services
shared/src/androidMain/kotlin/com/avirajsharma/zenki/data/local/DatabaseProvider.android.kt
Shared KMP core
Common app logic, UI, state, and domain boundaries
- App entry · Shared application root and top-level composition entry
shared/src/commonMain/kotlin/com/avirajsharma/zenki/App.kt - App module · Wires repositories, services, databases, and view models
shared/src/commonMain/kotlin/com/avirajsharma/zenki/di/AppModule.kt
Data layer
Local persistence, remote API access, and repositories
- Deck repo · Deck data access and deck-level business operations
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/repository/DeckRepository.kt - Card repo · Flashcard CRUD and card-oriented data operations
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/repository/FlashcardRepository.kt - Study repo · Study session persistence and session history operations
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/repository/StudySessionRepository.kt - Theme repo · Persists and resolves the current theme mode
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/repository/ThemeModeRepository.kt - Local DB · Shared database abstraction with platform-specific implementations
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/local/DatabaseProvider.kt - DAOs · Entity access interfaces for decks, cards, sessions, and metadata
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/local/dao/DeckDao.kt - Entities · Local storage models for decks, flashcards, sessions, and metadata
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/local/entity/Deck.kt - Groq API · Remote AI service used for content generation
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/remote/GroqService.kt - HTTP client · Platform-specific HTTP client wiring for remote calls
shared/src/commonMain/kotlin/com/avirajsharma/zenki/data/remote/HttpClientProvider.kt
UI layer
Compose screens, navigation, theming, and view models
- Navigation · Shared screen routing and app-level destination flow
shared/src/commonMain/kotlin/com/avirajsharma/zenki/navigation/AppNavigation.kt - App shell · Shared scaffold, bottom navigation, tabs, and snackbar surfaces
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/core/AppScaffold.kt - Theme system · Shared colors, shapes, typography, and theme mode support
shared/src/commonMain/kotlin/com/avirajsharma/zenki/theme/AppTheme.kt - Home · Deck overview and creation entry point
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/home/HomeScreen.kt - Deck detail · Deck contents and deck-level interactions
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/deck/DeckDetailScreen.kt - Card editor · Add and edit flashcards
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/card/AddEditCardScreen.kt - Study mode · Flashcard study session experience
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/study/StudyModeScreen.kt - Quiz mode · Quiz-oriented study flow
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/quiz/QuizModeScreen.kt - AI generate · AI-assisted card generation workflow
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/ai/AiGenerateScreen.kt - Settings · App preferences and configuration
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/screens/settings/SettingsScreen.kt - Home VM · Coordinates home screen state and deck actions
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/viewmodel/HomeViewModel.kt - Deck VM · Manages deck detail state and deck operations
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/viewmodel/DeckDetailViewModel.kt - Study VM · Coordinates study session state and progress
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/viewmodel/StudyViewModel.kt - Quiz VM · Coordinates quiz state and scoring flow
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/viewmodel/QuizViewModel.kt - AI VM · Drives AI generation requests and generated output
shared/src/commonMain/kotlin/com/avirajsharma/zenki/ui/viewmodel/AiGenerateViewModel.kt
Connections 40
- Android app → App entry: hosts · Android shell launches the shared app
- iOS app → iOS view: renders · Swift app presents the content view
- iOS view → Main VC: embeds · Content view mounts the Kotlin view controller
- Main VC → App entry: hosts · iOS bridge launches the shared app
- App entry → App module: composes · App root resolves dependencies through the composition root
- App entry → Navigation: starts · Shared app enters the navigation flow
- Navigation → App shell: uses · Navigation is presented inside the shared app shell
- App shell → Home: shows · Shell exposes the main home entry
- App shell → Settings: shows · Shell exposes settings as a top-level destination
- Navigation → Deck detail: routes · Navigation reaches deck detail screens
- Navigation → Card editor: routes · Navigation reaches card editing screens
- Navigation → Study mode: routes · Navigation reaches study mode
- Navigation → Quiz mode: routes · Navigation reaches quiz mode
- Navigation → AI generate: routes · Navigation reaches AI generation
- Home → Home VM: binds · Home screen is driven by its view model
- Deck detail → Deck VM: binds · Deck detail screen is driven by its view model
- Study mode → Study VM: binds · Study screen is driven by its view model
- Quiz mode → Quiz VM: binds · Quiz screen is driven by its view model
- AI generate → AI VM: binds · AI screen is driven by its view model
- Home VM → Deck repo: reads/writes · Home state uses deck operations
- Deck VM → Deck repo: reads/writes · Deck detail uses deck operations
- Deck VM → Card repo: reads/writes · Deck detail manages cards through the repository
- Study VM → Study repo: uses · Study flow persists and loads sessions
- Study VM → Card repo: reads · Study flow loads cards for review
- Quiz VM → Card repo: reads · Quiz flow loads cards for questions
- AI VM → Groq API: calls · AI workflow invokes the remote generation service
- Groq API → HTTP client: uses · Remote service is executed over the shared HTTP client
- Deck repo → Local DB: persists · Deck repository uses local storage
- Card repo → Local DB: persists · Card repository uses local storage
- Study repo → Local DB: persists · Study repository uses local storage
- Theme repo → Local DB: persists · Theme repository stores theme mode locally
- Local DB → DAOs: exposes · Database is accessed through DAO interfaces
- DAOs → Entities: maps · DAO contracts operate on local entities
- App module → Local DB: provides · Composition root wires database implementation
- App module → HTTP client: provides · Composition root wires the HTTP client
- App module → Deck repo: creates · Composition root assembles repositories
- App module → Card repo: creates · Composition root assembles repositories
- App module → Study repo: creates · Composition root assembles repositories
- App module → Theme repo: creates · Composition root assembles repositories
- Platform impls → Local DB: implements · Android and iOS source sets provide actual database wiring