High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• PRODUCT.md
• ios-shell/www/app.js
• src/lib/chat/tools.ts
• src/app/(app)/dashboard/page.tsx/dashboard/page.tsx)
• src/lib/help/faq.ts
• GLOSSARY.md

Hearth is a self-hostable household management system designed to track paperwork, assets, and financial obligations in a single shared environment. It functions as an all-in-one system of record for contracts, warranties, travel, home maintenance, vehicles, inventory, and wealth. The system prioritizes privacy by using local extraction and self-hosted infrastructure via Docker. Sources: PRODUCT.md:1-25, CLAUDE.md:38-44

The architecture supports a household-wide visibility model where every member sees the same records. Roles (Admin, Member, Read-Only) gate specific actions rather than data access. Sources: PRODUCT.md:68-71, CLAUDE.md:151-158, src/lib/help/faq.ts:25-33

System Overview

Hearth utilizes a Next.js App Router framework with TypeScript. It employs Prisma for database orchestration (SQLite via LibSQL) and NextAuth.js for session management. The system is composed of a web application and a specialized mobile shell. Sources: CLAUDE.md:38-44

Core Components

Component	Technology	Responsibility
Frontend	Next.js / Tailwind CSS	Provides the user interface and handles client-side state.
Backend	Next.js Server Actions	Primary write path for mutations and database interactions.
Database	SQLite (Prisma)	Stores household records, documents, and user sessions.
Mobile Shell	Capacitor	Wraps the web app or provides a standalone native experience.
AI Pipeline	Custom Typescript Logic	Processes document extraction in three stages (Local → OCR → Cloud).

Sources: CLAUDE.md:38-44, 76-88, PRODUCT.md:40-47

Data Flow Architecture

Hearth's primary data flow revolves around Server Actions for writes and a multi-stage pipeline for document processing.

Document Extraction Pipeline

When a user uploads a document, the system attempts to auto-fill fields through three escalating stages.

Notification and Reminder Flow

The system uses node-cron to trigger a scheduler that checks for upcoming thresholds (e.g., contract expiry).

Mobile Architecture

The mobile implementation consists of a Capacitor shell that supports two distinct operating modes. This shell uses a single handwritten app.js file (~4k lines) to manage native interactions and standalone logic. Sources: CLAUDE.md:141-150, ios-shell/www/app.js:1-15

Runtime Modes

1. Connected Mode: A WebView points to the user's self-hosted server URL. Native plugins manage mTLS certificates and URL handoffs.
2. Standalone Mode: A fully offline, device-local application. It uses an encrypted native SQLite database and app-private file storage. Standalone mode requires a one-time purchase via RevenueCat.

Sources: ios-shell/www/app.js:15-32, CLAUDE.md:162-178, ios-shell/www/index.html:10-60

Standalone Data Schema

In standalone mode, app.js initializes a local SQLite schema that mirrors the server's data structure.

Module Enablement System

Hearth uses a "Module" concept to toggle features like Travel, Home, and Wealth. While Contracts and Products are always-on, other domains are opt-in. Sources: CLAUDE.md:89-97, src/lib/help/faq.ts:15-22

Registry and Security

• Registry: src/lib/modules/registry.ts serves as the single source of truth for module metadata (labels, icons, routes).
• Enablement: requireModuleEnabled(key) is called at the top of pages or actions. If a module is disabled, the system returns a 404 or redirects to prevent data leaks. Sources: CLAUDE.md:93-97

AI and Integration Architecture

The system supports an optional AI Assistant and a read-only Model Context Protocol (MCP) server. Sources: CLAUDE.md:134-140, src/lib/chat/tools.ts:1-35

AI Assistant Tools

The Assistant uses "Guarded Writes." Tools do not write directly to the database; instead, they validate data against Zod schemas and return a "proposed action" for user confirmation in the UI. Sources: src/lib/chat/tools.ts:326-350

Tool Context and Security

export interface ToolContext {
  userId: string;
  role: Role;
  enabledModules: Set<ModuleKey>;
}

Tools are filtered based on the user's role and enabled modules. READONLY users cannot access write tools. Sources: src/lib/chat/tools.ts:19-25, 435-442

Summary

The Hearth architecture is a hybrid system combining a robust Next.js server-side environment with a flexible mobile shell. By utilizing a multi-stage document pipeline and a household-wide data model, it provides a centralized system of record while maintaining strict data privacy through self-hosting and local-first strategies. Sources: PRODUCT.md:15-35, CLAUDE.md:38-50