Home & Properties Module
Relevant source files
The following files were used as context for generating this wiki page:
The Home & Properties module manages physical dwellings, maintenance activities, and rental tenancies for a household. It tracks buildings the household owns or rents, records maintenance history, manages valuations for net worth calculations, and handles income tracking for properties let to tenants.
Sources: PRODUCT.md, GLOSSARY.md:27-28
Core Entities and Data Model
The module centers around the Property entity, which serves as the parent for maintenance records, tenancies, and valuations.
Entity Definitions
| Entity | Description |
|---|---|
| Property | A building or dwelling the household owns, rents, or lets out. |
| Maintenance record | A record of work done or money spent on a Property (e.g., repairs, improvements). |
| Tenancy | Tracks rent, bond, and lease dates for a Property the household lets out to a tenant. |
| Rental statement | A periodic statement from a property manager showing rent received and fees deducted. |
| Valuation | An estimate of a Property's worth used for net worth calculations. |
Sources: GLOSSARY.md:27-51, src/app/(app)/home/[id]/page.tsx:216-258
Relationships
Properties link to contracts and products. A maintenance record can also have documents (e.g., invoices) attached to it.
The diagram shows the hierarchical relationship where a Property owns multiple maintenance records, tenancies, valuations, and rental statements.
Sources: tests/unit/home-commands.test.ts:98-103, src/app/(app)/home/[id]/page.tsx:216-258
Features and Logic
Maintenance Tracking
Maintenance records (categorized as Maintenance, Improvement, Repair, or Other) track costs and providers for property upkeep. If a record is tax-deductible, the system summarizes this spending by financial year.
Sources: src/app/(app)/home/[id]/page.tsx:26-31, src/components/HomeListClient.tsx:50-61
Tenancy and Rental Management
The module handles rental income via the Tenancy and Rental Statement entities.
- Tracking: Users enable rental tracking by setting the property status to
RENTED. - Contract Linking: A Tenancy can link to a
RENTALcategory Contract. The system prevents linking contracts from other categories or contracts already linked to other tenancies. - Statement Calculation: Rental statements calculate net amounts by subtracting management fees and other deductions from gross rent.
Sources: src/lib/actions/home.ts:213-225, tests/unit/home-commands.test.ts:251-276, ios-shell/www/app.js:1449-1466
Property Valuations
Valuations track the market value of properties over time.
- Stale Data: Valuations older than 12 months are marked as "stale," prompting the user to update the record.
- Net Worth: These values integrate into the broader Wealth module to estimate household net worth.
Sources: src/app/(app)/home/[id]/page.tsx:35-37, src/app/(app)/home/[id]/page.tsx:216-231, ios-shell/www/app.js:435-442
Architecture and Data Flow
The module uses Server Actions for mutations and a Command pattern for database operations.
Mutation Flow (Server Actions)
When a user submits a property form, the following flow occurs:
- Authentication: The system validates the user session and checks if the
HOMEmodule is enabled. - Validation: Data is validated against Zod schemas (e.g.,
propertySchema). - Command Execution: A command (e.g.,
updatePropertyCommand) executes the Prisma write. - Revalidation: The system calls
revalidatePathto refresh the UI and redirects the user.
The sequence diagram illustrates the flow from form submission through validation and command execution to the final database update and UI revalidation.
Sources: src/lib/actions/home.ts:72-102, tests/unit/home-commands.test.ts:68-73
Offline and Mobile Implementation
The iOS/Android shell provides a "Standalone" mode that replicates the Home module using an encrypted native SQLite database.
- Schema: The mobile shell defines tables for
properties,home_items,rental_agreements, andrental_statementsmirroring the server-side Prisma schema. - Offline Edits: In the web app, offline edits are cached using
cachePageDataand synchronized when the connection returns.
Sources: ios-shell/www/app.js:116-169, src/components/HomeListClient.tsx:40-42
Technical Interface
Key Server Actions
| Function | Parameters | Action |
|---|---|---|
createProperty | formData | Creates a new property record. |
addHomeItem | propertyId, formData | Adds a maintenance record and optionally attaches a document. |
setRentalAgreementContract | propertyId, agreementId, formData | Links a Tenancy to a specific Contract. |
setPropertyRented | propertyId, isRented | Toggles rental tracking for a property. |
Sources: src/lib/actions/home.ts:72-243
AI Assistant Tools
The module exposes the list_properties tool to the AI Assistant. This tool queries the database for properties, including their rental status, current tenants, and the most recent valuations.
Sources: src/lib/chat/tools.ts:182-190
Summary
The Home & Properties module provides a comprehensive system for tracking the lifecycle and financial performance of household real estate. By integrating maintenance history, rental income, and market valuations, it ensures all property-related data is centralized and accessible for household management and financial planning.
Sources: PRODUCT.md, GLOSSARY.md