Contracts & Policies Module
Relevant source files
The following files were used as context for generating this wiki page:
The Contracts & Policies module tracks recurring household agreements, insurance policies, loans, and subscriptions. It operates as an "always-on" core module that manages renewal dates, costs, and provider contacts. The system uses a multi-stage AI extraction pipeline to populate contract data from uploaded documents, which requires human confirmation to re-arm reminders.
Sources: PRODUCT.md:20-22, GLOSSARY.md:38-40, CLAUDE.md:83-84
Data Model and Relationships
Contracts represent ongoing agreements with specific terms, costs, and providers. The data model supports linking contracts to specific household assets like properties or vehicles.
Contract Entity Structure
A contract record contains metadata regarding the provider, financial commitments, and timing requirements.
| Field | Type | Description |
|---|---|---|
title | String | Short descriptive title for the agreement. |
category | Enum | The kind of contract (e.g., INSURANCE, UTILITY, RENTAL). |
provider | String | The company or entity providing the service. |
startDate | Date | The beginning of the current term. |
endDate | Date | The expiration date of the current term. |
renewalType | Enum | Determines if renewal is AUTO_RENEW, MANUAL_RENEWAL, or FIXED_TERM. |
noticePeriodDays | Int | Days required to notify provider before cancellation/non-renewal. |
cost | Float | The financial amount of the contract. |
billingFrequency | Enum | How often the cost is charged (e.g., MONTHLY, ANNUALLY). |
status | Enum | Current state: ACTIVE, CANCELLED, or EXPIRED. |
Sources: src/lib/chat/tools.ts:58-76, src/lib/mcp/server.ts:16-35, GLOSSARY.md:41-65
Relationship Diagram
The following diagram illustrates how contracts connect to other system modules and documents.
Lifecycle and Workflow
Document Extraction and Confirmation
When you upload a document, the system attempts to auto-fill fields using a three-stage pipeline: text extraction, heuristic rules, and optional cloud AI. Any record populated this way is marked "Needs review" until a user saves the record or clicks a confirmation banner. Reminders are held until this confirmation occurs.
Sources: src/components/ContractForm.tsx:88-124, src/app/(app)/contracts/[id]/page.tsx:109-119, CLAUDE.md:87-101
Timing and Notice Deadlines
The module differentiates between an endDate and a notice deadline. The notice deadline is the endDate minus the noticePeriodDays. Reminders fire based on the earliest upcoming deadline.
- Expired: A manual-renewal contract past its end date.
- Ended: A fixed-term contract past its end date (not considered "Due").
- Cancelled: A contract deliberately terminated by a user.
Sources: GLOSSARY.md:47-65, src/app/(app)/contracts/[id]/page.tsx:68-73
Filtering and Housekeeping
The system categorizes contracts to identify those needing user attention. "Missing key details" specifically flags contracts that are not yet useful for automation.
Completeness Rules
A contract is flagged for "Missing key details" if it meets the following criteria:
- It is ACTIVE.
- It lacks an
endDatewhile having arenewalTypeother thanAUTO_RENEW. - It has a
costbut nobillingFrequency.
Sources: tests/unit/record-filters.test.ts:107-111, src/app/(app)/contracts/page.tsx:36-39
List Filters
| Filter Parameter | Logic |
|---|---|
due=soon | Deadline within the household's reminder window. |
due=overdue | Deadline has passed and status is ACTIVE. |
missing=details | Meets the completeness rules above. |
review=1 | Record was AI-extracted and not yet confirmed. |
noDocument=1 | Contract has no active documents attached. |
Sources: src/app/(app)/contracts/page.tsx:49-75, tests/unit/record-filters.test.ts:168-185
Integration and Tooling
Model Context Protocol (MCP) and Assistant
The module exposes read-only tools to LLMs and external agents via the MCP server and the internal Assistant. These tools calculate spend summaries and renewal timelines dynamically.
spend_summary: Estimates total and per-category monthly spend. It sums costs by converting different billing frequencies to a monthly equivalent.upcoming_renewals: Returns active contracts with deadlines within a specified horizon (default 30 days).propose_update_contract: A "guarded write" tool that validates proposed changes against Zod schemas without committing them to the database.
Sources: src/lib/chat/tools.ts:133-159, src/lib/mcp/server.ts:107-130, src/lib/chat/tools.ts:245-283
Spend Calculation
The system calculates estimatedMonthlySpend by applying factors to the cost based on billingFrequency:
- Weekly: 52 / 12
- Fortnightly: 26 / 12
- Annually: 1 / 12
- One-off: 0 (excluded from monthly totals)
Sources: src/lib/chat/tools.ts:143-148, src/app/(app)/dashboard/page.tsx:75-87
Summary
The Contracts & Policies module serves as the primary engine for tracking recurring household obligations. It leverages AI for data entry efficiency while maintaining a strict confirmation workflow to ensure reminder accuracy. By integrating with the Properties and Vehicles modules, it provides a unified view of the costs and legal requirements associated with household assets.
Sources: PRODUCT.md:31-35, GLOSSARY.md:144-162