# abdullahmahfouz/homeagent architecture

> Architecture diagram of the GitHub repository abdullahmahfouz/homeagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullahmahfouz/homeagent
- Repository: https://github.com/abdullahmahfouz/homeagent

## Overview

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: [`frontend/real-estate-agent/src/App.jsx`](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/App.jsx) (Chat application), [`backend/server.py`](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/server.py) (FastAPI endpoints), [`backend/agent.py`](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py) (Agent loop), [`frontend/real-estate-agent/src/api.js`](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/api.js) (Streaming client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Chat and exploration"]
  node_app["Chat application<br/>[App.jsx]"]
  node_api["Streaming client<br/>[api.js]"]
  node_response_parser["Response parser<br/>[parse.js]"]
  node_assistant_turn["Assistant display<br/>[AssistantTurn.jsx]"]
  node_listing_map["Listing map<br/>[ListingMap.jsx]"]
  node_listing_cards["Listing cards<br/>[ListingCards.jsx]"]
  node_mortgage_modal["Mortgage estimate UI<br/>[MortgageModal.jsx]"]
  node_mortgage_calc["Local mortgage calculator<br/>[mortgage.js]"]
end

subgraph group_backend["Agent and API"]
  node_server["FastAPI endpoints<br/>[server.py]"]
  node_guards["Request and budget guards<br/>[guards.py]"]
  node_agent_loop["Agent loop<br/>[agent.py]"]
  node_tool_dispatch["Tool dispatch<br/>[agent.py]"]
  node_listing_search["MLS listing search<br/>[agent.py]"]
  node_backend_mortgage["Mortgage tool<br/>[agent.py]"]
end

subgraph group_integrations["External services"]
  node_gemini{{"Gemini"}}
  node_repliers{{"Repliers MLS"}}
  node_mapbox{{"Mapbox"}}
end

subgraph group_state["Session state"]
  node_session_helpers["Session management<br/>[storage.js]"]
  node_browser_storage[("Browser localStorage")]
  node_backend_sessions[("In-memory chat sessions<br/>[server.py]")]
end

node_user(("Home seeker"))

node_user -->|"asks"| node_app
node_app -->|"sends chat"| node_api
node_app -->|"loads and saves"| node_session_helpers
node_session_helpers -->|"reads and writes"| node_browser_storage
node_app -->|"parses results"| node_response_parser
node_app -->|"renders replies"| node_assistant_turn
node_app -->|"shows listings"| node_listing_map
node_listing_map -->|"renders map"| node_mapbox
node_app -->|"shows listings"| node_listing_cards
node_app -->|"opens estimate"| node_mortgage_modal
node_mortgage_modal -->|"calculates payment"| node_mortgage_calc
node_api -->|"POSTs chat"| node_server
node_server -->|"checks limits"| node_guards
node_server -->|"reads and writes"| node_backend_sessions
node_server -->|"runs turn"| node_agent_loop
node_agent_loop -->|"requests generation"| node_gemini
node_agent_loop -->|"dispatches calls"| node_tool_dispatch
node_tool_dispatch -->|"invokes search"| node_listing_search
node_tool_dispatch -->|"invokes calculation"| node_backend_mortgage
node_listing_search -->|"fetches listings"| node_repliers
node_agent_loop -->|"yields events"| node_server
node_server -->|"streams NDJSON"| node_api
node_api -->|"delivers events"| node_app

click node_app "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/App.jsx"
click node_api "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/api.js"
click node_response_parser "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/lib/parse.js"
click node_assistant_turn "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/AssistantTurn.jsx"
click node_listing_map "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/ListingMap.jsx"
click node_listing_cards "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/ListingCards.jsx"
click node_mortgage_modal "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/MortgageModal.jsx"
click node_mortgage_calc "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/lib/mortgage.js"
click node_server "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/server.py"
click node_guards "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/guards.py"
click node_agent_loop "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py"
click node_tool_dispatch "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py"
click node_listing_search "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py"
click node_backend_mortgage "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py"
click node_session_helpers "https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/lib/storage.js"
click node_backend_sessions "https://github.com/abdullahmahfouz/homeagent/blob/master/backend/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_api,node_response_parser,node_assistant_turn,node_listing_map,node_listing_cards,node_mortgage_modal,node_mortgage_calc toneBlue
class node_server,node_guards,node_agent_loop,node_tool_dispatch,node_listing_search,node_backend_mortgage toneAmber
class node_gemini,node_repliers,node_mapbox toneMint
class node_session_helpers,node_browser_storage,node_backend_sessions toneRose
class node_user toneIndigo
```

## Components

### Chat and exploration

- [Chat application](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/App.jsx): `frontend/real-estate-agent/src/App.jsx`
- [Streaming client](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/api.js): `frontend/real-estate-agent/src/api.js`
- [Response parser](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/lib/parse.js): `frontend/real-estate-agent/src/lib/parse.js`
- [Assistant display](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/AssistantTurn.jsx): `frontend/real-estate-agent/src/components/AssistantTurn.jsx`
- [Listing map](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/ListingMap.jsx): `frontend/real-estate-agent/src/components/ListingMap.jsx`
- [Listing cards](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/ListingCards.jsx): `frontend/real-estate-agent/src/components/ListingCards.jsx`
- [Mortgage estimate UI](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/components/MortgageModal.jsx): `frontend/real-estate-agent/src/components/MortgageModal.jsx`
- [Local mortgage calculator](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/lib/mortgage.js): `frontend/real-estate-agent/src/lib/mortgage.js`

### Agent and API

- [FastAPI endpoints](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/server.py): `backend/server.py`
- [Request and budget guards](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/guards.py): `backend/guards.py`
- [Agent loop](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py): `backend/agent.py`
- [Tool dispatch](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py): `backend/agent.py`
- [MLS listing search](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py): `backend/agent.py`
- [Mortgage tool](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/agent.py): `backend/agent.py`

### External services

- **Gemini**
- **Repliers MLS**
- **Mapbox**

### Session state

- [Session management](https://github.com/abdullahmahfouz/homeagent/blob/master/frontend/real-estate-agent/src/lib/storage.js): `frontend/real-estate-agent/src/lib/storage.js`
- **Browser localStorage**
- [In-memory chat sessions](https://github.com/abdullahmahfouz/homeagent/blob/master/backend/server.py): `backend/server.py`

### Other components

- **Home seeker**

## Connections

- 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