suchi

README

suchi

A document-management system as a single Go binary.
_{Sanskrit सूची — "an index, a catalog, a list"; pronounced SOO-chee, like kimchi.}

Suchi combines SQLite, content-addressed storage, a Svelte interface, and an integration-friendly HTTP API. It needs no database server, queue, cache, or telemetry service.

The content-addressed store keeps immutable original and derived bytes under their SHA-256 digest. Identical bytes can share one stored object, retries do not create another copy, and database rows can retain stable content while filing paths are rebuilt as views. It is not encryption or an access-control boundary; SQLite metadata and the API still decide who can see each document.

Current source line: v0.1.0. Back up before upgrades, test restore for critical archives, and follow the documented stable-v1 compatibility policy.

Container images · Releases · Actions

• Reproducible size and startup measurements live under hack/bench/latest-published/.
• No built-in outbound connection is made until an operator enables or uses an integration. Operator scripts are outside Suchi's egress inventory.
• Static, CGO_ENABLED=0 Go binary with multi-user ACLs and scoped tokens.
• AGPL-3.0.

Capabilities

• PDF and image OCR, thumbnails, barcodes, encrypted PDFs, and ZUGFeRD invoices.
• EPUB, Office, OpenDocument, RTF, CSV, DjVu, HEIC/HEIF, EML, and Outlook MSG.
• Full-text search, Johnny.Decimal filing, custom fields, saved views, and rendered filesystem views.
• Import-introduced filing systems with permanent codes, direct membership plus document ACLs, and SYS.AC.documentID addresses using existing global IDs. Unprefixed archives keep their existing UI and paths until first prefixed Apply.
• Browser uploads, watched folders, IMAP intake, portable import/export, and versioned documents.
• Automations, human approval workflows, selective rescans, and optional OpenAI-compatible classification, grounded archive research, and source-backed date intelligence with Calendar. High-confidence suggestions apply by default; review-first mode sends inferred changes to Approvals instead.
• Groups, object ACLs, OIDC, share links, audit events, backups, and restore tooling.
• Svelte SPA, Android/iOS Suchi Companion, a documented scoped HTTP API, and MCP over stdio or HTTP.

The feature comparison and architecture describe the detailed scope and tradeoffs.

Quick Start

The versioned standard image is a convenient local evaluation starting point:

docker volume create suchi-data
docker run -d --name suchi --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -e PUBLIC_URL=http://127.0.0.1:8000 \
  -v suchi-data:/data \
  ghcr.io/johnnybravo-xyz/suchi:v0.1.0
docker logs suchi 2>&1 | grep token_minted

Open http://127.0.0.1:8000, enter the one-time setup token, and create the first admin account. The token expires after 24 hours; attempting to use an expired token writes a replacement to the server log. A minimal compose.yaml is also provided for operators who want editable mounts, networks, and image pins. See Getting started for direct binary, reverse-proxy, NAS, and production deployment paths.

After creating the administrator, choose a filing tree in Settings > Archive configuration > Filing tree. This is the only required archive setup step; the reminder remains until a preset, imported tree, or explicit Blank choice is saved.

This quick start is bound to loopback and pins the v0.1.0 image. A production server, including one reached by the mobile app, must use HTTPS and pin the selected release by its published image digest.

Images

• v0.1.0 / latest: Alpine. Supports all listed formats and indexes scanned PDFs with Tesseract.
• v0.1.0-full / latest-full: Debian. Adds OCRmyPDF so downloaded scanned PDFs can retain a searchable text layer.

Both images include anydoc, DjVu, HEIC/HEIF, and Outlook MSG support. The full image changes only the scanned-PDF archive behavior. See Supported file types for the exact routing and bare-metal dependencies.

Development

The workspace requires Go 1.27.0 or newer; plugin-api remains compatible with Go 1.24. SPA and documentation development require Bun.

git clone https://github.com/johnnybravo-xyz/suchi.git
cd suchi
make install-hooks
make check
make run

make run uses /tmp/suchi-dev and listens on http://127.0.0.1:8000. Useful verification commands:

make test
make lint
make ui-check
make smoke
make smoke-ingest
./hack/smoke-anydoc-docx.sh
make smoke-mail

The ci workflow runs formatting, vet, tests, static analysis, and the SPA build. The smoke workflow boots both images and verifies real PDF OCR and Outlook MSG ingestion.

Repository

plugin-api/   shared extension interfaces and types
core/         API, database, ingest pipeline, jobs, auth, and embedded UI
plugins/      local auth, OIDC, and LLM classifier modules
distro/       importable app assembly and shipped suchi / suchi-mcp entry points
ui/           Svelte SPA source
deploy/       self-hosting templates and mail intake sidecar
docs/         published documentation source
hack/         fixtures, benchmarks, smoke tests, and developer tools

The root module contains the shipped application; plugin-api stays separate for external plugins and the utilities under hack/ keep isolated dependency graphs. The empty ui module keeps Go tooling out of frontend dependencies. make build produces dist/suchi; suchi doctor inventories configured egress, pipeline tools, schema and taxonomy state, data-directory writability, and selected job, backup, audit, upload-limit, and CAS indicators.

Documentation

• Documentation
• Configuration
• CLI reference
• HTTP API
• Filing systems and taxonomy imports
• Supported file types
• Deployment templates
• Backup and restore
• Contributing
• Security policy

Works with Johnny.Decimal, a trademark of Coruscade Pty Ltd. Suchi is independent and not endorsed by them. The built-in filing trees are CC0-1.0, unreviewed and not compliance advice. Filing systems share one server, SQLite/FTS and CAS; server administrators and host/backup operators remain trusted. A code prefix is not separate infrastructure or a legal-independence guarantee. See Permissions for the application boundary.

License

Copyright (c) 2026 Ritesh Shrivastav. Suchi is available under two licenses:

• GNU Affero General Public License v3.0 — free for everyone. Note that if you modify Suchi and let others interact with it over a network, AGPL section 13 requires you to offer them its complete corresponding source.
• Commercial license — for embedding Suchi in a proprietary product, or for running a modified instance as a service without that source-offer obligation. Write to contact@suchi.page.

The AGPL offer begins with Suchi's first public release. Before that release, its repository and container images were private development artifacts and were not distributed to any third party.

The plugin interfaces in plugin-api/ are a separate module licensed under the Apache License 2.0, so third-party plugins may be released under any license, including proprietary ones.

Third-party components and their terms are listed in NOTICE. Contributions are accepted under the Contributor License Agreement.