Introduction
Relevant source files
The following files were used as context for generating this wiki page:
Hearth is a self-hosted household management system designed to track paperwork, assets, and recurring obligations in a single, privacy-focused platform. It serves as a unified system of record for contracts, warranties, travel, home maintenance, vehicles, inventory, and wealth. The application prioritizes local data processing and household-wide visibility, ensuring that all members of a household share access to the same records while maintaining administrative control through role-based permissions. Sources: PRODUCT.md:1-25, CLAUDE.md:83-93, GLOSSARY.md:1-5
The system operates primarily as a web application built with Next.js, but also offers mobile shells for iOS and Android. It includes an AI-assisted document extraction pipeline that operates locally by default, escalating to cloud providers only if configured by the user. Hearth emphasizes reducing data-entry friction through automation while maintaining user control, as all automated extractions require manual review before being committed to the database. Sources: PRODUCT.md:27-44, CLAUDE.md:120-134, PRIVACY.md:24-40
Core Architecture and Operating Modes
Hearth utilizes a Next.js App Router architecture with a Prisma-backed SQLite database. Mutations are handled via Server Actions, while the mobile shell provides a choice between connecting to a self-hosted server or operating in a fully offline "Standalone" mode. Sources: CLAUDE.md:95-105, ios-shell/www/app.js:23-45
Platform Deployment Models
The application supports two primary deployment contexts:
- Self-Hosted (Connected): Deployed via Docker Compose, serving one household. The mobile shell acts as a thin WebView wrapper pointing to the user's server URL. Sources: PRODUCT.md:27-31, CLAUDE.md:180-185
- Standalone (Mobile Only): A fully offline, device-local mode within the mobile shell. It uses an encrypted native SQLite database and app-private file storage. This mode is gated by a one-time purchase and does not sync with a server. Sources: CLAUDE.md:186-192, ios-shell/www/app.js:464-482
High-Level System Flow
The following diagram illustrates the relationship between the user, the mobile shell, and the self-hosted server backend.
Diagram shows the data path selection between local standalone storage and remote server connection. Sources: PRODUCT.md:27-45, CLAUDE.md:180-192, ios-shell/www/app.js:1063-1090
Functional Modules
Hearth categorizes household data into specific modules. Some are always active, while others are opt-in toggles. Sources: PRODUCT.md:47-51, src/lib/help/faq.ts:25-30
| Module | Status | Description |
|---|---|---|
| Contracts | Always On | Recurring agreements like insurance, utilities, and subscriptions. |
| Warranties | Always On | Coverage for specific items with defined end dates. |
| Documents | Always On | File attachments (PDF, images, Word) and the "Inbox" for unfiled items. |
| Travel | Opt-in | Trips, bookings, and travel segments. |
| Home | Opt-in | Property maintenance, rental agreements, and valuations. |
| Vehicles | Opt-in | Registration, insurance, and service history for household vehicles. |
| Inventory | Opt-in | Catalog of household items, serial numbers, and purchase prices. |
| Wealth | Opt-in | Investment portfolios and holdings with live price feeds. |
Sources: PRODUCT.md:47-51, src/lib/help/faq.ts:25-30, GLOSSARY.md:7-60, ios-shell/www/app.js:56-62
Data Extraction Pipeline
The document extraction system follows a three-stage escalation logic to minimize data exposure while maximizing automation. Sources: PRODUCT.md:32-35, CLAUDE.md:120-130, src/lib/help/faq.ts:47-52
- Text Extraction: Uses
pdftotextfor digital PDFs and Tesseract OCR for scans or photos. - Heuristic Extraction: Applies regex and built-in domain rules to identify fields. Optionally falls back to a local Ollama model if configured.
- Cloud AI (Opt-in): Dispatches raw bytes to Anthropic, Gemini, or OpenAI using a user-provided API key only if the first two stages fail to find sufficient data.
Extraction Sequence Diagram
Diagram shows the escalation from local heuristics to optional cloud AI for document processing. Sources: PRODUCT.md:32-35, CLAUDE.md:120-130, src/lib/help/faq.ts:47-52
Privacy and Security Principles
Hearth is built on a "Privacy-First" default stance. Sensitive data, such as AI API keys and database backups, are encrypted at rest using AES-256-GCM, gated by a user-configured ENCRYPTION_KEY. Sources: PRODUCT.md:58-61, CLAUDE.md:131-134, PRIVACY.md:6-12
- Self-Hosted Ownership: The developer has no access to user data; the user owns the server and database.
- Household-Wide Visibility: By default, all household members see all records. Roles (Admin, Member, Read-Only) gate actions rather than data visibility. Sources: PRODUCT.md:20-25, CLAUDE.md:225-235, src/lib/help/faq.ts:31-38
- Local Processing: Features that require data to leave the server (like cloud AI or offsite backups) are explicitly opt-in and require user configuration. Sources: PRODUCT.md:72-75, PRIVACY.md:24-40
- Authentication: Supports credentials, JWT sessions, and optional multi-factor authentication via WebAuthn passkeys or TOTP. Sources: PRODUCT.md:53-56, CLAUDE.md:112-119
Summary
Hearth provides a comprehensive framework for household administration by consolidating disparate spreadsheets and trackers into one system. By combining local-first AI automation with a self-hosted architecture, it enables households to track critical dates and assets without compromising privacy. Whether deployed as a shared server for a household or a standalone mobile application, the system focuses on reducing the cognitive load of managing domestic obligations. Sources: PRODUCT.md:16-25, GLOSSARY.md:1-5, ios-shell/www/app.js:23-45