# nahid1126/book-orbit architecture

> Architecture diagram of the GitHub repository nahid1126/book-orbit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nahid1126/book-orbit
- Repository: https://github.com/nahid1126/book-orbit

## Overview

1. **What this repo is:**  
   Book Orbit is a single-module Android app built in Kotlin with Jetpack Compose. Architecturally it is organized like a clean/MVVM app inside the `app` module rather than split into multiple Gradle modules.

2. **Top-level layer separation:**  
   The codebase is divided into `ui`, `domain`, `data`, and `core`. `ui` owns Compose screens and ViewModels, `domain` defines repository contracts, `data` contains the concrete implementations and storage/network adapters, and `core` holds cross-cutting helpers such as results, logging, enums, constants, and exception utilities.

3. **Application bootstrap and DI:**  
   `BookOrbit.kt` is the app entry point, and dependency wiring is centralized in Koin modules under `data/di` (`AppModule`, `FirebaseModule`, `RepositoryModule`, `ViewModelModule`). This is the composition root that connects ViewModels to repository implementations and external services.

4. **Presentation layer shape:**  
   The UI is split by feature under `ui/presentation`: welcome, home, books, book details, gems, profile, and main. Each feature typically has a Compose screen plus a ViewModel, which means state is pushed into the UI via observable state rather than managed directly in composables.

5. **Navigation boundaries:**  
   Navigation is handled with Jetpack Compose Navigation in `ui/navigation`. There are separate navigation graphs for the welcome flow and the main app flow, which implies a gate between onboarding/authentication and the authenticated/book-browsing experience. `Destinations.kt` centralizes route definitions and type-safe argument passing.

6. **Key user flows:**  
   The app appears to start in a splash/welcome path (`WelcomeActivity`, `SplashScreen`, `LoginScreen`) and then transition into the main app (`MainActivity`, `NavGraph`). The main experience includes browsing books, opening book details, viewing PDFs, managing gems, checking purchase history, and visiting profile/legal screens.

7. **Domain and data contracts:**  
   The `domain/repository` package defines the repository interfaces for auth, books, gems, and billing. The concrete implementations live in `data/repository`, which keeps the UI and ViewModels insulated from Firebase, local storage, or billing SDK details.

8. **External service integrations:**  
   Firebase is an important backend dependency, evidenced by `google-services.json` and `FirebaseModule`. The app also integrates Google Play Billing through `BillingRepositoryImpl`, supporting gem purchases as a monetization path.

9. **Data persistence and models:**  
   Local state/persistence is handled through `data/local/AppPreference` and type converters. Remote-facing data shapes are defined in `data/remote/dto` for books, gems, and gem transactions, suggesting the app maps backend or cloud data into app-facing models through repository logic.

10. **State and concurrency model:**  
   The app uses Kotlin Coroutines and `StateFlow` for async work and UI state updates. This makes the data flow one-directional: user actions in Compose screens trigger ViewModel logic, which calls repositories, then emits new state back to the UI.

11. **Shared UI and error handling:**  
   Common Compose components such as dialogs, typography helpers, and bullet text live under `ui/presentation/component`. Shared runtime helpers in `core/utils` and `core/utils/exception` standardize result handling and exception translation across features.

12. **Architecture diagram summary:**  
   A useful diagram would show: Compose screens at the top, ViewModels beneath them, repository interfaces in the domain layer, repository implementations in the data layer, and then Firebase/local preference/Play Billing as external adapters. The app has two main navigation branches: welcome/auth and authenticated main app, with gems/billing acting as a side business flow connected to the content access experience.

Main entry points: [`app/src/main/java/com/nahid/book_orbit/ui/navigation/NavGraph.kt`](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/NavGraph.kt) (Nav graph), [`app/src/main/java/com/nahid/book_orbit/data/di`](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/di) (DI modules), [`app/src/main/java/com/nahid/book_orbit/BookOrbit.kt`](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/BookOrbit.kt) (BookOrbit), [`app/src/main/java/com/nahid/book_orbit/data/repository`](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/repository) (Repos)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App"]
  node_bookorbit["BookOrbit<br/>app entrypoint<br/>[BookOrbit.kt]"]
end

subgraph group_ui["UI"]
  node_welcome_activity["Welcome<br/>activity<br/>[WelcomeActivity.kt]"]
  node_main_activity["Main<br/>activity<br/>[MainActivity.kt]"]
  node_nav_graph["Nav graph<br/>navigation<br/>[NavGraph.kt]"]
  node_welcome_graph["Welcome graph<br/>navigation<br/>[WelcomeNavGraph.kt]"]
  node_destinations["Destinations<br/>routes<br/>[Destinations.kt]"]
  node_welcome_vm["Login VM<br/>viewmodel<br/>[LoginViewModel.kt]"]
  node_home_vm["Home VM<br/>viewmodel"]
  node_book_vm["Book VM<br/>viewmodel"]
  node_gems_vm["Gems VM<br/>viewmodel<br/>[GemsViewModel.kt]"]
  node_billing_vm["Billing VM<br/>viewmodel"]
  node_main_vm["Main VM<br/>viewmodel<br/>[MainViewModel.kt]"]
  node_compose_ui["Compose UI<br/>screens"]
end

subgraph group_domain["Domain"]
  node_auth_repo["Auth repo<br/>contract<br/>[AuthRepository.kt]"]
  node_book_repo["Book repo<br/>contract<br/>[BookRepository.kt]"]
  node_gems_repo["Gems repo<br/>contract<br/>[GemsRepository.kt]"]
  node_billing_repo["Billing repo<br/>contract"]
end

subgraph group_data["Data"]
  node_repo_impls["Repos<br/>implementations"]
  node_di_modules["DI modules<br/>koin modules"]
  node_prefs["Prefs<br/>local storage<br/>[AppPreference.kt]"]
  node_remote_dto["DTOs<br/>remote models"]
end

subgraph group_core["Core"]
  node_core_utils["Core utils<br/>helpers"]
end

subgraph group_external["External"]
  node_firebase[("Firebase<br/>backend")]
  node_play_billing["Play Billing<br/>payments"]
end

node_bookorbit -->|"initializes"| node_di_modules
node_bookorbit -->|"launches"| node_welcome_activity
node_bookorbit -->|"hosts"| node_main_activity
node_welcome_activity -->|"uses"| node_welcome_graph
node_main_activity -->|"uses"| node_nav_graph
node_nav_graph -->|"routes"| node_destinations
node_welcome_graph -->|"routes"| node_destinations
node_welcome_graph -->|"binds"| node_welcome_vm
node_nav_graph -->|"binds"| node_home_vm
node_nav_graph -->|"binds"| node_book_vm
node_nav_graph -->|"binds"| node_gems_vm
node_nav_graph -->|"binds"| node_billing_vm
node_nav_graph -->|"binds"| node_main_vm
node_welcome_vm -->|"depends on"| node_auth_repo
node_home_vm -->|"depends on"| node_book_repo
node_book_vm -->|"depends on"| node_book_repo
node_gems_vm -->|"depends on"| node_gems_repo
node_billing_vm -->|"depends on"| node_billing_repo
node_main_vm -->|"depends on"| node_auth_repo
node_di_modules -->|"provides"| node_auth_repo
node_di_modules -->|"provides"| node_book_repo
node_di_modules -->|"provides"| node_gems_repo
node_di_modules -->|"provides"| node_billing_repo
node_repo_impls -->|"reads/writes"| node_firebase
node_repo_impls -->|"persists"| node_prefs
node_repo_impls -->|"maps"| node_remote_dto
node_billing_repo -->|"adapts"| node_play_billing
node_compose_ui -->|"uses"| node_core_utils

click node_bookorbit "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/BookOrbit.kt"
click node_welcome_activity "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/welcome/WelcomeActivity.kt"
click node_main_activity "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/main/MainActivity.kt"
click node_nav_graph "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/NavGraph.kt"
click node_welcome_graph "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/WelcomeNavGraph.kt"
click node_destinations "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/Destinations.kt"
click node_welcome_vm "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/welcome/login/LoginViewModel.kt"
click node_home_vm "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/home/HomeScreenViewModel.kt"
click node_book_vm "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/book_details/BookDetailsViewModel.kt"
click node_gems_vm "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/gams/GemsViewModel.kt"
click node_billing_vm "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/gams/BillingViewModel.kt"
click node_main_vm "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/main/MainViewModel.kt"
click node_auth_repo "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/AuthRepository.kt"
click node_book_repo "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/BookRepository.kt"
click node_gems_repo "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/GemsRepository.kt"
click node_billing_repo "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/BillingRepository.kt"
click node_repo_impls "https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/repository"
click node_di_modules "https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/di"
click node_prefs "https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/data/local/AppPreference.kt"
click node_remote_dto "https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/remote/dto"
click node_core_utils "https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/core/utils"
click node_compose_ui "https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/ui/presentation"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bookorbit toneBlue
class node_welcome_activity,node_main_activity,node_nav_graph,node_welcome_graph,node_destinations,node_welcome_vm,node_home_vm,node_book_vm,node_gems_vm,node_billing_vm,node_main_vm,node_compose_ui toneAmber
class node_auth_repo,node_book_repo,node_gems_repo,node_billing_repo toneMint
class node_repo_impls,node_di_modules,node_prefs,node_remote_dto toneRose
class node_core_utils toneIndigo
class node_firebase,node_play_billing toneTeal
```

## Components

### App

Android app module and entrypoints

- [BookOrbit](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/BookOrbit.kt): app entrypoint · Application bootstrap and DI initialization · `app/src/main/java/com/nahid/book_orbit/BookOrbit.kt`

### UI

Compose presentation and navigation

- [Welcome](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/welcome/WelcomeActivity.kt): activity · Entry activity for splash and login flow · `app/src/main/java/com/nahid/book_orbit/ui/presentation/welcome/WelcomeActivity.kt`
- [Main](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/main/MainActivity.kt): activity · Host activity for the authenticated app · `app/src/main/java/com/nahid/book_orbit/ui/presentation/main/MainActivity.kt`
- [Nav graph](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/NavGraph.kt): navigation · Main app navigation shell · `app/src/main/java/com/nahid/book_orbit/ui/navigation/NavGraph.kt`
- [Welcome graph](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/WelcomeNavGraph.kt): navigation · Onboarding and login navigation flow · `app/src/main/java/com/nahid/book_orbit/ui/navigation/WelcomeNavGraph.kt`
- [Destinations](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/navigation/Destinations.kt): routes · Central route and argument definitions · `app/src/main/java/com/nahid/book_orbit/ui/navigation/Destinations.kt`
- [Login VM](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/welcome/login/LoginViewModel.kt): viewmodel · State and actions for login · `app/src/main/java/com/nahid/book_orbit/ui/presentation/welcome/login/LoginViewModel.kt`
- [Home VM](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/home/HomeScreenViewModel.kt): viewmodel · State for the home dashboard · `app/src/main/java/com/nahid/book_orbit/ui/presentation/home/HomeScreenViewModel.kt`
- [Book VM](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/book_details/BookDetailsViewModel.kt): viewmodel · State and actions for book details · `app/src/main/java/com/nahid/book_orbit/ui/presentation/book_details/BookDetailsViewModel.kt`
- [Gems VM](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/gams/GemsViewModel.kt): viewmodel · State for gems and history · `app/src/main/java/com/nahid/book_orbit/ui/presentation/gams/GemsViewModel.kt`
- [Billing VM](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/gams/BillingViewModel.kt): viewmodel · Purchase flow orchestration · `app/src/main/java/com/nahid/book_orbit/ui/presentation/gams/BillingViewModel.kt`
- [Main VM](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/ui/presentation/main/MainViewModel.kt): viewmodel · Shared app-level state · `app/src/main/java/com/nahid/book_orbit/ui/presentation/main/MainViewModel.kt`
- [Compose UI](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/ui/presentation): screens · Feature screens, shared components, and theme · `app/src/main/java/com/nahid/book_orbit/ui/presentation`

### Domain

Repository contracts

- [Auth repo](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/AuthRepository.kt): contract · Authentication repository interface · `app/src/main/java/com/nahid/book_orbit/domain/repository/AuthRepository.kt`
- [Book repo](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/BookRepository.kt): contract · Book access repository interface · `app/src/main/java/com/nahid/book_orbit/domain/repository/BookRepository.kt`
- [Gems repo](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/GemsRepository.kt): contract · Gems balance and history interface · `app/src/main/java/com/nahid/book_orbit/domain/repository/GemsRepository.kt`
- [Billing repo](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/domain/repository/BillingRepository.kt): contract · Billing and purchase repository interface · `app/src/main/java/com/nahid/book_orbit/domain/repository/BillingRepository.kt`

### Data

Implementations, persistence, and adapters

- [Repos](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/repository): implementations · Concrete repository implementations · `app/src/main/java/com/nahid/book_orbit/data/repository`
- [DI modules](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/di): koin modules · Composition root for app wiring · `app/src/main/java/com/nahid/book_orbit/data/di`
- [Prefs](https://github.com/nahid1126/book-orbit/blob/master/app/src/main/java/com/nahid/book_orbit/data/local/AppPreference.kt): local storage · App preference and type conversion layer · `app/src/main/java/com/nahid/book_orbit/data/local/AppPreference.kt`
- [DTOs](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/data/remote/dto): remote models · Remote-facing data shapes for books and gems · `app/src/main/java/com/nahid/book_orbit/data/remote/dto`

### Core

Shared runtime helpers

- [Core utils](https://github.com/nahid1126/book-orbit/tree/master/app/src/main/java/com/nahid/book_orbit/core/utils): helpers · Results, logging, constants, enums, and exceptions · `app/src/main/java/com/nahid/book_orbit/core/utils`

### External

Third-party services

- **Firebase**: backend · Cloud auth and data backend
- **Play Billing**: payments · Google Play purchase SDK

## Connections

- BookOrbit → DI modules: initializes · Application startup wires dependencies
- BookOrbit → Welcome: launches · Entry flow starts in welcome path
- BookOrbit → Main: hosts · Authenticated flow enters main activity
- Welcome → Welcome graph: uses · Welcome activity renders onboarding graph
- Main → Nav graph: uses · Main activity hosts app navigation
- Nav graph → Destinations: routes · Navigation graph consumes central route definitions
- Welcome graph → Destinations: routes · Welcome flow uses shared destinations
- Welcome graph → Login VM: binds · Login state is provided by ViewModel
- Nav graph → Home VM: binds · Home screen state comes from ViewModel
- Nav graph → Book VM: binds · Book details screen uses ViewModel
- Nav graph → Gems VM: binds · Gems and history screens use ViewModel
- Nav graph → Billing VM: binds · Purchase flow uses billing ViewModel
- Nav graph → Main VM: binds · Shared app state is owned by main ViewModel
- Login VM → Auth repo: depends on · Authentication logic is abstracted behind contract
- Home VM → Book repo: depends on · Book browsing reads through repository contract
- Book VM → Book repo: depends on · Book detail retrieval goes through contract
- Gems VM → Gems repo: depends on · Gems balance and history come from contract
- Billing VM → Billing repo: depends on · Purchase flow delegates to billing contract
- Main VM → Auth repo: depends on · App-level state may depend on auth status
- DI modules → Auth repo: provides · Koin binds contract to implementation
- DI modules → Book repo: provides · Koin binds contract to implementation
- DI modules → Gems repo: provides · Koin binds contract to implementation
- DI modules → Billing repo: provides · Koin binds contract to implementation
- Repos → Firebase: reads/writes · Repository implementations integrate with backend
- Repos → Prefs: persists · Repository implementations use local storage
- Repos → DTOs: maps · Repository implementations map remote data shapes
- Billing repo → Play Billing: adapts · Billing implementation wraps Google Play Billing
- Compose UI → Core utils: uses · Shared UI and runtime helpers support features