Sign inSign up

sinarah/documind

By sinarah

•Updated 14 days ago

Image
0

31

sinarah/documind repository overview

⁠DocuMind: Complete Feature List & User Guide

DocuMind is a high-performance, self-hosted, privacy-first personal document vault. It combines automated OCR, local AI field extraction, hybrid full-text/vector search, a visual page manipulation studio, and conversational Q&A with citations—all running locally in a single Go binary backed by SQLite.


⁠Table of Contents

  1. Core Capabilities & Architecture⁠
  2. Complete Feature Matrix⁠
  3. User Guide & Workflows⁠
  4. Configuration & Environment Reference⁠
  5. Keyboard Shortcuts & UI Cheat Sheet⁠

⁠1. Core Capabilities & Architecture

  • Zero Cloud Reliance: All processing (OCR, heuristic extraction, vector search, embeddings, chat) can run 100% locally on your own hardware (from a Raspberry Pi to a dedicated server).
  • Graceful Fallback Pipeline: If Ollama AI is offline or models are not yet pulled, DocuMind uses local heuristics to extract dates, merchants, and amounts, preserving full-text searchability.
  • Single Database File: Structured metadata, full-text indexes (FTS5), and dense vector embeddings (sqlite-vec) reside inside SQLite with zero external database servers required.
  • Real-Time Reactivity: Ingestion states (queued $\to$ rendering $\to$ ocr $\to$ extracting $\to$ indexing $\to$ ready) stream live to the browser over Server-Sent Events (SSE).

⁠2. Complete Feature Matrix

⁠Document Ingestion & Multi-Format Ingestion
  • Drag-and-Drop Ingestion: Upload single or batches of files straight from your browser.
  • Automated Consume Folder: Drop files into /data/consume; the vault automatically watches, ingests, and processes them in the background via filesystem notifications (fsnotify).
  • Automated IMAP Email Import: Connect an IMAP mailbox (Host, User, Password, Folder) with a dedicated rule that imports email attachments automatically every minute and marks messages read.
  • Broad Format Support:
    • Native PDFs (application/pdf)
    • Raster images (PNG, JPEG/JPG, WebP)
    • Microsoft Word documents (.docx converted to rendered PDF text)
    • Plaintext, Markdown, and CSV (.txt, .md, .csv automatically converted to PDF)
  • Automatic Barcode & QR Code Splitting: Scanned batches containing barcode/QR separator pages are split into separate documents automatically during ingestion.
  • Image Pre-processing: Built-in automated image deskewing and rotation angle correction before OCR.
  • Automatic Library Filing: Organizes stored documents on disk into human-readable directory structures ({Category}/{Year}/{Merchant}_{Date}_{ID}.pdf).
  • Duplicate Detection: SHA-256 content hashing checks for duplicate uploads and prompts the user before storing redundant copies.
⁠OCR & Intelligent Metadata Extraction
  • Multilingual Tesseract OCR:
    • Supports 16+ languages (English, French, German, Spanish, Italian, Portuguese, Dutch, Persian, Arabic, Russian, Chinese Simplified, Japanese, Polish, Turkish, Ukrainian, Hindi).
    • Set global default OCR languages in Settings or customize languages per document and trigger instant re-reading.
  • Structured Field Extraction:
    • Document Type: Auto-classifies as Receipt, Invoice, Contract, Tax Document, Medical, Identification, Warranty, or Other.
    • Merchant / Entity: Identifies the issuer or counterparty.
    • Dates: Identifies Document Date and actionable Due Date.
    • Financials: Currency code, Total Amount, and Tax Amount.
    • Category & Summary: Automated categorization and concise plain-language summary.
    • Action Items: Flags items needing attention (e.g., unpaid invoices, upcoming renewals).
  • Extraction Source Transparency: Every extracted field shows a provenance badge:
    • Estimated (Local rule-based heuristic)
    • Read by <model> (Ollama LLM extraction)
    • Edited by you (User modification)
  • Searchable PDF Generation: Generates an invisible OCR text layer overlay for native text selection and visual keyword highlighting in the viewer.
  • Specialized Form Handlers: Built-in score/test sheet detection and parsing.
⁠Hybrid Search & AI Q&A Engine
  • Hybrid Search (RRF): Merges SQLite FTS5 lexical BM25 matching and sqlite-vec semantic vector search using Reciprocal Rank Fusion (RRF).
  • In-Document Hit Navigation: Search results show exact matching text snippets and page numbers; clicking a result immediately jumps to the page in the document preview.
  • Command Bar Assistant (Cmd+K / Ctrl+K):
    • Ask complex natural language questions about your vault (e.g., "How much did I spend on vehicle maintenance across 2025?" or "Which contracts expire in the next 60 days?").
    • Safe Intent Parsing: Spend and renewal queries execute parameterized database filters rather than letting LLMs generate unsafe raw SQL.
    • Direct Citations: Answers include clickable citation pills that open the exact page and display visual bounding box regions on the document.
    • Thread History: Past conversations and questions are stored and can be resumed at any time.
⁠Document Management & Workflows
  • Pre-configured Sidebar Views:
    • Inbox: All incoming documents.
    • Needs Review: New documents requiring confirmation before being marked reviewed.
    • Invoices, Contracts, Receipts, Tax Files: Filtered views by document type.
    • Expiring Soon: Documents with due dates within the next 60 days.
    • Trash: Soft-deleted documents.
  • Home Metric Strip:
    • Real-time counters for items needing review and due soon.
    • Dynamic currency-separated spend breakdown for the current month.
  • Multi-Criteria Filter Bar: Filter simultaneously by Type, Date range (From/To), Minimum/Maximum Amount, and Needs Attention status.
  • Saved Views: Save any combination of search queries and filter parameters as a pinned custom view in the sidebar.
  • Tagging & Notes: Multi-tag management and arbitrary searchable text notes per document.
  • Custom Key-Value Fields: Add custom metadata fields (e.g., VIN, Account Number, Project) to any document.
  • Batch Operations: Multi-select documents to bulk mark as reviewed, re-read (OCR/AI), move to trash, or restore.
  • Trash Lifecycle: Safe two-stage deletion (Move to Trash $\to$ Restore or permanently Empty Trash).
⁠Page Studio & PDF Manipulation
  • Visual Page Strip: Thumbnail strip of all pages in a document.
  • Rotate Pages: 90-degree increment rotation per page.
  • Reorder Pages: Move pages forward or backward in the sequence.
  • Drop Pages: Delete individual pages from multi-page documents.
  • Merge Documents: Append pages from another document in the vault into the current document.
  • Non-Destructive Saving Options:
    • Replace this document: Updates the working file in place.
    • Save as a new copy: Keeps the original intact and creates a new document.
  • Dual Download Modes: Download the untouched byte-for-byte original file or the current processed/searchable PDF.
⁠Security, Sharing & Multi-User Access
  • Vault Password & Lock Screen: Optional master password protecting all endpoints, APIs, downloads, and the web UI.
  • Network Exposure Alert: Automatic warning banner if the instance is exposed to a non-local network without password authentication.
  • Session Cookie Authentication: Secure session state with lock and unlock support.
  • Multi-User Management: Create named users with separate passwords and role assignments; restrict document visibility on a per-user basis.
  • Expiring Public Share Links: Generate time-limited secure token links (e.g., 7 days) to share individual files without exposing your vault credentials.
⁠Backup, Restore & Maintenance
  • One-Click Backup Export: Downloads a .zip containing all original files, generated PDFs, and a comprehensive JSON metadata manifest.
  • Disaster Recovery Restore: Upload an export .zip to rebuild database records, OCR data, and page renderings.
  • Persistent Docker Volume: All state is localized in /data for standard volume backup solutions.
⁠UI, Theming & Accessibility
  • Theme Switching: Built-in Dark and Light themes.
  • Multilingual UI: Native English and Persian (فارسی) interfaces with Right-to-Left (RTL) support.
  • Layout Modes: Toggle between an interactive Data Table and a visual Thumbnail Card grid.
  • Responsive Mobile Interface: Mobile-friendly layout with horizontal scroll tabs and optimized touch controls.

⁠3. User Guide & Workflows

⁠Step 1: Quick Start & Deployment
  1. Create a docker-compose.yml file or clone the repository:

    services:
      documind:
        image: documind:latest
        build: .
        ports:
          - "8080:8080"
        volumes:
          - documind-data:/data
        environment:
          - DATA_DIR=/data
          - ADDR=:8080
          - OCR_LANGS=eng
          - OLLAMA_URL=http://ollama:11434
          - OLLAMA_CHAT_MODEL=llama3.2
          - OLLAMA_EMBED_MODEL=nomic-embed-text
      ollama:
        image: ollama/ollama
        profiles: ["ai"]
        volumes:
          - ollama-models:/root/.ollama
    volumes:
      documind-data:
      ollama-models:
    
  2. Start the core service:

    docker compose up -d
    
  3. Enable local AI models:

    docker compose --profile ai up -d
    docker compose exec ollama ollama pull llama3.2
    docker compose exec ollama ollama pull nomic-embed-text
    
  4. Open your browser at http://localhost:8080.


⁠Step 2: Adding Documents

You have three ways to import documents into DocuMind:

  1. Web Drag-and-Drop:

    • Drag files directly into the browser window or click the upload area on the main dashboard.
    • Supported files: PDF, PNG, JPG, JPEG, WebP, Word (.docx), .txt, .md, .csv.
    • If a file has already been uploaded, DocuMind alerts you with a duplicate warning and asks if you want to keep a second copy.
  2. Watched Consume Folder:

    • Place files inside the /data/consume folder on your host or container mount.
    • DocuMind processes and indexes files automatically as soon as they appear.
  3. Email Import (IMAP):

    • Click Settings $\to$ Mailbox.
    • Enable mailbox scanning and enter your IMAP server credentials (host, username, password, folder).
    • DocuMind checks every minute for new messages with attachments, ingests them, and marks the email as read.

⁠Step 3: Reviewing & Editing Documents
  1. Accessing the Needs Review Queue:
    • Newly added documents arrive in the Needs review view (accessible from the sidebar or the dashboard counter).
  2. Detail Drawer:
    • Click any row or card to open the document inspection drawer.
    • The left pane shows the document preview with OCR highlight overlays.
    • The right pane displays extracted metadata.
  3. Editing Fields:
    • Click any field (Document Type, Merchant, Document Date, Due Date, Total, Tax, Category, Summary) to update it.
    • Click Accept fields to mark the document as verified.
  4. Custom Fields & Notes:
    • Add custom key-value pairs (e.g., Policy Number: 98124) in the Fields section.
    • Write persistent notes in the Note text area; notes are automatically indexed in search.
  5. Tags:
    • Add custom tags or click existing tag badges to remove them.

⁠Step 4: Editing Pages & Merging Documents

If a scan is upside down, missing pages, or needs to be combined with another file:

  1. Open the document in the Detail Drawer.
  2. Click Edit pages under the preview window to expand the Page Studio.
  3. Manipulating Pages:
    • Rotate: Click the rotate icon (⟳) on any thumbnail to rotate it by 90°.
    • Reorder: Click the Up (↑) or Down (↓) arrows to change page order.
    • Delete: Click the trash icon to remove a specific page.
  4. Merging Documents:
    • In the Append another document dropdown, choose another document from your vault and click Merge.
  5. Saving Changes:
    • Click Save pages.
    • Choose Replace this document to update the existing file or Save as a new copy to keep the original file untouched.

⁠Step 5: Searching & Asking Questions
  • Use the search bar in the header to search by merchant, content, notes, or tags.
  • Search hits display the matching page and context; clicking a snippet takes you directly to the highlighted page in the viewer.
⁠AI Assistant (Cmd+K / Ctrl+K)
  • Press Cmd+K (macOS) or Ctrl+K (Linux/Windows) anywhere in the application.
  • Ask questions in plain English:
    • "How much did I spend on electricity in 2025?"
    • "What is the policy number on my health insurance?"
    • "Show me invoices due in the next 30 days."
  • Click any Show in file citation badge to open the document directly at the cited location.

⁠Step 6: Custom Views & Filtering
  1. Click the Filters button above the document list.
  2. Filter by:
    • Type (e.g., Invoice, Receipt, Contract)
    • Date Range (From / To)
    • Amount Range (Min / Max)
    • Needs attention (flagged action items)
  3. Saving a View:
    • Click Save view at the end of the filter bar.
    • Enter a name (e.g., 2025 Tax Receipts).
    • The saved view will appear permanently in the left sidebar for one-click access.

⁠Step 7: Sharing & User Management
  1. Creating a Temporary Share Link:
    • Open a document in the Detail Drawer and click Copy a 7-day link.
    • Anyone with this link can view and download the document without entering the vault password. The link automatically expires after 7 days.
  2. Setting Up Additional Users:
    • Open Settings $\to$ People.
    • Enter a name and password to add a new user.
    • Assign per-document visibility so users only see files explicitly shared with them.

⁠Step 8: Backups & Disaster Recovery
  1. Creating a Backup:
    • Open Settings $\to$ Backup.
    • Click Download backup.
    • DocuMind generates a .zip containing all originals, processed PDFs, page images, and metadata.
  2. Restoring a Backup:
    • In Settings $\to$ Backup, click Restore from zip and upload your backup file.
    • The system validates and imports all documents and metadata.

⁠4. Configuration & Environment Reference

You can configure DocuMind via environment variables:

VariableDefaultDescription
DATA_DIRdataRoot path for SQLite database, originals, page renders, thumbnails, and the consume folder.
ADDR:8080HTTP listen address.
OLLAMA_URL"" (empty)Ollama base URL (e.g. http://localhost:11434). If omitted, AI extraction is disabled and local heuristics are used.
OLLAMA_CHAT_MODELllama3.2Ollama model used for field extraction, summarization, and chat.
OLLAMA_VISION_MODEL"" (empty)Vision model (e.g., llama3.2-vision) used to analyze images directly when GPU memory allows.
OLLAMA_EMBED_MODELnomic-embed-textModel used for semantic vector embeddings.
EMBED_DIM768Embedding vector dimension for sqlite-vec.
OCR_LANGSengDefault Tesseract language codes separated by + (e.g., eng+fra+deu).
MAX_OCR_PAGES15Maximum number of pages rasterized and OCR'd per document.
WORKERS2Number of concurrent background worker ingestion jobs.

⁠5. Keyboard Shortcuts & UI Cheat Sheet

Shortcut / ActionScopeDescription
Cmd + K / Ctrl + KGlobalOpen the AI Command Bar and conversational search assistant.
EscGlobalClose open drawers, modals, settings panels, or the Command Bar.
/DashboardFocus the header search input.
Drag & DropMain WindowDrop files anywhere to initiate upload.
Select CheckboxesTable/RowsSelect multiple documents to reveal bulk action buttons (Review, Read Again, Trash).
Click Search HitSearch ResultsJumps directly to the matching page in the document preview.
Theme ToggleSettingsSwitch between Dark and Light mode.
Language ToggleSettingsSwitch interface between English and Persian (فارسی).

Tag summary

Content type

Image

Digest

sha256:3aa99b1bb…

Size

111.6 MB

Last updated

14 days ago

docker pull sinarah/documind