Parchment README

README проекта с github.com/AhmadHassan-BTed/Parchment. Одним файлом markdown: 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)

Ищем в базе…

Что это такое?Parchment — нативная для Android читалка PDF, написанная на Kotlin и Jetpack Compose. Её дизайн построен на тёплой эстетике, похожей на бумагу, и на удобном чтении с помощью жестов, а не на строгом, технически холодном интерфейсе.
Как запустить это на своём устройстве?Соберите приложение из исходного кода в Android Studio: клонируйте репозиторий, откройте его в Android Studio Ladybug или более новой версии, убедитесь, что установлены JDK 17 и Android SDK 36, а затем запустите приложение на эмуляторе или устройстве.
Что нужно установить для сборки?Для сборки проекта требуются Android Studio Ladybug или более новая версия, JDK 17 и Android SDK 36 в качестве целевой платформы (минимальный SDK 28).
Приложение отслеживает или куда-либо отправляет данные о моём чтении?Нет — Parchment не делает ни одного сетевого запроса и не имеет аналитики или телеметрии, поэтому ваша активность при чтении полностью остаётся на вашем устройстве.
За счёт чего рендеринг PDF работает быстро и чётко?Он использует встроенный в Android PdfRenderer вместе с 2x-суперсэмплингом, чтобы текст оставался чётким при любом масштабе. Цель — время до первой страницы («Time to First Page») менее 100 мс при открытии книги.
Как организован код?Проект построен по строгой модульной многослойной архитектуре, которая полностью разделяет движок рендеринга и слой данных, чтобы участникам было легче быстро находить нужную логику.
Можно ли перемещаться по PDF с помощью оглавления?Да, есть интерактивное оглавление на основе гибкой модели TocItem для быстрой навигации по структуре документа.
Какие есть похожие проекты?AhSilence, vivi-music, LastWave-Native, mihon, YumaPlayer, Shizuku-Next, essentials, Metrolist
Размер
67.2 MB
Звёзды
3.6K
Обновлён
КоммитNov 10
Возраст
6 мес
Коммиты · 90 дней