Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aliammari1/readrealm/llms.txt

Use this file to discover all available pages before exploring further.

ReadRealm provides a reading experience that works across every platform. Books are sourced from Project Gutenberg via the Gutendex API and rendered natively on Android (Kotlin), iOS (Swift), and through the web interface. You get rich text formatting, images where available, and reading progress that stays in sync.

Android

Native reader built with Kotlin and Jetpack Compose.

iOS

Native reader built with Swift.

Book discovery

Automatic link resolution from Gutendex.

Progress sync

Your position in a book syncs across all devices.

​
How books are fetched

When you open a book, ReadRealm looks up the book on the Gutendex API (a Project Gutenberg catalog) by title. The service checks the available formats in this order:
  1. text/plain; charset=us-ascii
  2. text/plain; charset=utf-8
  3. text/plain
If none of these formats are available, no reading link is returned for that title. The match is flexible — the service accepts a book if its title contains your search term or vice versa, so minor variations in capitalization or punctuation still resolve correctly. 
GET /book/details/{id}
The response includes a link field containing the direct URL to the book’s text content when available: 
{
  "id": 2701,
  "title": "Moby Dick",
  "author": "Herman Melville",
  "publicationYear": 1851,
  "numOfPages": 654,
  "coverImage": "https://covers.openlibrary.org/b/id/8231856-M.jpg",
  "genre": "Fiction",
  "link": "https://www.gutenberg.org/files/2701/2701-0.txt",
  "description": "A five-line AI-generated summary appears here."
}
The link field is only populated when Gutendex has a plain-text version of the book. Some titles may not have a readable link if they are outside the Project Gutenberg catalog.

​
Platform rendering

The Android client is built with Kotlin and Jetpack Compose. The reader loads the plain-text content from the link URL and renders it in a scrollable, styled view. Compose handles text layout, line spacing, and font rendering natively.

​
What the EPUB service does

The backend EPUB service (epub.service.ts) is responsible for resolving a human-readable book title into a direct download link. It:
  1. URL-encodes the title and queries https://gutendex.com/books?search={title}
  2. Searches the results for a book whose title closely matches the query
  3. Returns the first available plain-text format URL
  4. Returns an empty string if no match is found, so the reading link is gracefully omitted
This resolution happens automatically when you load a book’s detail page or when a genre shelf is populated — you do not need to provide a link manually.

​
Reading progress

Reading progress is tied to your user account and syncs across devices. When you return to a book on a different device, ReadRealm picks up where you left off.
Bookmarks are separate from reading progress. A bookmark saves the book to your reading list; your reading position within the book is tracked independently. See Library management for details on bookmarks.

​
Book details page

Before opening a book to read, you can review its details:
FieldDescription
titleBook title
authorPrimary author name
publicationYearYear of first publication
numOfPagesMedian page count
coverImageCover image from Open Library
genrePrimary subject/genre
descriptionAI-generated five-line summary
averageRatingMean rating from all reader reviews
totalReviewsNumber of reviews submitted
linkDirect URL to book text content

Build docs developers (and LLMs) love

Get started for freeTalk to us