# adhamhesham07/estately_ai_system architecture

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

- Interactive diagram: https://gitdiagram.com/adhamhesham07/estately_ai_system
- Repository: https://github.com/adhamhesham07/estately_ai_system

## Overview

Estately is a real-estate assistant combining property recommendations, market analysis, and conversational help. Users can search or ask questions through the API or chatbot interfaces; the system also exposes fair-price and market-pulse analysis. The recommender and analyzer share cleaned property data backed by SQLite. The graph preserves the documented agent, booking, and knowledge capabilities, but source excerpts do not show the agent graph’s internal routing or all interface wiring, so those links are omitted rather than inferred.

Main entry points: [`5.APIs/main.py`](https://github.com/adhamhesham07/estately_ai_system/blob/main/5.APIs/main.py) (FastAPI), [`1.Agent/2_data_bridge.py`](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_data_bridge.py) (Agent Data Bridge), [`4.Data/preprocessing_engine.py`](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/preprocessing_engine.py) (Shared Preprocessing), [`4.Data/2_DataBase/db_adapter.py`](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/db_adapter.py) (Property Data Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_api["FastAPI<br/>[main.py]"]
  node_api_schemas["API Schemas<br/>[schemas.py]"]
  node_web_gui["Web Chat UI<br/>[chatbot.js]"]
  node_gradio_ui["Gradio UI<br/>[agent_gui.py]"]
end

subgraph group_agent["Conversational Agent"]
  node_agent_state["Conversation State"]
  node_agent_graph["Agent Graph<br/>[4_graph_builder.py]"]
  node_intent["Intent Extraction<br/>[1_intent_node.py]"]
  node_tool_node["Tool Execution<br/>[2_tool_node.py]"]
  node_translator["Response Translation<br/>[3_translator.py]"]
  node_auditor["Response Audit<br/>[4_auditor.py]"]
  node_entity_extractor["Entity Extraction"]
  node_booking["Viewing Booking<br/>[booking_logic.py]"]
  node_data_bridge["Agent Data Bridge<br/>[2_data_bridge.py]"]
end

subgraph group_recommendations["Property Recommendations"]
  node_query_adapter["Search Adapter<br/>[5_query_adapter.py]"]
  node_recommender["Recommendation Pipeline"]
  node_ranking["Ranking Features"]
  node_teacher["Ranker Training<br/>[3_teacher.py]"]
end

subgraph group_analysis_data["Analysis and Data"]
  node_market["Market Statistics<br/>[3_market_engine.py]"]
  node_preferences["Preference Analysis"]
  node_insights["Insight Synthesis"]
  node_evaluator["Fair Price Evaluation"]
  node_knowledge["Market Knowledge"]
  node_analyzer_llm["Analysis Language Model<br/>[8_analyzer_llm.py]"]
  node_ingestion["Analyzer Ingestion"]
  node_preprocessing["Shared Preprocessing"]
  node_db_adapter["Property Data Adapter<br/>[db_adapter.py]"]
  node_db_connector["SQLite Connector<br/>[db_connector.py]"]
  node_sqlite[("Property Database<br/>[RealEstate.db]")]
  node_knowledge_loader["Knowledge Loader"]
end

node_user(("User"))

node_user -->|"submits requests"| node_api
node_api -->|"validates with"| node_api_schemas
node_api -->|"searches through"| node_query_adapter
node_api -->|"evaluates prices with"| node_evaluator
node_api -->|"fetches market pulse"| node_market
node_data_bridge -->|"executes recommendations"| node_recommender
node_data_bridge -->|"requests fair-price estimate"| node_market
node_data_bridge -->|"formats price context"| node_insights
node_ingestion -->|"loads cleaned catalog"| node_preprocessing
node_preprocessing -->|"fetches properties"| node_db_adapter
node_db_adapter -->|"gets database engine"| node_db_connector
node_db_connector -->|"connects to"| node_sqlite

click node_api "https://github.com/adhamhesham07/estately_ai_system/blob/main/5.APIs/main.py"
click node_api_schemas "https://github.com/adhamhesham07/estately_ai_system/blob/main/5.APIs/schemas.py"
click node_web_gui "https://github.com/adhamhesham07/estately_ai_system/blob/main/6.GUI/chatbot.js"
click node_gradio_ui "https://github.com/adhamhesham07/estately_ai_system/blob/main/agent_gui.py"
click node_agent_state "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/3_state_definition.py"
click node_agent_graph "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/4_graph_builder.py"
click node_intent "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/1_intent_node.py"
click node_tool_node "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/2_tool_node.py"
click node_translator "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/3_translator.py"
click node_auditor "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/4_auditor.py"
click node_entity_extractor "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/entity_extractor.py"
click node_booking "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/3_sceduler/booking_logic.py"
click node_data_bridge "https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_data_bridge.py"
click node_query_adapter "https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/5_query_adapter.py"
click node_recommender "https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/4_main_orchestration.py"
click node_ranking "https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/2_math_and_features.py"
click node_teacher "https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/3_teacher.py"
click node_market "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/3_market_engine.py"
click node_preferences "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/4_preference_engine.py"
click node_insights "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/5_insight_builder.py"
click node_evaluator "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/6_analyzer_evaluator.py"
click node_knowledge "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/7_knowledge_engine.py"
click node_analyzer_llm "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/8_analyzer_llm.py"
click node_ingestion "https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/2_ingestion_adapter.py"
click node_preprocessing "https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/preprocessing_engine.py"
click node_db_adapter "https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/db_adapter.py"
click node_db_connector "https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/db_connector.py"
click node_sqlite "https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/RealEstate.db"
click node_knowledge_loader "https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/3_market_knowledge/knowledge_loader.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_api,node_api_schemas,node_web_gui,node_gradio_ui,node_user toneBlue
class node_agent_state,node_agent_graph,node_intent,node_tool_node,node_translator,node_auditor,node_entity_extractor,node_booking,node_data_bridge toneAmber
class node_query_adapter,node_recommender,node_ranking,node_teacher toneMint
class node_market,node_preferences,node_insights,node_evaluator,node_knowledge,node_analyzer_llm,node_ingestion,node_preprocessing,node_db_adapter,node_db_connector,node_sqlite,node_knowledge_loader toneRose
```

## Components

### User Interfaces

- [FastAPI](https://github.com/adhamhesham07/estately_ai_system/blob/main/5.APIs/main.py): `5.APIs/main.py`
- [API Schemas](https://github.com/adhamhesham07/estately_ai_system/blob/main/5.APIs/schemas.py): `5.APIs/schemas.py`
- [Web Chat UI](https://github.com/adhamhesham07/estately_ai_system/blob/main/6.GUI/chatbot.js): `6.GUI/chatbot.js`
- [Gradio UI](https://github.com/adhamhesham07/estately_ai_system/blob/main/agent_gui.py): `agent_gui.py`

### Conversational Agent

- [Conversation State](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/3_state_definition.py): `1.Agent/3_state_definition.py`
- [Agent Graph](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/4_graph_builder.py): `1.Agent/4_graph_builder.py`
- [Intent Extraction](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/1_intent_node.py): `1.Agent/2_nodes/1_intent_node.py`
- [Tool Execution](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/2_tool_node.py): `1.Agent/2_nodes/2_tool_node.py`
- [Response Translation](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/3_translator.py): `1.Agent/2_nodes/3_translator.py`
- [Response Audit](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/4_auditor.py): `1.Agent/2_nodes/4_auditor.py`
- [Entity Extraction](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_nodes/entity_extractor.py): `1.Agent/2_nodes/entity_extractor.py`
- [Viewing Booking](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/3_sceduler/booking_logic.py): `1.Agent/3_sceduler/booking_logic.py`
- [Agent Data Bridge](https://github.com/adhamhesham07/estately_ai_system/blob/main/1.Agent/2_data_bridge.py): `1.Agent/2_data_bridge.py`

### Property Recommendations

- [Search Adapter](https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/5_query_adapter.py): `2.Recommender/5_query_adapter.py`
- [Recommendation Pipeline](https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/4_main_orchestration.py): `2.Recommender/4_main_orchestration.py`
- [Ranking Features](https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/2_math_and_features.py): `2.Recommender/2_math_and_features.py`
- [Ranker Training](https://github.com/adhamhesham07/estately_ai_system/blob/main/2.Recommender/3_teacher.py): `2.Recommender/3_teacher.py`

### Analysis and Data

- [Market Statistics](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/3_market_engine.py): `3.Analyzer/3_market_engine.py`
- [Preference Analysis](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/4_preference_engine.py): `3.Analyzer/4_preference_engine.py`
- [Insight Synthesis](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/5_insight_builder.py): `3.Analyzer/5_insight_builder.py`
- [Fair Price Evaluation](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/6_analyzer_evaluator.py): `3.Analyzer/6_analyzer_evaluator.py`
- [Market Knowledge](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/7_knowledge_engine.py): `3.Analyzer/7_knowledge_engine.py`
- [Analysis Language Model](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/8_analyzer_llm.py): `3.Analyzer/8_analyzer_llm.py`
- [Analyzer Ingestion](https://github.com/adhamhesham07/estately_ai_system/blob/main/3.Analyzer/2_ingestion_adapter.py): `3.Analyzer/2_ingestion_adapter.py`
- [Shared Preprocessing](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/preprocessing_engine.py): `4.Data/preprocessing_engine.py`
- [Property Data Adapter](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/db_adapter.py): `4.Data/2_DataBase/db_adapter.py`
- [SQLite Connector](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/db_connector.py): `4.Data/2_DataBase/db_connector.py`
- [Property Database](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/2_DataBase/RealEstate.db): `4.Data/2_DataBase/RealEstate.db`
- [Knowledge Loader](https://github.com/adhamhesham07/estately_ai_system/blob/main/4.Data/3_market_knowledge/knowledge_loader.py): `4.Data/3_market_knowledge/knowledge_loader.py`

### Other components

- **User**

## Connections

- User → FastAPI: submits requests (evidence: `5.APIs/main.py`)
- FastAPI → API Schemas: validates with (evidence: `5.APIs/main.py`)
- FastAPI → Search Adapter: searches through (evidence: `5.APIs/main.py`)
- FastAPI → Fair Price Evaluation: evaluates prices with (evidence: `5.APIs/main.py`)
- FastAPI → Market Statistics: fetches market pulse (evidence: `5.APIs/main.py`)
- Agent Data Bridge → Recommendation Pipeline: executes recommendations (evidence: `1.Agent/2_data_bridge.py`)
- Agent Data Bridge → Market Statistics: requests fair-price estimate (evidence: `1.Agent/2_data_bridge.py`)
- Agent Data Bridge → Insight Synthesis: formats price context (evidence: `1.Agent/2_data_bridge.py`)
- Analyzer Ingestion → Shared Preprocessing: loads cleaned catalog (evidence: `3.Analyzer/2_ingestion_adapter.py`)
- Shared Preprocessing → Property Data Adapter: fetches properties (evidence: `4.Data/preprocessing_engine.py`)
- Property Data Adapter → SQLite Connector: gets database engine (evidence: `4.Data/2_DataBase/db_adapter.py`)
- SQLite Connector → Property Database: connects to (evidence: `4.Data/2_DataBase/db_connector.py`)