🇬🇧 English · 🇩🇪 Deutsch
Organize, preview, and bundle local documents by topic — references and read status only, originals stay put.
Note
DokuReader is part of the doc-bricks local document management suite. It works seamlessly alongside LitZentrum (citation & literature management), CleanMarkdown (Markdown reading & editing), and UniversalDocsGrabber (mail attachment intake). DokuReader is fully indexed for AI/LLM coding assistants via llms.txt.
- Overview & Core Value
- Key Capabilities & Feature Matrix
- Interactive Architecture Flowchart
- Target Personas & High-Intent Discoverability Queries
- Comparative Matrix vs. Alternatives
- Document Lifecycle & Privacy Sequence
- Getting Started & Installation
- Supported Formats & System Dependencies
- Windows Store & Standalone Build
- Mobile & PWA Companion
- Governance & Runtime Invariants
- Sibling Tools & Ecosystem Matrix
- Privacy & Security Posture
- Quality Gates & Automated Test Suites
- Machine-Readable Context (
llms.txt) - Third-Party Licenses & Transparency
- Marketing & Discoverability Strategies / Log
- Statutory Notice, Liability Limitation & License
DokuReader is an unprivileged desktop application for organizing, previewing, and bundling documents by topic. Original files stay exactly where they are; the application indexes only file path references and read status in a local JSON state file (~/.dokubibliothek_state.json).
It is engineered specifically for private document libraries, academic research collections, confidential legal discovery sets, and topic-based reading queues that must remain 100% offline, inspectable, and secure.
| Goal | Entry Point |
|---|---|
| Run the desktop application | python DokuReader.py or START.bat |
| Understand the export specification | EXPORTFORMAT.md |
| Test the desktop source build | python tests/source_platform_smoke.py |
| Check the mobile/PWA companion smoke | web_companion/README.md |
| Check Windows Store readiness | python _WARTUNG/check_store_readiness.py --allow-blockers |
| Prepare or parse WACK reports | python _WARTUNG/run_windows_wack.py --dry-run |
| Prepare Windows Store listings | STORE_LISTING.md, PRIVACY_POLICY.md, SUPPORT.md |
| Provide LLM tools project context | llms.txt |
The version roles are intentionally separate and read back from the current source tree:
- Development Runtime:
1.0.1-dev(DokuReader.pyandpyproject.toml1.0.1.dev0) - Windows Store Package Metadata:
1.0.1.0(store_package.json) - Release Verification: There is no verified public release artifact in this repository. Signing, MSIX generation, WACK validation, and Store submission remain external gates. The
1.0.1-devbadge indicates development status, not a public store release claim. See RELEASE_STATUS.md and PORTIERUNGSPLAN.md.
- In-Place File Protection (INV-INPLACE-03): Original documents are never copied, moved, modified, or overwritten.
- Dynamic Topic Organization: Create, rename, sort, and delete document topics on the fly.
- Read / Unread Queue Management: Toggle read status with one click; filter exports by read, unread, or all.
- Multi-Format Instant Preview: In-app visual preview for PDFs, text files, images (JPG, PNG, GIF), and Office documents (DOCX, ODT).
- Text Preview & Latin-1 Fallback: Robust text rendering with UTF-8 primary and Latin-1 secondary decoding.
- Desktop Drag-and-Drop: Intuitive document intake when
tkinterdnd2is installed. - External App Dispatch: Double-click opens any document in the system default application.
- Consolidated PDF Bundling: Merge selected read, unread, or all documents into a single consolidated PDF bundle.
- Clean JSON Metadata Export: Export the entire library outline as schema-compliant
dokureader-library-v1.jsonwithout copying or embedding binary document content. - Office Conversion Pipeline: Seamless conversion of Office formats via headless LibreOffice or Windows Word COM.
- Offline PWA Companion: Zero-egress mobile web application for reviewing libraries and toggling read status on smartphones and tablets.
flowchart TD
subgraph Host ["Local Workstation Environment (Windows · macOS · Linux)"]
subgraph App ["DokuReader Application Layer"]
UI["Tkinter Desktop UI (DokuReader.py)"]
StateManager["Local State Manager"]
PreviewEngine["Preview Engine"]
ExportEngine["Export & Bundling Engine"]
end
subgraph Backends ["Processing & Preview Backends"]
MuPDF["PyMuPDF (PDF Render Engine)"]
PIL["Pillow (Image Processing)"]
OfficeConv["LibreOffice / MS Word (COM / Subprocess)"]
PDFMerger["pypdf / reportlab (PDF Generation)"]
end
subgraph Storage ["Local Storage & Privacy Boundary"]
Originals[("Original Documents (Read-Only In-Place)")]
StateFile[("~/.dokubibliothek_state.json")]
ExportFile[("dokureader-library-v1.json")]
PDFOutput[("Consolidated PDF Bundle")]
end
end
subgraph Companion ["PWA Mobile Companion (web_companion)"]
PWA["Local PWA Client (Offline Cache)"]
end
UI --> StateManager
UI --> PreviewEngine
UI --> ExportEngine
StateManager <--> StateFile
PreviewEngine --> MuPDF
PreviewEngine --> PIL
PreviewEngine --> OfficeConv
PreviewEngine -. Read-Only .-> Originals
ExportEngine --> PDFMerger
ExportEngine --> ExportFile
PDFMerger --> PDFOutput
ExportFile -. Offline JSON Import / Sync .-> PWA
========================================================================================================================
DOKUREADER -- FOUR-VIEW ARCHITECTURAL TOPOLOGY (LOCAL-FIRST & ZERO-EGRESS)
========================================================================================================================
[VIEW 1: CALLER RUNTIMES, USER INTERACTION & DESKTOP GUI/CLI CONTROLS]
+-------------------------------------------------------------------------------------------------------------------+
| Windows Desktop Shell / CLI Launcher Tkinter Desktop Application PWA Mobile Companion |
| (START.bat / build_exe.bat / python) (DokuReader.py / Tkinter / TkinterDnD2) (web_companion / JS ES6) |
| - Local python launch - Topic List & Tree Navigation - Pure vanilla HTML5/CSS3|
| - PyInstaller EXE runner - Multi-Format Document Preview - Scoped CacheStorage |
| - Automated test orchestrators - Read / Unread Status Checkbox Toggles - Zero-egress PWA shell |
| - RunAsInvoker Non-Elevation (INV-RUNAS-02) - Search & Filter Controls (INV-A11Y-08) - Offline library review |
+-------------------------------------------------------------------------------------------------------------------+
|
v
[VIEW 2: DOKUREADER DESKTOP CORE, PREVIEW ENGINE & BUNDLING PIPELINES]
+-------------------------------------------------------------------------------------------------------------------+
| Document State Manager Preview Engine Subsystem Export & Bundling Subsystem |
| (DokuReader.py Core Model) (Multi-Format Rendering) (Merging & Outline Generation) |
| - Topic hierarchy dictionary - PyMuPDF (fitz) PDF page rendering - pypdf deterministic concatenator |
| - Path validation & normalization - Pillow (PIL) image decoding - reportlab text-to-PDF compiler |
| - Read/unread state mapping - Text preview (UTF-8 / Latin-1) - Read/unread filter predicates |
| - Safe topic rename & merge gates - Headless LibreOffice / Word COM - Atomic file publication |
| (INV-SCHEMA-04, INV-PARITY-07) (INV-SANDBOX-06 subprocess bounds) (INV-INPLACE-03 file protection) |
+-------------------------------------------------------------------------------------------------------------------+
|
v
[VIEW 3: RUNTIME PERSISTENCE, LOCAL STATE RECOVERY & EXPORT TIERS]
+-------------------------------------------------------------------------------------------------------------------+
| Original Documents Vault Application State Store Structured Export Artifacts |
| (Local Filesystem) (~/.dokubibliothek_state.json) (dokureader-library-v1 / PDF Bundles) |
| - In-place originals strictly - Atomic write via unique temp file - Schema-compliant JSON library export |
| read-only (INV-INPLACE-03) - Automatic .bak backup generation - Metadata-only outline (no binaries) |
| - Zero file moves or overwrites - Corrupted state fallback recovery - Consolidated topic PDF document |
| - Multi-topic path referencing - Isolated namespace (INV-ISOLATION-05)- Round-trip mobile import format |
+-------------------------------------------------------------------------------------------------------------------+
|
v
[VIEW 4: AIR-GAP DEFENSE PERIMETER, UNPRIVILEGED RUNASINVOKER & ZERO-EGRESS GOVERNANCE]
+-------------------------------------------------------------------------------------------------------------------+
| 100% Offline Air-Gap (INV-LOCAL-01) Unprivileged RunAsInvoker (INV-RUNAS-02) |
| - Zero outbound sockets, HTTP/S, or DNS - Standard user privilege mode execution |
| - Zero analytics, telemetry, or cloud calls - No UAC administrative elevation required |
| - Total offline data privacy by design - Bounded subprocess execution (INV-SANDBOX-06) |
| |
| Statutory § 521 BGB Disclaimer 48h Security Response SLA (INV-SLA-10) |
| - § 521 BGB Gefaelligkeitsrecht applies - 48h initial acknowledgement SLA |
| - No warranty for unpaid open source - 5-day triage commitment ([email protected]) |
+-------------------------------------------------------------------------------------------------------------------+
========================================================================================================================
DokuReader serves four distinct user personas requiring deterministic, local-first document curation:
-
[PERSONA-01]Academic Researchers & Literature Curators:- Need: Curation of preprints, journal PDFs, whitepapers into topic-based reading queues without duplicating or modifying local filesystem storage.
- High-Intent Queries (EN): "offline local document organizer pdf research library", "desktop pdf manager read status topics", "academic paper queue local first python"
- High-Intent Queries (DE): "lokale dokumentenverwaltung pdf forschungsbibliothek", "desktop pdf organizer lesestatus themen", "wissenschaftliche artikel offline lesen"
-
[PERSONA-02]Legal Counsel & Compliance Officers:- Need: Confidential discovery dossier organization, litigation case reading, zero cloud egress under GDPR/HIPAA/professional secrecy mandates.
- High-Intent Queries (EN): "confidential legal discovery document viewer offline", "zero egress local pdf bundle case management", "gdpr compliant document organizer desktop"
- High-Intent Queries (DE): "vertrauliche aktenverwaltung anwalt offline", "zero egress dokumentenleser bündeln datenschutz", "dsgvo konforme dokumentenbibliothek lokal"
-
[PERSONA-03]Technical Writers & Knowledge Engineers:- Need: Multi-format document inspection (Markdown, PDF, DOCX, ODT, images), in-place topic indexing, consolidated PDF bundling for handbook reviews.
- High-Intent Queries (EN): "multi format document preview bundling tool", "markdown docx pdf reading list desktop", "technical documentation bundle generator local"
- High-Intent Queries (DE): "multi format dokumenten vorschau sammlung", "markdown docx pdf leseliste desktop", "technische dokumentation bündeln offline"
-
[PERSONA-04]Autonomous AI Agents & Developers:- Need: Clean schema-compliant
dokureader-library-v1.jsonmetadata exports for agentic indexing and local RAG pipelines without file copying. - High-Intent Queries (EN): "local document library metadata json export schema", "clean json document catalogue ai agents", "offline document reader llm ready"
- High-Intent Queries (DE): "lokale dokumentenbibliothek json export schema", "metadaten katalog dokumente llm agenten", "offline dokumentenleser llms txt"
- Need: Clean schema-compliant
Evaluation of DokuReader against common alternative approaches across 10 architectural and operational dimensions:
| Dimension / Requirement | DokuReader | Calibre (E-Book Manager) | Zotero (Reference Manager) | DEVONthink / Commercial DMS | Ad-Hoc Filesystem Folders |
|---|---|---|---|---|---|
D1: In-Place Safety (INV-INPLACE-03) |
Strictly in-place (Zero file moves or modifications) | ❌ Copies all files into rigid internal directory structure | ✅ Files remain in place | ||
D2: Zero-Egress Privacy (INV-LOCAL-01) |
100% Offline (Zero outbound network traffic) | ❌ Proprietary cloud sync & license verification | ✅ Local only | ||
D3: Unprivileged Execution (INV-RUNAS-02) |
RunAsInvoker User Mode (No admin elevation) | ❌ System kernel/driver extensions on macOS | ✅ Standard user mode | ||
D4: Deterministic Schema (INV-SCHEMA-04) |
dokureader-library-v1 clean JSON export |
❌ Complex SQLite schema with heavy metadata blobs | ❌ Complex SQLite / CSL JSON exports | ❌ Proprietary binary database formats | ❌ No structured metadata schema |
D5: Multi-Format Preview (INV-SANDBOX-06) |
PDF, TXT, DOCX, ODT, PNG, JPG via safe bridges | ✅ Broad e-book format support | ✅ Broad format support | ❌ Relies entirely on external OS apps | |
| D6: Consolidated PDF Bundling | One-click merged PDF with read/unread filters | ❌ No native topic PDF merging workflow | ❌ Requires external plugins or PDF editors | ❌ Requires manual external PDF stitching | |
D7: Mobile PWA Companion (INV-ISOLATION-05) |
Offline PWA with round-trip JSON sync | ❌ Manual file sync required | |||
D8: Tri-Platform Source Support (INV-PARITY-07) |
Windows, Linux & macOS native Python/Tkinter | ✅ Cross-platform desktop | ✅ Cross-platform desktop | ❌ Apple macOS/iOS proprietary lock-in | ✅ Universal |
| D9: Automated Test Quality Gates | 62+ Pytest + 37 Node tests (100% green) | ❌ Closed-source proprietary verification | ❌ No test harness | ||
D10: Open Governance & SLA (INV-SLA-10) |
AGPL-3.0, § 521 BGB disclaimer, 48h SLA | ❌ Closed-source commercial EULA | ❌ None |
sequenceDiagram
autonumber
actor User as User / Researcher
participant UI as Desktop UI (DokuReader.py)
participant State as Local State Manager
participant Engine as Preview & Conversion Engine
participant Disk as Local Storage (Original Files)
participant Output as Export Generator
User->>UI: Add File / Drag-and-Drop
UI->>Disk: Inspect File Metadata (Stat only)
Note over UI,Disk: Originals remain untouched (INV-INPLACE-03)
UI->>State: Store Topic Reference & Unread Flag (INV-ISOLATION-05)
State-->>UI: Update Topic Tree View
User->>UI: Select Document for Preview
UI->>Engine: Request Page 1 / Text Stream
Engine->>Disk: Read-Only Stream
Engine-->>UI: Rendered Thumbnail / Plaintext
UI-->>User: Display In-App Preview
User->>UI: Toggle Read Status
UI->>State: Persist Read Status
State-->>UI: Reflected in Library Overview
User->>UI: Trigger Export (Consolidated PDF or JSON)
UI->>Output: Generate Bundle (Filtered by Read/Unread)
Output->>Disk: Write dokureader-library-v1.json or Merged PDF
Note over UI,Disk: 100% Offline / Local-First — Zero Network Egress (INV-LOCAL-01)
- Python 3.10+
- Tkinter (included with standard Python installations)
git clone https://github.com/doc-bricks/DokuReader.git
cd DokuReader
pip install -r requirements.txtpython DokuReader.pyOn Windows, launch directly via:
START.batSTART.bat opens the current source without a console window. An existing Plan-D
pointer selects the canonical source directory; old executables take no precedence.
A project venv is preferred over Python on PATH (Python 3.10 or newer). Install the
dependencies first. Use debug.bat for console diagnostics. Startup failures display
an error; output and crashes are logged outside the project and OneDrive under
%LOCALAPPDATA%\DokuReader\logs\app-<PID>.log. Each process keeps up to four 2 MiB
files; older process logs are not automatically deleted. Run
powershell -NoProfile -File .\start_source.ps1 -Check to inspect source and interpreter
selection without opening the application or changing its library.
- Documents:
.txt,.doc,.docx,.pdf,.odt,.rtf - Images:
.jpg,.jpeg,.gif,.png
For full preview rendering and external document conversion:
- LibreOffice: Required for headless DOC/DOCX/ODT/RTF to PDF conversion. Each attempt uses a fresh private profile and output directory with a 180-second deadline. Windows terminates the owned process job and observes its exit before returning; an available
soffice.comconsole entry is preferred. Linux/macOS send SIGKILL to the owned process group before waiting for and reaping its supervisor. Cleanup allows up to five additional seconds. Only a fresh readable PDF with pages, exit code 0 and successful cleanup is accepted. Conversion, profile cleanup or publication failures preserve previous output. The deadline applies per attempt; another converter may subsequently be tried. Detached POSIX processes fall outside this group boundary; termination of every grandchild is not generally proven. - Poppler: Required if using the optional
pdf2imagepreview backend. - Microsoft Word: Supported on Windows 10 or later with pywin32. Word automation runs in an owned process job with a 180-second deadline covering startup, export and shutdown, plus at most five seconds for cleanup. Existing Word processes are not reused or terminated.
build_exe.batBuild output under build/, dist/, and releases/ stays strictly local and is excluded from Git tracking via .gitignore. Set DOKUREADER_BUILD_ROOT to customize the local build scratch directory.
python _WARTUNG/check_store_readiness.py --allow-blockersValidates Store metadata, privacy policy URLs, required support links, visual assets, screenshots, and MSIX packaging requirements.
python _WARTUNG/run_windows_wack.py --dry-runGenerates the exact certification command for elevated execution and parses resulting XML validation reports into structured JSON.
The companion web application under web_companion/ provides an offline-first, mobile-optimized reading view:
- Installable PWA: Full Web App Manifest with iOS Safe-Area support (
viewport-fit=cover). - Offline Shell: Scoped Service Worker caching preserving external application caches.
- Round-Trip Synchronization: Imports
dokureader-library-v1.jsonexported from the desktop app, allows toggling read states on mobile, and exports an updated JSON back to the desktop. - Zero Third-Party Dependencies: Runs on pure vanilla JavaScript and Node.js built-in test runner (
37 passed, 0 failed).
cd web_companion
node --testThe following 10 invariants govern DokuReader's runtime architecture, privacy boundary, and security guarantees:
| Invariant | Principle | Guarantee & Verification Mechanism |
|---|---|---|
| INV-LOCAL-01 | 100% Local-First & Zero-Egress | Zero outbound HTTP/S, WebSocket, or telemetry traffic. All parsing and previews operate strictly offline. |
| INV-RUNAS-02 | Unprivileged RunAsInvoker Execution | The application runs exclusively in standard user mode without administrative elevation requirements. |
| INV-INPLACE-03 | In-Place Original File Safety | Original documents are strictly read-only. DokuReader never moves, modifies, or deletes imported files. |
| INV-SCHEMA-04 | Deterministic Export Schema | Library metadata exports adhere strictly to the versioned dokureader-library-v1 JSON specification. |
| INV-ISOLATION-05 | Local State & Cache Isolation | State is isolated in ~/.dokubibliothek_state.json. PWA companion caches only within dokureader-companion- scope. |
| INV-SANDBOX-06 | Safe Subprocess Execution | External converters (LibreOffice, Word COM) run with constrained arguments, timeout guards, and isolated temp directories. |
| INV-PARITY-07 | Tri-Platform Source Support | Core codebase runs across Windows, macOS, and Linux with platform-independent path handling and fallbacks. |
| INV-A11Y-08 | Keyboard & Visual Accessibility | Full keyboard navigation support, high-contrast readability, and deterministic UI state reflection. |
| INV-DISCOVERY-09 | Multimodal Transparency & LLM Ready | Complete bilingual documentation (DE/EN), machine-readable llms.txt, and interactive dual Mermaid diagrams. |
| INV-SLA-10 | Security Vulnerability SLA | Formal 48h initial response SLA and 5-business-day triage commitment for reported security disclosures. |
DokuReader is a core component of the doc-bricks family under the open-bricks open-source initiative:
| Repository | Focus | Role in Desktop Workflow |
|---|---|---|
| LitZentrum | Literature & Citations | Academic paper library, BibTeX export, and literature management |
| CleanMarkdown | Markdown Studio | Focused Markdown reader, editor, and typography cleaner |
| UniversalDocsGrabber | Document Intake | Automated mail attachment extraction and local document sorting |
| UniversalInvoiceMail | Invoice Mail Extraction | Deterministic invoice attachment detection and extraction |
| UniversalMailCleaner | Mail Hygiene | Local mail archive cleaning, duplicate removal, and sanitization |
| MailProcessor | Mail Processing | Rule-based local mail routing, filtering, and document triage |
| PDFtoPDFocr | PDF OCR Processing | Searchable sandwich PDF creation with local Tesseract OCR |
| MediaBrain | Media Asset Organizer | Visual media tagging, categorization, and metadata indexing |
| DokuZen | Distraction-Free Docs | Minimalist zen reading and document inspection environment |
| ProFiler | Multi-Tool File Analysis | Deep file inspector, structural parser, and metadata profiler |
| ExplorerPro | Advanced File Explorer | High-performance multi-pane local file manager |
| DevCenter | Developer Workspace | Central developer dashboard and project management hub |
| CodeBox | Code Snippet Vault | Offline-first code snippet organizer with syntax highlighting |
| open-bricks | Umbrella Architecture | Master ecosystem coordination for desktop productivity |
- Zero Network Egress: The application contains no telemetry code, analytics libraries, or cloud sync background tasks.
- In-Place File Safety: Imported files are opened exclusively in read-only mode for thumbnail and text preview.
- RunAsInvoker Least Privilege: Operates entirely in unprivileged standard user mode.
- Formal Security SLA: Vulnerability disclosures receive initial acknowledgement within 48 hours and triage within 5 business days. Reports should be submitted to
[email protected],[email protected], or via GitHub Security Advisories. See SECURITY.md.
Continuous quality is assured through independent, automated verification gates:
# Run Python unit and metadata contract tests (224 tests)
pytest
# Run static analysis and lint checks
ruff check .
# Validate whole-repository bytecode compilation
python -m compileall -q .
# Run cross-platform desktop smoke test
python tests/source_platform_smoke.py
# Run mobile PWA companion test suite (37 tests)
cd web_companion && node --testFor AI coding agents (Claude Code, Gemini / Antigravity, Codex, Kimi Code), DokuReader exposes complete architectural context via llms.txt. It provides canonical repository paths, dependency boundaries, test commands, search keywords, and security invariants in an efficient format.
DokuReader is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). All third-party Python dependencies (Pillow, pypdf, reportlab, python-docx, odfpy, tkinterdnd2, pywin32, pdf2image) are distributed under permissive open-source licenses (MIT, BSD-3-Clause, Apache-2.0, PSF-2.0) or compatible AGPL-3.0 (PyMuPDF).
For the complete dependency audit, Level 1 SBOM invariant cross-reference matrix, and unprivileged runtime statements, see THIRD_PARTY_LICENSES.md, THIRD_PARTY_LICENSES.txt, and NOTICE.
DokuReader maintains an active, traceable marketing, discoverability, and architecture audit log in MARKETING-LOG.txt.
Key discoverability pillars:
- GitHub Ecosystem Satiation: Full 20/20 topics populated with high-intent keywords (
desktop-app,document-management,library,pdf,pdf-export,python,tkinter,local-first,privacy-first,reading-state). - LLM Context Integration: Indexed via
llms.txtfor AI developer agents and search engines. - Cross-Project Linkage: Deep integration with doc-bricks sibling tools (LitZentrum, CleanMarkdown, UniversalDocsGrabber).
- Bilingual Parity: 100% documentation alignment between English (README.md) and German (README_de.md).
DokuReader is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Full author and open-source umbrella attribution is declared in NOTICE.
Statutory Disclaimer pursuant to § 521 German Civil Code (BGB):
Da diese Software und sämtliche zugehörigen Vorlagen unentgeltlich zur Verfügung gestellt werden, haften die Urheber, die Organisationdoc-brickssowie der Dachverbandopen-bricksnach den gesetzlichen Bestimmungen des deutschen Gefälligkeitsrechts (§ 521 BGB) ausschließlich für Vorsatz und grobe Fahrlässigkeit. Eine Gewährleistung für Sach- oder Rechtsmängel ist ausgeschlossen.
As this software and related templates are provided free of charge, the authors, thedoc-bricksorganization, and theopen-bricksumbrella collective shall only be liable for intent and gross negligence in accordance with § 521 of the German Civil Code (BGB). Any warranty for defects of quality or title is excluded.
The maintainers commit to a 48-hour response SLA for incoming security advisories and vulnerability notifications sent to [email protected], [email protected], or reported via GitHub Security Advisories. Initial triage is completed within 5 business days. For details, see SECURITY.md.