Mobile Apps & Standalone Mode
Relevant source files
The following files were used as context for generating this wiki page:
Hearth provides a mobile experience through Capacitor-based native shells for iOS and Android. The mobile implementation supports two distinct operating modes: Connected Mode, which acts as a WebView wrapper for a self-hosted Hearth server, and Standalone Mode, which functions as a fully offline, device-local application. Standalone mode stores all data in an encrypted SQLite database on the device and manages documents in app-private storage.
Sources: CLAUDE.md:129-142, PRODUCT.md:30-34, ios-shell/www/app.js:10-25
Runtime Modes
When you first launch the mobile app, you must choose how the application manages your household records.
Connected Mode
In this mode, the app functions as a thin native wrapper. It points a WKWebView at your self-hosted Hearth server URL.
- Handoff: The
ServerConfigplugin manages the connection. - Auth: It uses the server's NextAuth implementation (credentials, JWT, and optional passkeys).
- Persistence: The server URL is stored in native app-private storage (Android
SharedPreferences/ iOSUserDefaults).
Sources: ios-shell/www/app.js:132-135, ios-shell/www/index.html:15-28, PRIVACY.md:18-28
Standalone Mode
Standalone mode provides a private, offline experience. It requires a one-time non-consumable purchase via RevenueCat to unlock.
- Storage: Uses
@capacitor-community/sqlitewith AES encryption. - Files: Stores documents in app-private storage using the
Filesystemplugin. - Reminders: Uses
LocalNotificationsinstead of the server's node-cron scheduler. - Logic: Duplicates core application logic in a vanilla-JS entrypoint (
ios-shell/www/app.js).
Sources: ios-shell/www/app.js:136-148, CLAUDE.md:144-149, ios-shell/www/index.html:30-41
Mode Selection Flow
The following diagram illustrates the initial decision tree for the mobile app:
The application checks for a saved mode in Preferences before rendering the appropriate interface.
Sources: ios-shell/www/app.js:1745-1758, ios-shell/www/index.html:10-41
Standalone Data Architecture
Standalone mode relies on several native plugins to replicate server-side functionality locally.
Local Database Schema
The app initializes an encrypted SQLite database named hearth_standalone. The schema includes tables for contracts, products, vehicles, properties, inventory, trips, wealth portfolios, and documents.
| Table | Key Fields | Purpose |
|---|---|---|
local_profile | display_name, default_currency | Basic app settings. |
contracts | title, cost, reminder_days_before | Household service agreements. |
products | description, warranty_end_date | Warranty tracking. |
documents | storage_key, sha256, is_head | Metadata for attached files. |
trades | ticker, units, price_per_unit | Ledger for wealth holdings. |
Sources: ios-shell/www/app.js:68-228
Document Management
The mobile shell handles file uploads by sniffing MIME types and generating unique storage keys to prevent path traversal.
- Validation: Files are limited to 15MB and specific types (PDF, Word, JPEG, PNG, WEBP, HEIC).
- Storage: The
Filesystemplugin writes data to theDATAdirectory under thestandalone-documentsroot. - Deduplication: The app computes a SHA-256 hash to detect possible duplicates in the inbox.
Sources: ios-shell/www/app.js:462-520, ios-shell/www/app.js:522-540
Local Reminders System
Standalone mode implements a local reminder engine that replaces the server's notification scheduler. It calculates notification dates based on the reminder_days_before field (defaulting to 30,14,7,1).
The system schedules notifications at a fixed time (09:00 AM) on calculated threshold dates.
Sources: ios-shell/www/app.js:770-850, ios-shell/www/app.js:930-970
Synchronization and Parity
Because ios-shell/www/app.js is a separate ~4,000 line vanilla JavaScript implementation, changes to the main Next.js application require manual parity updates.
- Logic Duplication: Data validation, monthly cost calculations, and wealth cost-basis logic (FIFO) are re-implemented in JavaScript.
- Wealth Module: While the server uses live price feeds, the standalone mode calculates holdings solely from the local trade history ledger.
- Backup/Restore: Standalone mode supports manual JSON exports. These backups include full database records and base64-encoded document contents.
Sources: ios-shell/www/app.js:1220-1250, CLAUDE.md:151-157, ios-shell/www/app.js:1085-1108
Technical Constraints
Standalone mode has specific limitations compared to the self-hosted server:
- AI Extraction: Local document extraction is not yet supported in the mobile shell; extraction is "Connected-only" until a local engine is added.
- Integrations: Live price feeds, S3/SFTP backups, and email ingestion are unavailable in standalone mode.
- Multi-user: Standalone records are private to the device and cannot be shared with other household members.
Sources: ios-shell/www/app.js:1010-1018, src/lib/help/faq.ts:25-33, PRODUCT.md:30-34
Standalone mode provides a robust, privacy-first alternative for users who do not wish to manage a server, though it requires manual management of backups and lacks the automated AI features of the Connected experience.