EPUB reading

Read books with rich formatting, embedded fonts, and images across Android, iOS, and the web. ReadRealm fetches and renders EPUB and plain-text content from Project Gutenberg.

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

Android

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.

iOS

The iOS client is built with Swift. The reader fetches the text content and renders it using Swift’s native text layout engine, providing a familiar reading experience consistent with the rest of the iOS system UI.

Web / Admin Dashboard

The Flutter admin dashboard runs on web and desktop. It loads book text from the same API endpoint and displays it using Flutter’s text rendering pipeline, which produces consistent output across macOS, Windows, and web browsers.

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:

Field	Description
title	Book title
author	Primary author name
publicationYear	Year of first publication
numOfPages	Median page count
coverImage	Cover image from Open Library
genre	Primary subject/genre
description	AI-generated five-line summary
averageRating	Mean rating from all reader reviews
totalReviews	Number of reviews submitted
link	Direct URL to book text content