Deutsch | English
Note
AI / LLM Integration Index: Machine-readable repository context, API boundaries, and architecture contracts are indexed in llms.txt.
DokuZen is a cross-platform, local-first desktop document management and processing suite built with Python and PySide6, combining 22 specialized text, PDF, OCR, and file utilities into a single unified workspace.
- 📸 Visual Showcase Gallery
- 🏛️ System Architecture
- 🔄 Document & PDF Processing Lifecycle
- ✨ Core Features & 22 Utilities
- 🎯 Target Personas & SEO Intent
- ⚖️ Comparative Matrix vs. 5 Alternatives
- 🚀 Installation & Quick Start
- 🖥️ GUI-CLI Direct Entry Points
- 🌐 Ecosystem & Sibling Tools
- 🔒 Privacy & Security Invariants
- 🧪 Testing & Verification
- ⌨️ Keyboard Shortcuts
- 🪟 Windows Store & MSIX Packaging
- 🐧 Portable Linux Bundle
- 📦 Offline Workspace Export & Mobile PWA
- 📜 Audit Trail & Discoverability Log
- ⚖️ Statutory & Liability Notice (§ 521 BGB)
- 📄 License & Third-Party Dependencies
flowchart TD
subgraph UI ["Layer 1: PySide6 Desktop User Interface"]
LP["Library Panel<br/>(Thematic Taxonomy & State)"]
DP["Document List Panel<br/>(Metadata, Search & Sorting)"]
PP["Preview Panel<br/>(PyMuPDF / WebView / Syntax Engine)"]
DLG["Specialized Modal Dialogs<br/>(OCR, Redaction, Merge, Converter, Settings)"]
end
subgraph AppRouter ["Layer 2: Application Router & State Manager"]
ROUTER["Event & Task Dispatcher<br/>(Thread Guards, Async Workers, Hotkeys)"]
SETTINGS["Configuration Manager<br/>(settings.json, Non-Privileged State)"]
end
subgraph Core ["Layer 3: Core Processing Engines"]
LIB["Library Manager<br/>(Persistence, Tag Index & Review State)"]
PDF["PDF Workshop<br/>(Merge, Split, Crop, Rotate, Overlay)"]
OCR["OCR Engine<br/>(Tesseract Subprocess & Text Layer Generation)"]
CVT["Format Converter<br/>(DOCX ↔ PDF ↔ MD ↔ TXT, RGBA Alpha)"]
SEC["Security & Unlock<br/>(Pikepdf Session-Key Isolation)"]
RED["Redaction Engine<br/>(Destructive Black-Fill Sanitization)"]
end
subgraph Storage ["Layer 4: Local Storage & Data Isolation Boundary"]
STATE["dokuzen_state.json<br/>(Local-First User State)"]
WSEXPORT["dokuzen-workspace-v1.json<br/>(Redacted Portable Workspace Export)"]
FS["Local File System Boundary<br/>(Zero-Egress / Atomic Sandboxed Paths)"]
end
subgraph Distribution ["Layer 5: Packaging & Distribution Artifacts"]
MSIX["MSIX Packaging Bridge<br/>(Windows Store Manifest & Preflight)"]
LINUX["Linux Bundle Engine<br/>(PyInstaller onedir + AppStream XML)"]
end
LP --> ROUTER
DP --> ROUTER
PP --> ROUTER
DLG --> ROUTER
ROUTER --> LIB
ROUTER --> PDF
ROUTER --> OCR
ROUTER --> CVT
ROUTER --> SEC
ROUTER --> RED
ROUTER --> SETTINGS
LIB --> STATE
LIB --> WSEXPORT
PDF --> FS
CVT --> FS
MSIX -.-> UI
LINUX -.-> UI
sequenceDiagram
autonumber
actor User as Desktop User
participant GUI as PySide6 Main Window
participant Router as Format & Task Router
participant Engine as Core Engine (PDF/OCR/Converter)
participant FS as Local File System Boundary
User->>GUI: Ingest Document (Drag & Drop / Ctrl+I / CLI Flag)
GUI->>Router: Detect MIME Type & Header Signature
alt PDF Stream / Document
Router->>Engine: Parse via PyMuPDF / pikepdf with Thread Guard
Engine-->>GUI: Render Offscreen Page Pixmaps & Extract Text Layers
GUI-->>User: Display High-Fidelity Preview & Page Navigation
else Image / OCR Scan
Router->>Engine: Dispatch to Tesseract OCR Subprocess
Engine-->>GUI: Bounding-Box Layout & Textual Layer Generated
else Format Conversion
Router->>Engine: Convert (DOCX / Markdown / TXT / Alpha Image)
Engine-->>GUI: Transformed Output Ready for Inspection
end
opt Redaction / Signature / Split & Merge
User->>GUI: Apply PII Redaction Pattern / Signature Stamp
GUI->>Engine: Destructive Vector & Pixel Overlay
end
User->>GUI: Trigger Save / Export
GUI->>FS: Atomic Write to Local Disk (Zero Egress, Closed File Descriptors)
FS-->>User: File Saved Successfully with 100% Offline Guarantee
- Thematic Organisation: Categorize documents by topics and tags with persistent category selection across restarts.
- Read / Unread State: Track review progress across large document collections.
- Fast Search & Filtering: Instant filter by name, content, and metadata with
Ctrl+Fglobal shortcut. - Drag & Drop Import: Direct file ingestion into active categories with automatic type recognition.
- Merge & Split: Combine multiple PDF streams or split at specific page boundaries and ranges.
- Tesseract OCR Integration: Generate searchable PDFs and extract textual layers with bounding-box precision.
- Sanitization & Redaction: Regex- and span-based PII redaction with irreversible black-fill sanitization.
- Signature & Stamp Overlay: Stamp transparent PNG signatures or metadata badges onto target pages.
- Password Removal: Decrypt password-protected files via
pikepdfwith session key guards. - Page Transformations: Non-destructive and destructive rotation, margin cropping, and page reordering.
- Word ↔ PDF ↔ Markdown ↔ Plain Text: Seamless bidirectional document format transitions.
- Image Conversion: PNG, JPG, ICO, WebP with full RGBA transparency preservation on conversion to PDF.
- Encoding Repair: Automatic Mojibake and UTF-8/Latin-1 encoding restoration.
- Python to EXE Compiler: PyInstaller bundling UI with icon embedding and dependency detection.
- License Generator: Standardized open-source license creation.
- Code Splitter: Clean split of multi-class Python source files into modular units.
- Web Companion & Workspace Export: Export redacted
dokuzen-workspace-v1.jsonworkspaces for mobile PWA viewers.
- Privacy Guard: Visual privacy monitor alerting on sensitive data exposure.
- Sync Engine: Local-first synchronization helper.
- Media Brain: Integrated asset extraction and indexing.
- Windows Store Bridge: MSIX Packaging Manifest & automated preflight readiness checks.
DokuZen is engineered for professionals and power users requiring dependable local document tools:
- Regulatory Frameworks: GDPR (DSGVO), HIPAA, CCPA, ISO 27001, SOC 2.
- Pain Point: Cloud-based PDF web converters (Smallpdf, iLovePDF) upload unredacted contracts, patient data, and confidential IP to third-party web servers, violating international data residency and attorney-client privilege.
- DokuZen Solution: 100% Zero-Egress local execution, destructive black-fill vector sanitization, unprivileged runtime (
RunAsInvoker), and closed file descriptor hygiene. - High-Intent Search Queries:
local pdf redaction tool gdpr compliantoffline pdf pii sanitizerdesktop document anonymizer zero data egresssafe legal document redaction software
- Context: Everyday knowledge workers handling high volumes of invoices, contracts, forms, and client briefs.
- Pain Point: Costly recurring Adobe Acrobat Pro subscription fees ($240+/year), slow application startup times, intrusive background updaters, and tool fragmentation.
- DokuZen Solution: Comprehensive 22-in-1 desktop utility suite, instantaneous PyMuPDF offscreen preview, keyboard shortcuts (
Ctrl+I,Ctrl+F,Ctrl+P), batch merging, and transparent signature overlays. - High-Intent Search Queries:
free alternative to adobe acrobat pro offlinefast desktop pdf merger and splitterpyside6 document managerpdf signature overlay desktop tool
- Context: Scientists, historians, and digital archivists cataloging extensive document collections and scans.
- Pain Point: Incomplete OCR text layers in scanned archives, lack of thematic categorization, character encoding corruption (Mojibake), and proprietary file lock-in.
- DokuZen Solution: Tesseract OCR engine with language auto-detection, thematic topic classification with unread tracking, Mojibake repair, and clean export to Markdown and plain text.
- High-Intent Search Queries:
open source ocr pdf search toolacademic document organizer local firsttesseract ocr desktop gui pythonscan to searchable pdf offline
- Context: Python engineers, system administrators, and DevOps professionals managing local document pipelines.
- Pain Point: Flaky cloud REST APIs, platform-specific lock-in, unmanaged temporary file leaks, and complex dependency management.
- DokuZen Solution: Dual packaging (Windows Store MSIX + Linux PyInstaller bundle), GUI-CLI shortcut entry points (
--import,--ocr,--redact,--merge), cleandokuzen-workspace-v1.jsonexport schema, and zero-egress CI verification. - High-Intent Search Queries:
portable linux pdf tools bundlepython pdf automation local-firstmsix python desktop appreproducible offline document workflow
| Invariant / Feature | DokuZen 1.0.1 | Adobe Acrobat Pro | Smallpdf / iLovePDF | PDF24 Creator | Master PDF Editor | Okular / Evince |
|---|---|---|---|---|---|---|
| INV-LOCAL-01: Zero-Egress Privacy | ✅ 100% Local | ❌ Cloud Upload | ✅ Local Native | ✅ Local Native | ✅ Local Native | |
| INV-COST-02: Open-Source / Pricing | ✅ Free (AGPL-3.0) | ❌ $240+/year sub | ❌ $108+/year sub | ❌ $70+ Commercial | ✅ Free (GPL) | |
| INV-PRIV-03: Destructive Redaction | ✅ Vector Blackout | ✅ Yes | ❌ Server-side Risk | ❌ None | ||
| INV-TOOL-04: Tool Consolidation | ✅ 22 Utilities | ❌ Viewer Only | ||||
| INV-OCR-05: Tesseract OCR Layer | ✅ Native Integrated | ❌ Cloud Queue | ✅ Basic OCR | ❌ Paid License Only | ||
| INV-PERF-06: High-Speed Rendering | ✅ PyMuPDF / Fitz | ✅ Native C++ | ❌ Browser Latency | ✅ Native C++ | ✅ Poppler | |
| INV-PLAT-07: Cross-Platform Parity | ✅ Win / Linux / Mac | ❌ Windows only | ||||
| INV-FMT-08: Multi-Format Converter | ✅ Bidirectional | ❌ PDF only | ❌ Export only | |||
| INV-SECR-09: Unprivileged Sandbox | ✅ RunAsInvoker | ❌ Background Daemons | ❌ Remote Multi-Tenant | ✅ Standard User | ✅ Standard User | |
| INV-ARCH-10: Open Workspace Export | ✅ dokuzen-json v1 | ❌ Cloud Lock-in | ❌ Account Lock-in | ❌ None | ❌ None | ❌ None |
- Python 3.10, 3.11, 3.12, or 3.13
- PySide6 >= 6.5.0
- Tesseract OCR (optional, for OCR capabilities)
- Dependencies listed in
requirements.txt/pyproject.toml
# Clone the repository
git clone https://github.com/doc-bricks/DokuZen.git
cd DokuZen
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
source venv/bin/activate # Linux/macOS
# Install dependencies
pip install -r requirements.txt
# Start DokuZen
python main.pyNote: On Windows, you can also launch directly via start.bat.
DokuZen provides direct CLI flags that launch the desktop application and navigate immediately into specific workflows:
# Import documents into library
python main.py --import document.pdf notes.md
# Open document in preview panel
python main.py --open manual.pdf
# Launch OCR Dialog with preloaded file
python main.py --ocr scan.pdf
# Launch Redaction Dialog
python main.py --redact contract.pdf
# Launch PDF Merger Dialog
python main.py --merge part1.pdf part2.pdfNote
Automation Boundary: The evidenced use case is a local desktop document and PDF workstation. The CLI entry points above are GUI startup shortcuts. Headless batch CLI and REST API endpoints remain intentionally unasserted until explicit remote use cases and approved security models are established.
DokuZen is maintained under the doc-bricks ecosystem, part of the open-bricks family of local-first tools:
| Repository | Purpose | Status |
|---|---|---|
| doc-bricks/DokuZen | All-in-One Document & PDF Management Suite | Active / 1.0.1 |
| doc-bricks/CleanMarkdown | Distraction-Free Markdown Editor & PDF Exporter | Active / 1.0.0 |
| doc-bricks/FormularErstellen | Interactive PDF & AcroForm Form Designer | Active / 1.5.0 |
| doc-bricks/UniversalDocsGrabber | Automated IMAP Document Ingestion & PWA Hub | Active / 1.1.4 |
| doc-bricks/PDFtoPDFocr | OCR Conversion & Searchable PDF Engine | Active / 1.1.3 |
| doc-bricks/DokuReader | Lightweight Multi-Format Document Reader | Active / 1.0.0 |
| doc-bricks/MediaBrain | Multi-format Media & Metadata Extraction | Active / 0.1.0 |
| doc-bricks/TextBrain | AI-assisted Text Analysis & Extraction | Active / 0.1.0 |
| file-bricks/WinStorePackager | MSIX Packaging & Windows Store Tooling | Active / 3.1.0 |
| file-bricks/ProSync | Local Backup & WAL-Protected Sync | Active / 3.2.1 |
| file-bricks/ExplorerPro | Multi-Tab Local-First File Manager | Active / 1.0.3 |
| dev-bricks/DevCenter | Developer Productivity Hub & Dashboard | Active / 1.0.0 |
| open-bricks/.github | Umbrella Organisation & Open Standards | Active |
DokuZen is committed to uncompromising privacy and security:
- 100% Local-First & Zero-Egress (
INV-LOCAL-01): All document operations, conversions, and OCR recognitions occur exclusively on your local CPU/GPU. No document content or telemetry is ever sent over the network. - Unprivileged User Mode (
INV-SECR-09): DokuZen runs without administrative or root privileges (RunAsInvoker). - Destructive Redaction (
INV-PRIV-03): Redactions are applied directly to vector streams and image rasters, preventing reverse extraction of sanitized text. - Deterministic File Cleanup: All intermediate temporary files are cleaned up atomically upon operation completion with guaranteed file descriptor closure.
Detailed security and disclosure policies are available in SECURITY.md.
DokuZen maintains an automated test suite covering unit operations, GUI dialog smoke tests, PDF encryption lifecycles, and metadata parity:
# Run complete test suite (391 passed, 100% green)
python -m pytest
# Run offscreen platform smoke tests
python tests/test_source_platform_smoke.py
# Run Windows Store readiness gatekeeper
python tools/check_store_readiness.py
# Validate the portable Linux bundle contract (host-independent)
python tools/build_linux_bundle.py --check
# Run linting gatekeeper
python -m ruff check .| Shortcut | Action |
|---|---|
Ctrl+I |
Import Files into Active Category |
Ctrl+N |
Create New Theme / Category |
Ctrl+F |
Focus Search Filter |
Ctrl+P |
Toggle Preview Panel |
Ctrl+, |
Open Preferences Dialog |
Ctrl+Shift+E |
Export Redacted Workspace Snapshot (dokuzen-workspace-v1.json) |
F5 |
Refresh Document Index |
DokuZen includes complete Microsoft Windows Store (MSIX) packaging infrastructure:
- Manifest:
store_package/DokuZen/AppxManifest.xml(Geiger.DokuZen,runFullTrust) - Assets: 1080p store screenshots in
screenshots/store/and high-DPI icon assets (44x44, 50x50, 150x150, 310x150, 310x310) - Validation: Automated preflight validation script via
tools/check_store_readiness.py
DokuZen has a reproducible PyInstaller-onedir packaging path for Linux. A dedicated workflow builds DokuZen-1.0.1-linux-<architecture>.tar.gz with the application, assets, six-language catalog, configuration, Freedesktop desktop entry, AppStream metadata, license, and bilingual documentation.
# Metadata/contract check on any host
python tools/build_linux_bundle.py --check
# Actual bundle build on Linux
python tools/build_linux_bundle.pyTesseract remains an optional external dependency; DokuZen starts without it, while OCR features remain unavailable until Tesseract is installed. See packaging/linux/README.md for extraction and startup instructions.
DokuZen provides a built-in export mechanism (Ctrl+Shift+E or File → Export Workspace...) generating a portable, redacted workspace snapshot adhering to the dokuzen-workspace-v1 schema:
- Redacted Privacy Guarantee: Absolute local filesystem paths, passwords, and master credentials are completely stripped.
- Categorical State: Full preservation of document themes, tags, read/unread review status, and document byte sizes.
- Mobile Companion Ready: Designed for ingestion into offline PWA companions and static archive viewers without server dependencies.
DokuZen maintains full operational transparency across releases and ecosystem audits:
- Pfad B Marketing Log: Detailed persona mapping, SEO keywords, and comparative matrices in
MARKETING-LOG.txt. - Third-Party Dependency Inventory: Complete SPDX license classification and copyleft boundary documentation in
THIRD_PARTY_LICENSES.txtandTHIRD_PARTY_LICENSES.md. - Release History: Chronological changelog in
CHANGELOG.md.
Important
Limitation of Liability for Gratuitous Software Provision (§ 521 BGB): As this software is provided free of charge as open-source software, the authors and contributors are liable only for intent and gross negligence pursuant to § 521 of the German Civil Code (Bürgerliches Gesetzbuch - BGB). The software is provided "as is", without warranty of any kind, express or implied.
DokuZen is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
Direct third-party libraries and runtime copyleft boundaries are documented in THIRD_PARTY_LICENSES.txt and THIRD_PARTY_LICENSES.md.







