[Feature]: One-Click Property Information Retrieval (Auto-fill)

[important-new]

Problem

To reduce manual data entry time for inspectors, we need to implement a feature that fetches basic property details (sqft, bedrooms, bathrooms, year built) automatically once a property address is provided. This will improve workflow efficiency and data accuracy.

Proposed solution

Proposed Workflow

1. Address Input: Inspector enters or selects an address (via Google Places Autocomplete).
2. Trigger: A new "Fetch Property Details" button appears next to the address field.
3. API Integration: Upon clicking, the system calls a property data provider (e.g., RealEstateAPI.com).
4. Auto-population: The relevant fields in the project form (e.g., Living Sqft, Bedrooms, Bathrooms, Year Built) are automatically populated.
5. Manual Override: The user retains the ability to edit any pre-filled fields if the data is outdated or incorrect.

Override Logic & Data Protection

• API Selection: Integrate with [RealEstateAPI.com](https://www.realestateapi.com/) for property data.
• Caching Strategy: Before calling the external API, the system must check our local database for existing data associated with the normalized address. If found, return cached data to save API costs.
• UI Update: Add a "loading" state during the API request and provide feedback if the address is not found in the database.
• Field Mapping: Map API response fields to the internal Property schema (e.g., living_sqft, bedrooms, bathrooms, year_built).
• Persistence: Store the fetched data in our PostgreSQL database for future reference.

Technical Requirements

To prevent accidental data loss when an inspector has already started filling out the form manually, the following state machine should be implemented upon receiving the API response:

• Scenario A (Empty Fields): If all target property fields are currently empty, auto-fill the data immediately without prompting.

• Scenario B (Existing Data): If one or more target fields already contain user-inputted values, intercept the auto-fill and trigger a Confirmation Modal:

  • Modal Title: Overwrite Existing Data?

  • Modal Body: "We found official tax records for this property. Would you like to overwrite your current inputs with the fetched data?"

  • Actions: [Cancel] (Dismisses modal, keeps current inputs) / [Confirm Overwrite] (Replaces inputs with API data).

Field Mapping Table

RealEstateAPI Key (Source)	Internal DB Field	Data Type	Implementation Notes
bedrooms	bedroom_count	Integer	Standard integer count
bathrooms	bathroom_count	Float	Support half-baths (e.g., 2.5)
square_footage	living_sqft	Integer	Total interior living area
year_built	year_built	Integer	YYYY format
property_type	property_type	String	Standardize to internal enums (e.g., "SFR", "Condo")
address.formatted	normalized_address	String	Used to match and verify cache hits

Acceptance Criteria

• Clicking the "Fetch" button correctly triggers the API service.
• Form fields are successfully auto-populated with data.
• The Confirmation Modal accurately detects existing form data and prevents accidental overwrites.
• Existing project data is NOT overwritten if the user has already manually input values (optional: confirm via a toast message/prompt if data already exists).
• All auto-filled text fields remain fully editable by the inspector post-fetch.
• API costs are minimized by using a caching mechanism. The local database cache successfully intercepts external API calls for duplicate addresses within a 30-day window.
• The feature handles edge cases (e.g., address not found, API timeout) gracefully.

Notes

• We should prioritize accuracy for common residential property types.
• Ensure the API key is handled securely in the backend environment variables.
• The default UI should allow inspectors to override any fetched data, as tax records may occasionally be outdated.
• Ensure the UI clearly communicates that these are "official tax record suggestions" so inspectors know they can (and should) verify them on-site.

Alternatives considered

No response

Who would benefit?

Solo inspector, Self-hoster / IT admin

Code of conduct

• I have read and agree to the Code of Conduct.

[important-new]

Shipped via #259 (squash 63bb997b): the editor's "Fetch property details" button looks up public-records property facts and fills only the fields the inspector hasn't already set, degrading to a clear not-configured notice when ESTATED_API_KEY is unset. Closing as done.