Document Management
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/(app)/documents/inbox/page.tsx
- src/lib/documents/liveDocuments.ts
- src/components/InboxReviewClient.tsx
- src/app/(app)/documents/page.tsx
- src/lib/commands/documents.ts (Referenced via unit tests)
- src/lib/storage.ts (Referenced via architecture overview)
Document Management handles the storage, classification, and retrieval of household files such as contracts, warranties, and receipts. The system categorizes files into "Filed" documents, which attach to specific records, and "Inbox" documents, which await user review. It employs a three-stage AI extraction pipeline to automatically populate record fields from uploaded files.
Sources: PRODUCT.md, CLAUDE.md, src/app/(app)/documents/page.tsx
Document Lifecycle and Storage
The system stores uploaded documents on disk using generated UUID filenames to prevent path traversal and collisions. Every document record in the database is paired with a physical file. Deletion operations typically move records to a Trash state before permanent purging, ensuring both the database row and the file are removed together.
Sources: CLAUDE.md, tests/unit/document-commands.test.ts:133-138
Document Types
Documents are categorized based on the entity they belong to. The system filters these using specific "Live" queries to exclude deleted items or items belonging to trashed parents.
| Document Type | Parent Entity | Source Table |
|---|---|---|
| Contracts | Contract | document |
| Warranties | Product | productDocument |
| Vehicles | VehicleItem | vehicleItemDocument |
| Travel | TripSegment | tripSegmentDocument |
| Properties | HomeItem / RentalStatement | homeItemDocument / rentalStatementDocument |
| Inventory | InventoryItem | inventoryItemDocument |
| Wealth | Trade | tradeDocument |
| Inbox | None (Pending) | inboxDocument |
Sources: src/app/(app)/documents/page.tsx:37-230, src/lib/documents/liveDocuments.ts
Storage Architecture
The following diagram illustrates the relationship between the storage layer and the application entities.
A brief diagram showing how uploads are processed into UUID-named files on disk while maintaining references in SQLite.
Sources: CLAUDE.md, tests/unit/document-commands.test.ts:98-110
Document Inbox and Classification
The Inbox acts as a staging area for documents that have not yet been linked to a specific household record. Documents can arrive via web upload or email ingestion.
Sources: PRODUCT.md, src/app/(app)/documents/inbox/page.tsx
Classification States
When a document resides in the Inbox, it is assigned a status based on initial processing results:
- NEEDS_REVIEW: The default state for new uploads.
- POSSIBLE_DUPLICATE: Assigned if the file's SHA256 hash matches an existing document.
- EXTRACTION_FAILED: Assigned if the automated extraction pipeline fails to process the file.
- NEEDS_CLASSIFICATION: The document requires the user to select a target record type.
Sources: src/components/InboxReviewClient.tsx:18-32, src/app/(app)/documents/inbox/page.tsx:61-78
The Review Process
Users classify inbox documents by selecting a target entity (e.g., Contract, Warranty, or Inventory Item). The system then presents a form pre-filled with extracted data for confirmation.
A sequence diagram showing the workflow from selecting a document in the inbox to filing it as a record.
Sources: src/components/InboxReviewClient.tsx:289-325, src/components/InboxReviewClient.tsx:341-385
AI Extraction Pipeline
Hearth uses a three-stage pipeline to extract metadata from documents, ensuring privacy by prioritizing local processing.
- Text Extraction: Uses
pdftotextfor text-layer PDFs or OCR (Tesseract) for scans and photos. - Heuristic Extraction: Applies regex and built-in rules for common document types (invoices, leases, trips).
- Cloud AI (Optional): If local methods fail, the system uses user-provided API keys for Anthropic, Gemini, OpenAI, or OpenRouter.
Sources: CLAUDE.md, PRODUCT.md, src/lib/help/faq.ts:40-44
User Interface Indicators
To maintain transparency, the UI uses color-coded highlights to show the source of auto-filled data:
- Accent Color: Data matched via built-in heuristic rules.
- Blue/Grey Color: Data suggested by AI models.
Sources: src/components/InboxReviewClient.tsx:156-163, src/lib/help/faq.ts:45-48
Document Versions and History
The system supports document versioning through a supersession mechanism. When a new file is uploaded to replace an existing one, it is linked via a supersedesId.
- Head Document: The most recent version of a document, identified by
isHeador by not being superseded by another record. - Version Chain: A backward-walking list of documents starting from the head to the original upload.
Sources: src/components/DocumentList.tsx:23-44, tests/unit/document-commands.test.ts:167-175
Security and Access Control
Access to document management is gated by household roles. While visibility is generally household-wide, write actions are restricted.
- ADMIN / MEMBER: Can upload, classify, edit, and delete documents.
- READONLY: Can view documents and download files but cannot perform any write operations, including classification or trashing.
- Encryption: API keys for cloud providers and offsite backups are encrypted at rest using AES-256-GCM.
Sources: CLAUDE.md, PRODUCT.md, src/components/InboxReviewClient.tsx:135-139
Document Management serves as the central repository for the household's digital paperwork, reducing manual entry through automated extraction while maintaining strict privacy controls via local-first processing.