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: Seff-hosted, Google Drive, WebDAV, MinIO, S3
Accessibility	E-ink optimization, dark/light themes, customizable fonts

Supported platforms

Platform	Status	Notes
Android	Supported	Primary mobile target
iOS	Supported	Requires Xcode for building
Web	Supported	PWA with offline support
Windows	Supported	Native desktop experience
macOS	Supported	Requires Xcode for building
Linux	Supported	AppImage/Snap distribution

Getting started

Prerequisites

• Flutter SDK 3.x: Installation guide
• Dart SDK 3.x: Included with Flutter

Installation

1. Clone the repository

   git clone git@github.com:Eoic/Papyrus.git
   cd Papyrus

2. Install dependencies

   cd client
   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

Documentation

Project documentation is available in the /spec/ directory and can be built into a browsable static site using MkDocs.

# Install documentation dependencies
pip install -r docs-requirements.txt

# Serve documentation locally (http://127.0.0.1:8000)
mkdocs serve

# Build static site
mkdocs build

Technology stack

Layer	Technology	Purpose
Frontend	Flutter / Dart	Cross-platform UI
Backend	FastAPI / Python	REST API server
Database	PostgreSQL	Primary data store
Cache	Redis	Sessions, caching
Storage	Multiple backends	Book file storage

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:

   cd client
   dart format .
   dart analyze
   flutter test

3. Commit your changes and push:

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

4. Open a pull request

Code style

• Run dart format . before committing
• Ensure dart analyze passes with no issues
• Use sentence case for UI text (e.g., "Apply filters" not "Apply Filters")

Releases

Releases are automated via GitHub Actions. To create a new release:

1. Ensure all changes are merged to master

2. Create and push a version tag:

   git tag v1.2.3
   git push origin v1.2.3

3. GitHub Actions will automatically:

   • Build all platforms (Android, Web, Linux, Windows)
   • Create a GitHub Release with auto-generated release notes
   • Attach versioned artifacts to the release

Resources

Resource	Description
Documentation	Full project specification
API specification	OpenAPI/Swagger definition
Figma prototype	UI/UX design
Trello board	Project management

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.