Parchment README

The project's README from github.com/AhmadHassan-BTed/Parchment. As one markdown file: README.md.

Parchment

A Soulful PDF Reading Experience for Android

CI License Android Kotlin Maintainer

Reading is a sacred act of connection.
Parchment was engineered to remove the digital friction between the reader and the text.
It brings the warmth of physical paper to the precision of modern Android engineering.

Explore Architecture • View Roadmap • Contribute

The Vision

Digital PDF readers often feel cold and industrial. Parchment, envisioned and engineered by Ahmad Hassan (B-Ted), prioritizes the human element. By utilizing a "Warm Paper" design system and a gesture-driven interface, it replicates the focused, undistracted environment of a physical library.

Feature Ecosystem

Feature Technical Implementation Human Value
Warm Aesthetic Custom HSL-tailored Design System Reduces digital eye strain
Parchment Engine Android PdfRenderer + 2× Super-sampling Keeps text crisp at any zoom level
Interactive TOC Flexible TocItem Model Quick, outline-based navigation
Smart HUD Auto-hiding gesture-aware UI Maximum immersion, zero clutter
Fluid Navigation LazyColumn + Haptic Feedback loops Tactile sense of progress
Persistence Synchronized SharedPreferences layer Never lose your place in a text

Architecture Overview

The system is built on a strict Modular Layered Architecture. This ensures 100% cohesion and zero coupling between the rendering engine and the data source.

graph TD
    subgraph Presentation_Layer [UI & Presentation]
        Main[MainActivity] --> Viewer[PdfViewerScreen]
        Viewer --> Comp[Extracted UI Modules]
        Comp --> Tokens[Design Tokens]
    end

    subgraph Domain_Layer [Business Logic]
        Viewer --> Repo[BookRepository]
        Viewer --> Prefs[ReadingPreferences]
    end

    subgraph Data_Layer [Resources]
        Repo --> Config[BookConfig Model]
        Config --> Assets[PDF Assets]
    end

    style Presentation_Layer fill:#F8F1E4,stroke:#8B6914,stroke-width:2px
    style Domain_Layer fill:#F0E8D8,stroke:#6B5E4F,stroke-width:2px
    style Data_Layer fill:#E8DFCC,stroke:#5A6340,stroke-width:2px

Request & Data Flow

When a reader opens a book, the following lifecycle is executed to ensure a sub-100ms "Time to First Page."

Page Rendering Lifecycle

sequenceDiagram
    participant U as User
    participant V as ViewerScreen
    participant Util as PdfUtils
    participant R as PdfRenderer
    participant P as PdfPageRenderer

    U->>V: Selects Book
    V->>Util: Request FileDescriptor
    Util->>Util: Copy Asset to Cache (if needed)
    Util-->>V: Return Descriptor
    V->>R: Initialize Native Engine
    V->>P: Render Page 0..N
    loop Synchronized Rendering
        P->>R: openPage(index)
        R-->>P: Render Bitmap (2x Res)
        P->>P: Apply Night Mode Filter
    end
    P-->>U: Display Fluid Page

Repository Structure

The project is structured to favor feature-first discovery. Contributors can locate logic within seconds.

root/
├── .github/                # CI/CD Workflows & Templates
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── assets/     # Bundled PDF documents
│   │   │   └── java/ted/parchment/reader/
│   │   │       ├── data/   # Models, Prefs, Repositories
│   │   │       ├── ui/     # Themed screens & components
│   │   │       └── utils/  # Hardware/File IO Utilities
│   └── build.gradle.kts    # Modular build config
├── docs/                   # Architectural deep-dives
└── README.md               # You are here

Technical Pipeline

Build & Deployment

The project utilizes a professional GitHub Actions pipeline for every commit to ensure structural integrity.

graph LR
    Push[Push/PR] --> Lint[Linting Check]
    Lint --> Build[Debug Build]
    Build --> Test[Unit Tests]
    Test --> Result{Success?}
    Result -- Yes --> Merge[Ready to Merge]
    Result -- No --> Fix[Notify Maintainer]

Development Workflow

New contributions are welcomed. The repository is maintained with a high bar for engineering standards.

1. Development Setup
  • IDE: Android Studio Ladybug+
  • JDK: 17
  • SDK: 36 (target), 28 (min)
  • Commands:
    ./gradlew assembleDebug  # Build
./gradlew test           # Verify
2. Module Relationship Guide
Module Responsibility
PdfViewerScreen Orchestrates navigation and HUD states
VerticalZoomBar Custom Canvas-based scaling controller
PdfPageRenderer Native-to-Bitmap bridge with memory management
BookRepository Single source of truth for all book metadata

Acknowledgments & Ethics

Parchment is an original work by Ahmad Hassan (B-Ted).
It is built with a commitment to privacy:

Built for the love of reading.
Engineered by Ahmad Hassan (B-Ted)

Parchment (AhmadHassan-BTed/Parchment)

Searching Database…

1.2K ·GitHub
Parchment
What is this?Parchment is a native Android PDF reader built with Kotlin and Jetpack Compose, designed around a warm, paper-like aesthetic and a gesture-driven reading experience rather than a clinical, industrial UI.
How do I get this running on my device?You build it from source in Android Studio: clone the repo, open it in Android Studio Ladybug or newer, make sure JDK 17 and Android SDK 36 are installed, then run the app on an emulator or device.
What do I need installed to build it?Android Studio Ladybug or a newer version, JDK 17, and Android SDK 36 as the target (min SDK 28) are required to build the project.
Does the app track or send my reading data anywhere?No — Parchment makes zero network calls and has no analytics or telemetry, so your reading activity stays entirely on your device.
What makes the PDF rendering fast and crisp?It uses Android's native PdfRenderer combined with 2x super-sampling to keep text sharp at any zoom, aiming for a sub-100ms 'Time to First Page' when opening a book.
How is the codebase organized?It follows a strict Modular Layered Architecture meant to keep the rendering engine and data layer fully decoupled, so contributors can find logic quickly.
Can I jump around a PDF using a table of contents?Yes, there's an interactive TOC built on a flexible TocItem model for quick outline-based navigation.
What are similar projects?AhSilence, vivi-music, LastWave-Native, mihon, YumaPlayer, Shizuku-Next, Metrolist, YunX
Which topics is it in?material3, clean-architecture, ux, reader, jetpack-compose, apk, on-device, software-engineering, ui-design, offline-first, native, privacy-first
Creator
AhmadHassan-BTed
Size
67.2 MB
Stars
1.2K
Updated
CommitJun 30
Age
5mo
Commits · 90 Days