How abdullahmahfouz/homeagent works
HomeAgent turns a plain-language home or mortgage question into a conversational response, live tool updates, and listing results users can explore on a map and cards. The main path runs from the chat UI through the streaming API and agent to Gemini and, when requested, MLS or mortgage tools; results return to the UI for parsing and presentation. The README documents mapping, listing exploration, mortgage estimates, and session history. Backend session handling and request/budget guards are shown; unsampled implementation details are omitted.
Main entry points: App.jsx Chat application · server.py FastAPI endpoints · agent.py Agent loop · api.js Streaming client
Components 21
Chat and exploration
- Chat application
frontend/real-estate-agent/src/App.jsx - Streaming client
frontend/real-estate-agent/src/api.js - Response parser
frontend/real-estate-agent/src/lib/parse.js - Assistant display
frontend/real-estate-agent/src/components/AssistantTurn.jsx - Listing map
frontend/real-estate-agent/src/components/ListingMap.jsx - Listing cards
frontend/real-estate-agent/src/components/ListingCards.jsx - Mortgage estimate UI
frontend/real-estate-agent/src/components/MortgageModal.jsx - Local mortgage calculator
frontend/real-estate-agent/src/lib/mortgage.js
Agent and API
- FastAPI endpoints
backend/server.py - Request and budget guards
backend/guards.py - Agent loop
backend/agent.py - Tool dispatch
backend/agent.py - MLS listing search
backend/agent.py - Mortgage tool
backend/agent.py
External services
- Gemini
- Repliers MLS
- Mapbox
Session state
- Session management
frontend/real-estate-agent/src/lib/storage.js - Browser localStorage
- In-memory chat sessions
backend/server.py
Other components
- Home seeker
Connections 23
- Home seeker → Chat application: asks
- Chat application → Streaming client: sends chat
- Chat application → Session management: loads and saves
- Session management → Browser localStorage: reads and writes
- Chat application → Response parser: parses results
- Chat application → Assistant display: renders replies
- Chat application → Listing map: shows listings
- Listing map → Mapbox: renders map
- Chat application → Listing cards: shows listings
- Chat application → Mortgage estimate UI: opens estimate
- Mortgage estimate UI → Local mortgage calculator: calculates payment
- Streaming client → FastAPI endpoints: POSTs chat
- FastAPI endpoints → Request and budget guards: checks limits
- FastAPI endpoints → In-memory chat sessions: reads and writes
- FastAPI endpoints → Agent loop: runs turn
- Agent loop → Gemini: requests generation
- Agent loop → Tool dispatch: dispatches calls
- Tool dispatch → MLS listing search: invokes search
- Tool dispatch → Mortgage tool: invokes calculation
- MLS listing search → Repliers MLS: fetches listings
- Agent loop → FastAPI endpoints: yields events
- FastAPI endpoints → Streaming client: streams NDJSON
- Streaming client → Chat application: delivers events