How kekmacska/gamelibrary works
1. Overall shape
- This is a single Android app built in native Kotlin + Jetpack Compose.
- The architecture is a classic mobile layering: UI/screens → ViewModels → service/cache/providers → backend/API and local storage.
- There is no separate server code here; the app consumes an external backend that the README says is Laravel 12 with a MariaDB database.
2. App entry and navigation
- MainActivity.kt is the Android entry point.
- NavHost.kt centralizes screen routing with Navigation Compose, so navigation is a shared cross-cutting concern rather than being embedded inside individual screens.
- This is the top-level app shell that decides whether the user sees auth, main content, game details, or error states.
3. Feature screens
- The screens/ package contains the app’s primary user-facing flows:
- Login.kt, Register.kt for authentication
- Main.kt for the main game browsing experience
- GameDetails.kt for a selected game’s detail view
- Collectibles.kt for collectible-related data
- Error.kt for failure states
- These screens are the composition layer that binds ViewModel state to UI and orchestrates navigation.
4. State and presentation logic
- The viewModels/ package holds stateful presentation logic:
- Auth.kt handles login/register/session-related state
- Main.kt manages the main game list/search/browsing state
- Collectibles.kt manages collectible-specific state
- The ViewModels are the main boundary between Compose UI and data access; they likely expose observable state and user intents, keeping screens mostly declarative.
5. Backend/data access layer
- services/DataService.kt is the main data-fetching abstraction.
- This is the likely gateway to the remote backend API, keeping HTTP/network details out of UI and ViewModels.
- The README says networking uses Ktor Client, so this service layer is where API calls, request/response mapping, and serialization concerns live.
6. Models and serialized domain data
- models/ contains the app’s core data contracts:
- Game, Collectible, Publisher for catalog data
- User, Login, Register for auth/account flows
- These are the data shapes that flow from backend → service → ViewModel → screen, and they are probably also used for KotlinX serialization.
7. Local storage and session persistence
- preferences/UserPreferences.kt and cache/EncryptedUserPreferences.kt indicate persistent local storage for user/session data.
- cache/PublisherCache.kt suggests a small local cache for publisher-related data, likely to reduce repeated remote fetches.
- The “encrypted” preference layer is an important boundary: sensitive user state is stored separately from ordinary app state.
8. Platform and device-specific providers
- providers/ contains platform-adjacent utilities:
- BiometricAuthentication.kt for biometric sign-in / auth gating
- Clipboard.kt for copy/share interactions
- EmulatorDetection.kt for runtime device integrity checks
- Activity.kt for activity access/interop
- Validator.kt for input validation rules
- These are not core business logic, but they shape how the app behaves on-device and how auth/security flows are enforced.
9. Reusable UI components
- components/ is the app’s shared Compose widget library.
- It contains UI building blocks such as:
- GameCard, GameList, Table, SearchBar, PaginationBar
- ImageCarousel, ImageControls, FullScreenImage
- AuthScreenLayout, AuthTextField, SidebarLeft
- GithubIssuesLink for external navigation/help
- These components keep screens thin and consistent, especially for list/detail/search-heavy views.
10. Loading and skeleton states
- components/shimmer/ holds placeholder versions of key screens and image/text elements.
- This suggests the app uses a “loading skeleton” pattern while remote content is being fetched, which is a distinct UI state alongside success and error.
11. Theme and visual system
- themes/Theme.kt defines the app’s Material 3 styling, including dynamic color / Monet support mentioned in the README.
- The app is designed to inherit system colors where available, so theming is a cross-cutting presentation layer rather than a per-screen concern.
12. External integration and runtime dependencies
- The app depends on an external API backend configured via local.properties rather than checked into source control.
- It also uses Coil 3 for image loading, which means remote image URLs are a major data path for game artwork and detail screens.
- Serialization and networking are handled by Ktor Client + Kotlinx Serialization, which strongly influences the data boundary between backend responses and app models.
13. Functional flow to draw in an architecture diagram
- Typical flow is: Android activity → navigation host → screen → ViewModel → service/network or local cache → backend/local storage → state back to Compose UI.
- Auth flows additionally pass through biometric/provider and encrypted preferences.
- Content browsing flows pass through game/publisher models, caching, and image loading.
14. Key architectural boundaries
- UI boundary: screens/ and components/
- State boundary: viewModels/
- Data boundary: services/, cache/, preferences/
- Platform boundary: providers/
- Shared contract boundary: models/
- This separation is what makes the repo diagram-able as a layered Compose app rather than a monolithic UI dump.
Main entry points: Auth.kt Auth VM · DataService.kt DataService · NavHost.kt NavHost · Main.kt Main VM
Components 24
App shell
Android entry point and navigation scaffold.
- MainActivity · App launch activity and Compose host.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/MainActivity.kt - NavHost · Central screen routing for the app.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/NavHost.kt
UI layer
Screens, reusable Compose components, and theming.
- Main screen · Primary game browsing and search UI.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/screens/Main.kt - Login · Authentication sign-in screen.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/screens/Login.kt - Register · Account creation screen.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/screens/Register.kt - Game details · Selected game detail view.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/screens/GameDetails.kt - Collectibles · Collectible-related content and state display.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/screens/Collectibles.kt - Error · Failure and fallback UI state.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/screens/Error.kt - Theme · Material 3 styling and dynamic color setup.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/themes/Theme.kt
State layer
ViewModels coordinating UI state and user actions.
- Auth VM · Login, register, and session state.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/viewModels/Auth.kt - Main VM · Game browsing, search, and list state.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/viewModels/Main.kt - Collectibles VM · Collectible-specific state and actions.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/viewModels/Collectibles.kt
Data layer
Remote access, local storage, and caches.
- DataService · Remote API access and response mapping.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/services/DataService.kt - User prefs · Local session and user preference storage.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/preferences/UserPreferences.kt - Encrypted prefs · Encrypted user/session persistence.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/cache/EncryptedUserPreferences.kt - Publisher cache · Local cache for publisher data.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/cache/PublisherCache.kt
Platform helpers
Device-specific providers and runtime checks.
- Biometric auth · Biometric sign-in and auth gating.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/providers/BiometricAuthentication.kt - Validator · Input and form validation utilities.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/providers/Validator.kt
Domain models
Shared data contracts passed through the app.
- Game · Game catalog data contract.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/models/Game.kt - Collectible · Collectible domain contract.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/models/Collectible.kt - Publisher · Publisher domain contract.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/models/Publisher.kt - User · Authenticated user/account contract.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/models/User.kt - Login · Login request/response contract.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/models/Login.kt - Register · Registration request/response contract.
composeApp/src/main/kotlin/org/kekmacska/gamelibrary/models/Register.kt
Connections 33
- MainActivity → NavHost: hosts · Launch activity installs the navigation shell.
- NavHost → Login: routes · Navigation selects the auth flow.
- NavHost → Register: routes · Navigation selects the registration flow.
- NavHost → Main screen: routes · Navigation selects the main browsing flow.
- NavHost → Game details: routes · Navigation opens a selected game detail view.
- NavHost → Collectibles: routes · Navigation opens collectibles content.
- NavHost → Error: routes · Navigation falls back to error states.
- Main screen → Main VM: reads state · Main UI binds browsing and search state.
- Game details → Main VM: reads state · Detail UI shares game selection state.
- Collectibles → Collectibles VM: reads state · Collectibles UI binds to its ViewModel.
- Login → Auth VM: reads state · Login UI binds auth state and actions.
- Register → Auth VM: reads state · Register UI binds auth state and actions.
- Auth VM → DataService: auth API · Authentication flows call the remote API.
- Main VM → DataService: catalog API · Game browsing and search fetch remote content.
- Collectibles VM → DataService: collectibles API · Collectible data is fetched from the backend.
- Auth VM → User prefs: session · Session state is persisted locally.
- Auth VM → Encrypted prefs: secure session · Sensitive auth data uses encrypted storage.
- Main VM → Publisher cache: cache hits · Publisher lookups can reuse local cache.
- Auth VM → Biometric auth: gates login · Biometric checks can unlock auth flows.
- Auth VM → Validator: validates · Auth forms use shared validation rules.
- Register → Validator: validates · Registration inputs are validated before submit.
- Main screen → Theme: styles · Screens consume the shared Material theme.
- Login → Theme: styles · Auth screens share the app theme.
- Register → Theme: styles · Auth screens share the app theme.
- Game details → Theme: styles · Detail screens share the app theme.
- Main VM → Game: uses · Game state is shaped by the game model.
- Collectibles VM → Collectible: uses · Collectible state is shaped by the collectible model.
- DataService → Game: maps · Remote responses are mapped into game data.
- DataService → Collectible: maps · Remote responses are mapped into collectible data.
- DataService → Publisher: maps · Remote responses are mapped into publisher data.
- Auth VM → User: maps · Auth state is shaped by the user model.
- DataService → Login: maps · Login payloads use the login contract.
- DataService → Register: maps · Registration payloads use the register contract.