# aleksnestu/ai-real-estate-assistant architecture

> Architecture diagram of the GitHub repository aleksnestu/ai-real-estate-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aleksnestu/ai-real-estate-assistant
- Repository: https://github.com/aleksnestu/ai-real-estate-assistant

## Overview

##### Project Type & Purpose
- This is a full-stack, conversational AI web application (“AI Real Estate Assistant”) built in Python.
- Purpose: Leverage Retrieval-Augmented Generation (RAG) with LLMs and structured CSV real-estate data to answer user questions and recommend properties via a Streamlit UI.

##### File Structure Analysis
- Top-level apps:
- app.py (V1: pandas DataFrame agent)
- app_v2.py (V2: RAG with ConversationalRetrievalChain)
- streaming.py (streaming utilities for UI responses)
- Modules:
- ai/agent.py: core agent abstraction and LLM orchestration
- data/csv_loader.py: CSV loading & normalization
- common/cfg.py: configuration management (API keys, env variables)
- dataset/pl/*.csv: sample property datasets
- utils.py & utils/*.sh: helper scripts, Docker/dev-container setup
- Config & deployment:
- .devcontainer/ & utils/run_* scripts for containerized dev
- Docker scripts under utils/
- CI configuration under .github/

##### Key Architecture from README
- Retrieval-Augmented Generation (RAG) pattern combining:
– Vector embeddings (FastEmbed)
– In-memory vector store (DocArrayInMemorySearch / ChromaDB)
– LangChain’s ConversationalRetrievalChain for multi-turn dialog
- Data pipeline: load CSV → normalize (Pandas) → embed → index → similarity search → LLM integration
- UI: Streamlit for rapid interactive web interface

##### Main Components
1. User & Streamlit UI Layer
– Browser → Streamlit app (app.py/app_v2.py)
2. Application Logic
– Conversational controller (streaming.py / langchain chains)
– Agent module (ai/agent.py)
3. Data Processing
– CSV Loader (data/csv_loader.py)
– Pandas normalization
4. Embedding Engine
– FastEmbed (in-process library)
5. Vector Store
– DocArrayInMemorySearch or ChromaDB (in-memory vector DB)
6. LLM Providers
– External: OpenAI GPT API (cloud)
– Local: Llama models (optional)
7. Configuration & Utilities
– common/cfg.py (env variables, API keys)
– utils scripts & dev-container for deployment

##### Relationships & Data Flow
- User submits query → Streamlit UI → Agent
- Agent calls LLM (OpenAI/Llama) for intent extraction → returns structured preferences
- Agent loads/ensures data is indexed:
– CSV Loader → Pandas DF → embeddings via FastEmbed → stored in vector store
- Agent queries vector store for similarity search → retrieves top-k property records
- Agent invokes LLM again (RAG) to generate conversational response with retrieved data
- Response returned to Streamlit UI → displayed to user

##### Architectural Patterns & Principles
- Modular Monolith: clear separation across modules (UI, AI, Data, Config)
- RAG Pattern: retrieval (vector DB) + generation (LLM)
- SRP & Open/Closed: data loader, agent, and config follow single-responsibility and are extensible
- DevOps: containerized dev (.devcontainer), Docker deployment, CI via GitHub

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        style UI fill:#CCE5FF,stroke:#1E90FF
        User["User (Browser)"]:::frontend
        UI_V1["Streamlit UI V1<br/>(app.py)"]:::frontend
        UI_V2["Streamlit UI V2<br/>(app_v2.py)"]:::frontend
    end

    %% Business Logic
    subgraph "Business Logic"
        style BL fill:#D4F8C4,stroke:#27AE60
        Stream["Streaming Controller<br/>(streaming.py)"]:::business
        Agent["Agent Module<br/>(ai/agent.py)"]:::business
    end

    %% Data & Embedding
    subgraph "Data & Embedding Layer"
        style DE fill:#FFE5B4,stroke:#E67E22
        CSVLoader["CSV Loader<br/>(data/csv_loader.py)"]:::data
        Pandas["Data Normalization<br/>(Pandas)"]:::data
        Embed["FastEmbed Embedding Engine"]:::data
    end

    %% Storage
    subgraph "Vector Storage"
        style Storage fill:#FFF5BA,stroke:#F1C40F
        VectorStore["DocArrayInMemorySearch<br/>or ChromaDB"]:::storage
    end

    %% External Services
    subgraph "External LLM Providers"
        style Ext fill:#E8DAEF,stroke:#8E44AD
        OpenAI["OpenAI GPT API<br/>(cloud)"]:::external
        Llama["Local Llama Models"]:::external
    end

    %% Config & DevOps
    subgraph "Config & DevOps"
        style Config fill:#ECECEC,stroke:#7F8C8D
        ConfigFile["Config Management<br/>(common/cfg.py)"]:::config
        DevContainer["DevContainer Config<br/>(.devcontainer/devcontainer.json)"]:::config
        Utils["Utility & Deployment Scripts"]:::config
        CI["GitHub CI (.github/)"]:::config
    end

    %% Dataset
    subgraph "Datasets"
        style DS fill:#F0F0F0,stroke:#BDC3C7
        CSV1["apartments_rent_pl_2024_01.csv"]:::dataset
        CSV2["apartments_rent_pl_2024_02.csv"]:::dataset
        CSV3["apartments_rent_pl_2024_03.csv"]:::dataset
        CSV4["apartments_rent_pl_2024_04.csv"]:::dataset
        CSV5["apartments_rent_pl_2024_05.csv"]:::dataset
        CSV6["apartments_rent_pl_2024_06.csv"]:::dataset
    end

    %% Workflow Arrows
    User -->|"1. Query"| UI_V1
    User -->|"1. Query"| UI_V2
    UI_V2 -->|"2. Stream"| Stream
    UI_V1 -->|"2. Agent"| Agent
    Stream -->|"3. Invoke"| Agent
    Agent -->|"4. Load Data"| CSVLoader
    CSVLoader -->|"5. CSV → DataFrame"| Pandas
    Pandas -->|"6. embed()"| Embed
    Embed -->|"7. vector_store.add()"| VectorStore
    Agent -->|"8. similarity search"| VectorStore
    VectorStore -->|"9. top-k records"| Agent
    Agent -->|"10. RAG → conversational_chain()"| OpenAI
    Agent -->|"10. RAG → conversational_chain()"| Llama
    OpenAI -->|"11. Response"| Agent
    Llama -->|"11. Response"| Agent
    Agent -->|"12. Display"| UI_V2
    Agent -->|"12. Display"| UI_V1

    %% Config & DevOps connections
    Agent -->|"uses"| ConfigFile
    UI_V1 -->|"configured by"| ConfigFile
    UI_V2 -->|"configured by"| ConfigFile
    DevContainer -->|"setup dev env"| UI_V1
    DevContainer -->|"setup dev env"| UI_V2
    Utils -->|"scripts"| DevContainer
    CI -->|"validates"| Utils

    %% Click Events
    click UI_V1 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/app.py"
    click UI_V2 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/app_v2.py"
    click Stream "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/streaming.py"
    click Agent "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/ai/agent.py"
    click CSVLoader "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/data/csv_loader.py"
    click ConfigFile "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/common/cfg.py"
    click CSV1 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/dataset/pl/apartments_rent_pl_2024_01.csv"
    click CSV2 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/dataset/pl/apartments_rent_pl_2024_02.csv"
    click CSV3 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/dataset/pl/apartments_rent_pl_2024_03.csv"
    click CSV4 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/dataset/pl/apartments_rent_pl_2024_04.csv"
    click CSV5 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/dataset/pl/apartments_rent_pl_2024_05.csv"
    click CSV6 "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/dataset/pl/apartments_rent_pl_2024_06.csv"
    click DevContainer "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/.devcontainer/devcontainer.json"
    click Utils "https://github.com/aleksnestu/ai-real-estate-assistant/blob/main/utils.py"
    click CI "https://github.com/aleksnestu/ai-real-estate-assistant/tree/main/.github/CODEOWNERS"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#1E90FF;
    classDef business fill:#D4F8C4,stroke:#27AE60;
    classDef data fill:#FFE5B4,stroke:#E67E22;
    classDef storage fill:#FFF5BA,stroke:#F1C40F;
    classDef external fill:#E8DAEF,stroke:#8E44AD;
    classDef config fill:#ECECEC,stroke:#7F8C8D;
    classDef dataset fill:#F9E79F,stroke:#F39C12;
```
