Glossary & Terminology
Relevant source files
The following files were used as context for generating this wiki page:
Hearth defines a specific set of terms to describe household management, assets, and agreements. These terms ensure consistency across the web interface, the mobile shell, and the underlying database schema. The project prioritizes household-wide visibility over individual user silos, meaning every record belongs to the household as a collective entity.
This glossary serves as the single source of truth for naming conventions within the codebase and documentation. It differentiates between similar concepts, such as "Warranties" versus "Contracts," and "Lapsed" versus "Expired" states, to maintain technical precision.
Household and Roles
The Household is the primary organizational unit in Hearth. It represents a group of people who share one instance and have equal visibility of all records.
| Term | Definition |
|---|---|
| Household | The group sharing one Hearth instance. They see and edit the same records. |
| Admin | A role that manages household members, webhooks, backups, and modules. |
| Member | A role that can add, edit, and delete the household's records. |
| Read-only | A role that can view records but cannot perform any writes or modifications. |
Sources: GLOSSARY.md:6-8, src/lib/help/faq.ts:25-27, PRODUCT.md:38-41
Data Visibility Relationship
This diagram illustrates how roles gate actions while maintaining shared data visibility across the household.
Sources: src/lib/help/faq.ts:25-27, CLAUDE.md:144-149
Assets and Inventory
Hearth categorizes physical possessions and dwellings into distinct record types.
Things Owned
- Item: A physical object owned by the household (e.g., fridge, laptop).
- Property: A building or dwelling owned or rented by the household.
- Vehicle: A registered car, motorbike, or other vehicle.
- Service Record: A log of work or money spent on a Vehicle.
- Maintenance Record: A log of work or money spent on a Property.
Sources: GLOSSARY.md:12-32, ios-shell/www/app.js:63-67
Asset States
- Archived: A deliberate state for an asset the household no longer possesses (sold, discarded). Its history is preserved.
- Lapsed: Specific to Warranties; indicates the end date has passed. A Lapsed warranty is never "Due."
- Missing Key Details: A housekeeping state for records lacking critical identifiers (e.g., a Vehicle with no VIN or plate).
Sources: GLOSSARY.md:21-26, GLOSSARY.md:154-162, tests/unit/record-filters.test.ts:135-140
Agreements and Contracts
Agreements represent ongoing commitments with external providers. Hearth distinguishes between recurring agreements and one-time coverage.
Record Types
- Contract: An ongoing agreement with a recurring cost or term (e.g., insurance, phone plan, lease).
- Warranty: Coverage for an Item against faults. It always belongs to an Item.
- Term: A specific period of a Contract with a start/end date and cost.
- Tenancy: A property let out to a tenant (income-generating), distinct from a rental Contract (expense).
Sources: GLOSSARY.md:36-47, GLOSSARY.md:73-75
Contract and Warranty Lifecycle
This diagram shows the state transitions for agreements based on user actions and time.
Reminders and Attention
The system uses a specific vocabulary to describe how it alerts the household to upcoming obligations.
- Needs Attention: The central queue for items requiring action, split into Due and Housekeeping.
- Due: An entry whose date is within its Due-soon window or has passed.
- Overdue: A Due entry whose date has passed without action.
- Reminder Threshold: The number of days before a date that a notification is sent (default: 30, 14, 7, 1).
- Housekeeping: Items needing "tidying" rather than responding to a date (e.g., Needs Review or Missing Key Details).
Sources: GLOSSARY.md:131-152, src/lib/help/faq.ts:56-62
Document Management
Documents are files (PDFs, images, Word docs) attached to records or entries.
- Document: A file attached to a specific record. It can be starred or superseded by newer versions.
- Inbox: A temporary holding area for documents uploaded before being linked to a record.
- Needs Review: A state for records automatically filled by AI/extraction that require human confirmation.
Sources: GLOSSARY.md:109-123, CLAUDE.md:78-83
Document Extraction Pipeline
Hearth uses a three-stage process to extract metadata from documents.
Sources: CLAUDE.md:65-74, PRODUCT.md:27-30
Wealth and Travel Modules
These opt-in modules use domain-specific terminology for planning and financial tracking.
| Module | Term | Definition |
|---|---|---|
| Travel | Trip | A journey made of segments. |
| Travel | Trip Segment | A specific leg of a trip (flight, stay). |
| Wealth | Portfolio | A set of investment holdings. |
| Wealth | Holding | Amount of one asset in a portfolio. |
| Wealth | Trade | A buy or sell action. Cost basis is derived from trades. |
Sources: GLOSSARY.md:88-105, CLAUDE.md:104-108
Hearth's terminology ensures that developers and users share a common language for self-hosted household management, emphasizing privacy, shared visibility, and proactive maintenance.