Skip to content

iOS App — Foundational Locator

What it is

Foundational Locator is a native iOS "locator workspace" app for apartment/property locators. It lets a locator browse buildings, filter the universe down to what's relevant, run AI-assisted natural-language search, track fit against a client's criteria, and manage a save/shortlist pipeline through to close.

Tech stack

Layer Technology
Language Swift 6
UI SwiftUI
Local persistence SwiftData
Maps MapKit
Networking URLSession
Credential storage Security / Keychain
Target OS iOS 26

Note

The app deliberately has no third-party dependencies — it is built entirely on Apple frameworks.

Architecture

  • Data is fetched from a hosted "Resource API" and cached locally in SwiftData for offline and responsive browsing. SwiftData is explicitly a device cache and workflow store, not an independent source of truth — the warehouse behind the Resource API remains authoritative. See ../data-model/warehouse-schema.md for the underlying schema.
  • A dedicated memory+disk cache holds building photo bytes so images persist across app launches without re-downloading.
  • The app talks to a /resource gateway with two calls:
    • resource=buildings — paginated discovery.
    • resource=building — full detail for a single building.

These expose the same underlying warehouse fields the (retired) Chrome extension used to show — see Chrome Extension — Relive Overlay for that history. - Property coordinates are resolved via the on-device MapKit geocoder and persisted in SwiftData so the map view works offline on subsequent launches. - Sync is merge-based: an interrupted sync never wipes existing locator notes, client assignments, or save-pipeline state. - Auth is a Resource API key entered in Settings, used when the deployment requires one.

For how the Resource API's backend fits into the rest of the platform, see Architecture Overview.

Core flows

  • Explore properties in a list or an Apple Maps view; filter by market, commission, confidence, contactability, amenities, and monthly rent.
  • Natural-language search via Apple Intelligence — a free-text query is turned into structured filters automatically.
  • Inspect commission basis, confidence, sources, rent, and management/leasing contacts for a building.
  • Browse photos, amenities, specials, floorplans, and unit-availability rows.
  • Call, email, open the property's site, share, take notes, or assign a property to a client.
  • Shortlist a property via a full right-swipe or a card bookmark. Shortlisted cards mute visually and live in a dedicated Shortlist tab, backed by a five-stage SwiftData save pipeline.
  • Store per-client criteria and rank properties by explainable fit (market, budget, bedrooms, neighborhood, amenities, locator terms, contact readiness).

Visual conventions

Market illustrations (Chicago/Atlanta/Denver) are original decorative artwork used only for market identity — they are not real photos.

Every property card, map pin, and detail view uses only real photos sourced from the Resource API. A missing or failed photo shows a neutral placeholder rather than a stock image.

Build & test

xcodebuild -project ios/FoundationalLocator.xcodeproj \
  -scheme FoundationalLocator \
  -sdk iphonesimulator \
  -configuration Debug \
  CODE_SIGNING_ALLOWED=NO build

xcodebuild test -project ios/FoundationalLocator.xcodeproj \
  -scheme FoundationalLocator \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro'

For interactive development, open FoundationalLocator.xcodeproj directly in Xcode 26.

Note

See Deployment for how the Resource API backend this app depends on is deployed and operated, and History & Migrations for background on prior clients that consumed the same underlying data.