Kazier Documentation
Kazier Documentation
Section titled “Kazier Documentation”Welcome to the Kazier v1.1.0 documentation (released September 25, 2026).
Kazier is a local-first Android file manager. It mirrors your device’s Storage Access Framework (SAF) into a local Room database, then syncs with your own backend — first metadata (transactional outbox), then bytes (automatic upload), and pulls back on demand (offline).
Principles
Section titled “Principles”| Principle | Meaning |
|---|---|
| Local-First | Your data lives on your own hardware, not in a cloud that could disappear tomorrow. |
| Open Source | Software you can inspect, audit and self-host. No black boxes, no vendor lock-in. |
| Private by Design | Encryption and sovereignty are the defaults, not options. |
| Controlled sync | Nothing leaves without your gesture: file review, targeted upload, safe purge (never any loss). |
How it works
Section titled “How it works”- The Android client walks your SAF folders and mirrors them into a local Room database.
- Mutations (create, move, delete, shares, presence) are recorded in a transactional outbox alongside the local change.
- A WorkManager worker drains the outbox to
POST /sync/opson your backend, which applies operations sequentially. - A second worker pushes bytes (targeted
POST /files/upload) once metadata is known; the server exposes their presence (has_content, placements). - Remote reading via streaming (
GET /files/:id/content, never persisted), offline pull back into SAF, or freeing space (safe purge: only if the server keeps the bytes).
Architecture
Section titled “Architecture”┌─────────────────────────────┐ outbox sync ┌────────────────────────────┐│ Android (Kotlin + Compose) │ ───────────────────▶ │ Backend (Go + Gin) ││ · Room database (v18) │ metadata │ · PostgreSQL 17 ││ · SAF file access │ + bytes (V2) │ · PASETO auth ││ · WorkManager outbox │ │ · OCR (Tesseract) ││ · Auto retention │ ◀─────────────────── │ · Placements, groups │└─────────────────────────────┘ streaming/reads └────────────────────────────┘What’s new in v1.1.0 (V2 sync)
Section titled “What’s new in v1.1.0 (V2 sync)”- Automatic upload: bytes follow metadata (idempotent targeted overwrite, 3 attempts max).
- Offline: pull a cloud file back into SAF (reboot-resilient); safe free up space purge (never without a server copy).
- Multi-device placements: each device reports its bytes (
report_bytes), owners see the copies. - Auto retention: “keep all / last N months” rule, daily pass + manual free-up in Settings.
- Groups: share with a group instead of user by user (one level, no nesting).
Since v1.0.0
Section titled “Since v1.0.0”- Remote streaming: image/text/multi-page PDF reading with no persistence.
- Full sharing: editable/revocable grants, public links (create, copy, revoke),
kazier://share/<token>deep-links. - Silent re-login: 7-day token auto-renewed (encrypted credentials), no request replay.
- Accent-insensitive search (“ete” finds “ÉTÉ”).
Since v0.1.0
Section titled “Since v0.1.0”- Keep / Discard review: newly discovered SAF files are imported locally but pushed to the server only when you “keep” them.
- Document scanner: offline capture, crop and PDF export.
- Server OCR: Tesseract (
fra+eng) extracts text on the backend, then synced back to your devices. - Sharing & public links: user sharing (
viewer,commenter,editor) and share links, synchronized through the outbox. - Local search, PDF generation, offline mode, light/dark theme, FR/EN interface.
Getting started
Section titled “Getting started”- Quick Start — run the backend and Android app locally.
- Docker Setup — run PostgreSQL with Docker Compose.
- Environment Variables — full reference of server configuration.
- API Reference — the authoritative V1 API contract.
- Signed APK v1.1.0: Gitea release — release history
- Source code (AGPLv3 license)
- Backend image:
gitea.thirdshop.fr/thirdshop/kazier:v1.1.0(latestavailable) - Landing page: Kazier