Maps & Geocoding
Relevant source files
The following files were used as context for generating this wiki page:
Hearth provides integrated mapping and geocoding capabilities to visualize property locations and automate address entry within the Home module. The system renders interactive maps using Leaflet and resolves geographical coordinates through an external geocoding provider.
These features allow users to view property locations on a map within the property detail view and receive address suggestions while filling out property forms. Mapping and geocoding are primarily utilized within the HOME module context.
Sources: PRODUCT.md, src/app/(app)/home/[id]/page.tsx:28
Map Visualization
The mapping system renders a visual representation of a property's location using the Leaflet library. The primary component for this visualization is PropertyMap.tsx.
Architecture and Data Flow
Map rendering occurs on the client side. The server resolves tile configuration (URL and attribution) from environment variables before passing them to the client component. If a property has lat and lng values defined, the property detail page initializes the PropertyMap component.
Sources: src/app/(app)/home/[id]/page.tsx:123-130, src/components/PropertyMap.tsx:1-10
Summary of map initialization data flow from server configuration to client rendering.
Sources: src/lib/mapTiles.ts, src/components/PropertyMap.tsx:30-45
Map Tile Configuration
Hearth defaults to OpenStreetMap for map tiles but allows administrators to configure custom tile providers via environment variables.
| Configuration Variable | Purpose | Default Value |
|---|---|---|
MAP_TILE_URL | The template URL for map tiles (supports {z}/{x}/{y} and {s}). | https://tile.openstreetmap.org/{z}/{x}/{y}.png |
MAP_TILE_ATTRIBUTION | Legal credit text displayed on the map. | © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors |
MAP_TILE_SUBDOMAINS | Subdomains for the tile provider (e.g., "abc"). | Not set (optional) |
| Sources: src/lib/mapTiles.ts:4-31, tests/unit/mapTiles.test.ts:41-45 |
Security and Referrer Policy
Hearth enforces a strict referrer policy for map requests. Most application requests use Referrer-Policy: no-referrer, but because OpenStreetMap tile servers require a Referer header to function, the PropertyMap component explicitly overrides the policy to strict-origin specifically for tile layer requests.
Sources: src/components/PropertyMap.tsx:42-49
Geocoding and Address Suggestions
The geocoding system converts human-readable address text into geographic coordinates (Latitude and Longitude) and structured address components.
Geocode Integration Flow
When a user types into the "Street" field of a PropertyForm, the application performs an asynchronous lookup to fetch suggestions. This process includes a 300ms debounce to limit API calls.
Sources: src/components/PropertyForm.tsx:160-184
Sequence of address autocompletion and geocoding via the internal API proxy.
Sources: src/components/PropertyForm.tsx:158-204, PRIVACY.md:38
Structured Data
The system utilizes a GeocodeSuggestion interface to handle geographical data:
lat(number): Latitude.lng(number): Longitude.display_name(string): Full formatted address.street,suburb,state,postcode,country(string): Individual address components.
Sources: src/components/PropertyForm.tsx:21-30
Privacy and External Dependencies
Mapping and geocoding rely on external providers, which has specific privacy implications in a self-hosted context.
- OpenStreetMap Nominatim: Used for address lookups. Address text typed by the user is sent to this service only if configured.
- OpenStreetMap Tile Servers: Used for rendering map visuals.
- On-Device Processing: Coordinates are stored in the local SQLite database. In standalone mobile mode, data remains strictly device-local.
Sources: PRIVACY.md:14-16, PRIVACY.md:38
Summary
The Maps & Geocoding system in Hearth provides essential spatial context for property management. By combining Leaflet-based client-side map rendering with server-configured tile providers and a debounced geocoding API, the application ensures that address entry is accurate while allowing users to visualize their household assets. The architecture balances ease of use (auto-fill) with the privacy requirements of a self-hosted application by using OpenStreetMap as the default provider and strictly controlling referrer headers.
Sources: src/components/PropertyMap.tsx, src/lib/mapTiles.ts, src/components/PropertyForm.tsx