A cross-platform book management application

---

Overview

Papyrus is an open-source, cross-platform application for managing and reading books. It supports both physical and digital book collections across Android, iOS, Web, Windows and Linux. The application features an integrated book reader, flexible organization tools, reading statistics, progress tracking, supports various file storage back-ends and cross-device synchronization via a self-hostable server.

Why Papyrus?

Many reading applications offer partial solutions but fall short on essential features, platform availability or user experience. Papyrus aims to deliver a comprehensive, privacy oriented solution that:

• Works offline-first with optional cloud synchronization
• Supports self-hosting for complete data ownership
• Provides a unified experience across all popular platforms
• Offers extensive customization for different reading preferences

Features

Category	Features
Reading	Integrated viewer for EPUB, PDF, MOBI, AZW3, TXT, CBR, CBZ
Organization	Shelves, tags, topics, custom filters, advanced search
Annotations	Highlights, bookmarks, notes with export capabilities
Progress	Reading time tracking, page/percentage progress, statistics
Goals	Reading goals (books, pages, time) with streak tracking
Sync	Cross-device synchronization via self-hostable server
Storage	Multiple backends: self-hosted, Google Drive, WebDAV, S3
Accessibility	E-ink optimization, dark/light themes, customizable fonts

Supported platforms

• Android
• iOS
• macOS
• Linux
• Windows
• Web

Getting started

Prerequisites

• Flutter SDK 3.x: Installation guide

Installation

1. Clone the repository

   git clone git@github.com:PapyrusReader/client.git
   cd client

2. Install dependencies

   cd app
   flutter pub get

3. Run the application

   # Android/iOS (with connected device or emulator)
   flutter run
   
   # Web
   flutter run -d chrome
   
   # Desktop
   flutter run -d windows  # or: macos, linux

Running with the back-end

When the user signs in, the Flutter client communicates with the Papyrus server for auth and asks the server for PowerSync credentials.

Run the server and PowerSync locally, then start Flutter with:

cd ../server
./scripts/bootstrap_local.sh
cd ../client/app
flutter run -d chrome --web-hostname papyrus.localhost --web-port 3000 --dart-define-from-file=.dart_defines

Authenticated books use papyrus-account.db and synchronize through PowerSync. Guest mode uses the separate local-only papyrus-guest.db; guest books remain on that device and are not merged into an account.

For local web auth links, add these entries to /etc/hosts:

127.0.0.1 papyrus.localhost
::1 papyrus.localhost

See server/docs/flutter-auth-integration.md for the full integration guide.

Documentation

See PapyrusReader/docs.

Technology stack

Layer	Technology
Frontend	Flutter / Dart
Backend	FastAPI / Python
Database	PostgreSQL
Cache	Redis
File storage	Multiple (e.g., Google Drive, S3, OPFS, self-hosted)

Contributing

Setup

1. Fork and clone the repository

2. Install git hooks for code quality checks:

   ./scripts/setup-hooks.sh

   This installs a pre-commit hook that runs dart format and dart analyze before each commit.

Development workflow

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes and ensure quality checks pass:

   dart format .
   dart analyze
   flutter test

3. Commit your changes and push:

   git commit -m "feat: description of your changes"
   git push origin feature/your-feature-name

4. Open a pull request

Resources

Repository	Description
server	Back-end for self-hosted sync and file storage
website	Landing page
docs	Documentation