How Jiandu works
Jiandu is a self-hosted document library for a household or another small, trusted group. The central design choice is simple: the durable original is not the same thing as the title, tags, permissions, search text, and processing state that help people use it.
Keeping those concerns separate makes corrections cheap and recovery understandable. A wrong title should be fixable without rewriting the source PDF. A failed processing job should leave the original available. A search index should be rebuildable rather than becoming the only copy of the archive.
The five parts of a document
| Part | What it represents | Recovery expectation |
|---|---|---|
| Original | The admitted PDF, image, or plain-text source bytes | Durable and independently recoverable |
| Document record | Identity, title, dates, correspondents, tags, and lifecycle state | Backed up with the database |
| Processing result | Extracted text and other derived artifacts | Reproducible from the original when the run contract permits |
| Search index | A disposable representation optimized for retrieval | Rebuildable; never the source of truth |
| Access policy | Who may view, edit, or manage an exceptional document | Enforced from the database and included in recovery tests |
The blob backend stores originals and durable artifacts. SQLite or PostgreSQL stores the records and coordination state. A complete backup needs both at a coherent point in time.
From intake to a searchable record
capture source → durable admission → processing → review → search and access
- Capture starts in the browser, a watched folder, a configured scanner or agent, an email connector, or a reviewed import.
- Admission validates the input and preserves the durable original before downstream work is treated as complete.
- Processing runs with explicit resource limits and a versioned plan. Work is segmented so an interrupted run can continue safely.
- Review lets a person correct filing information. Manual corrections remain authoritative.
- Retrieval combines the searchable record with the current access decision before returning a result.
Durable acceptance is not the same as completed processing. The original may already be safe while a later stage is still queued, retrying, or waiting for attention.
Shared library, explicit exceptions
The normal household library is shared. Named members use the ordinary document workflow, while built-in roles, groups, and custom permission sets handle administration and recurring responsibilities.
Sensitive documents can be restricted to named people or groups with Viewer, Editor, or Manager access. The installation Owner retains a recovery grant. An Administrator does not automatically gain access to every restricted document, so access checks must be tested with an ordinary Member account.
See people and access for the operational model.
Accountable automation
Jiandu can observe repeated, authoritative metadata corrections and propose a filing rule. It does not silently turn one edit into household-wide automation. Accepted rules remain visible, pausable, exportable, auditable, and reversible, and a later manual edit wins.
Restricted documents do not provide evidence for household-global learning. This keeps an exceptional private record from indirectly influencing shared filing behavior.
One process owns an installation
Jiandu currently uses a single-process deployment topology. Do not point two Jiandu processes at the same database and blob namespace, and do not scale the Kubernetes example to multiple application replicas. This boundary applies even when PostgreSQL or remote blob storage could technically serve several clients.
For exact supported combinations, use the support matrix. For the data path during failures, read document lifecycle and backup and restore.