App Development Documentation

Repository

Project Setup

This project is an Android app written in Kotlin, built with Gradle.

Tech Stack (overview)

  • Kotlin (Android)
  • Gradle build system
  • Jetpack components (ViewModels)
  • Room (local persistence)
  • Retrofit (remote API calls)

Codebase Structure (high level)

  • JabaApplication.kt: Application entry point (app-wide initialization).
  • MainActivity.kt: Main Android activity hosting the UI.
  • data/
    • local/: Room database layer
      • BookDatabase.kt: Room database definition
      • dao/: Data access objects (e.g., BookDao.kt, ShelfDao.kt)
      • entity/: Room entities and relations (e.g., BookEntity.kt, ShelfEntity.kt, ReadingEntryEntity.kt, BookShelfCrossRef.kt, BookWithHistory.kt)
      • Converters.kt: Room type converters
    • remote/: Networking layer
      • OpenLibraryApi.kt: Retrofit API interface
      • RetrofitClient.kt: Retrofit client configuration
      • Dto.kt: Network DTOs
    • repository/: Repository abstraction (e.g., BookRepository.kt) that coordinates local/remote data sources
    • datastore/: DataStore persistence for simple settings/state (e.g., CheckInDataStore.kt)
  • ui/
    • AppViewModel.kt, ViewModelFactory.kt: Shared application state and ViewModel wiring
    • screens/: Screen-specific UI + ViewModels (e.g., LibraryScreen.kt, BookDetailsScreen.kt, AddBookScreen.kt, etc.)
    • components/: Reusable UI components (e.g., GlobalSearchBar.kt)
    • theme/: UI theme definitions (Color.kt, Theme.kt, Type.kt)
  • utils/: Helpers such as BarcodeUtils.kt, ConnectivityObserver.kt

Build \& Run (local)

  1. Open the project root in Android Studio.
  2. Ensure the Android SDK is configured for the IDE and a device/emulator is available.
  3. Configure GitHub username and password (process described at the top of the index page of our documentation).
  4. Sync Gradle (imports the Android/Gradle configuration).
  5. Run the app configuration (launches MainActivity).

Data \& Persistence

  • Books, shelves, and reading history are stored locally via Room (data/local/**).
  • Remote lookups are performed via Retrofit (data/remote/**) against the OpenLibrary API.
  • Data access is routed through data/repository/BookRepository.kt to keep UI and storage decoupled.

Entity Relationship Diagram

erDiagram BOOKS ||--o{ READING_ENTRIES : "has" BOOKS ||--o{ BOOK_SHELF_CROSS_REF : "belongs_to" SHELVES ||--o{ BOOK_SHELF_CROSS_REF : "contains" BOOKS { string isbn PK string title string author string coverUrl int pages string attachedFileName string attachedFileType } READING_ENTRIES { long id PK string bookIsbn FK string status int rating string review long startDate long finishDate } SHELVES { long id PK string name } BOOK_SHELF_CROSS_REF { string isbn FK long shelfId FK }