# munawarjamil/realestate_ai architecture

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

- Interactive diagram: https://gitdiagram.com/munawarjamil/realestate_ai
- Repository: https://github.com/munawarjamil/realestate_ai

## Overview

PropChat is a multi-tenant real-estate AI platform. Visitors use an embeddable widget to chat with an assistant grounded in agency documents; the platform also supports property search, mortgage estimates, viewing bookings, lead qualification, and broker takeover. Agency staff manage conversations and CRM data in a dashboard, while platform administrators manage tenants and system operations. The README documents the broad product flow; sampled source confirms selected routes and module references, but unsampled implementations are not assumed to call one another.

Main entry points: [`src/app/modules/chat/service.py`](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/service.py) (Conversation Service), [`src/app/modules/chat/graph_runtime.py`](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/graph_runtime.py) (LangGraph Agent), [`dashboard/src/api/client.ts`](https://github.com/munawarjamil/realestate_ai/blob/main/dashboard/src/api/client.ts) (Dashboard API Client), [`src/app/modules/chat/socketio_server.py`](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/socketio_server.py) (Broker Handoff)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experiences"]
  node_widget["Website Widget<br/>[main.ts]"]
  node_dashboard["Admin Dashboard<br/>[router.tsx]"]
  node_dashboard_api["Dashboard API Client<br/>[client.ts]"]
end

subgraph group_platform["API and Identity"]
  node_auth["Authentication<br/>[router.py]"]
  node_tenant_admin["Tenant Management"]
  node_widget_api["Widget Sessions<br/>[router.py]"]
  node_chat_api["Chat API<br/>[router.py]"]
end

subgraph group_conversation["Conversation AI"]
  node_chat_service["Conversation Service<br/>[service.py]"]
  node_agent["LangGraph Agent<br/>[graph_runtime.py]"]
  node_handoff["Broker Handoff<br/>[socketio_server.py]"]
  node_knowledge["Document RAG<br/>[retrieval.py]"]
  node_knowledge_ingestion["Document Ingestion"]
end

subgraph group_agency_ops["Agency Operations"]
  node_properties["Property Search<br/>[service.py]"]
  node_calculator["Mortgage Calculator<br/>[engine.py]"]
  node_bookings["Viewing Bookings<br/>[service.py]"]
  node_leads["CRM Leads<br/>[service.py]"]
end

subgraph group_infrastructure["State and Integrations"]
  node_db[("PostgreSQL<br/>[session.py]")]
  node_qdrant[("Qdrant Vectors<br/>[client.py]")]
  node_llm["LLM Provider<br/>[client.py]"]
  node_redis["Redis Pub/Sub<br/>[redis_pubsub.py]"]
end

node_visitors(("Visitors"))
node_brokers(("Agency Brokers"))
node_platform_admins(("Platform Admins"))

node_visitors -->|"chat through"| node_widget
node_widget -->|"opens session"| node_widget_api
node_widget_api -->|"uses chat service"| node_chat_service
node_chat_service -->|"retrieves context"| node_knowledge
node_chat_service -.->|"runs agent"| node_agent
node_agent -.->|"calls model"| node_llm
node_agent -->|"searches listings"| node_properties
node_agent -->|"calculates mortgage"| node_calculator
node_agent -->|"books viewings"| node_bookings
node_knowledge_ingestion -.->|"indexes vectors"| node_qdrant
node_brokers -->|"manage conversations"| node_dashboard
node_dashboard -->|"requests data"| node_dashboard_api
node_dashboard_api -->|"streams chat"| node_chat_api
node_dashboard_api -->|"authenticates"| node_auth
node_dashboard_api -->|"manages tenants"| node_tenant_admin
node_dashboard_api -.->|"manages leads"| node_leads
node_chat_api -.->|"delegates requests"| node_chat_service
node_chat_service -.->|"qualifies visitors"| node_leads
node_brokers -->|"takes over chats"| node_handoff
node_handoff -->|"publishes events"| node_redis
node_handoff -->|"dispatches chat"| node_agent
node_platform_admins -->|"administers platform"| node_dashboard
node_chat_service -.->|"stores conversations"| node_db
node_knowledge_ingestion -.->|"feeds retrieval"| node_knowledge
node_bookings -.->|"persists bookings"| node_db
node_leads -.->|"persists leads"| node_db

click node_widget "https://github.com/munawarjamil/realestate_ai/blob/main/widget/src/main.ts"
click node_dashboard "https://github.com/munawarjamil/realestate_ai/blob/main/dashboard/src/router.tsx"
click node_dashboard_api "https://github.com/munawarjamil/realestate_ai/blob/main/dashboard/src/api/client.ts"
click node_auth "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/auth/router.py"
click node_tenant_admin "https://github.com/munawarjamil/realestate_ai/tree/main/src/app/modules/tenants"
click node_widget_api "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/widget/router.py"
click node_chat_api "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/router.py"
click node_chat_service "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/service.py"
click node_agent "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/graph_runtime.py"
click node_handoff "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/socketio_server.py"
click node_knowledge "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/knowledge/retrieval.py"
click node_knowledge_ingestion "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/knowledge/ingestion_runner.py"
click node_properties "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/properties/service.py"
click node_calculator "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/calculator/engine.py"
click node_bookings "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/bookings/service.py"
click node_leads "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/leads/service.py"
click node_db "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/db/session.py"
click node_qdrant "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/integrations/qdrant/client.py"
click node_llm "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/integrations/llm/client.py"
click node_redis "https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/redis_pubsub.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_widget,node_dashboard,node_dashboard_api toneBlue
class node_auth,node_tenant_admin,node_widget_api,node_chat_api toneAmber
class node_chat_service,node_agent,node_handoff,node_knowledge,node_knowledge_ingestion toneMint
class node_properties,node_calculator,node_bookings,node_leads toneRose
class node_db,node_qdrant,node_llm,node_redis,node_visitors,node_brokers,node_platform_admins toneIndigo
```

## Components

### User Experiences

- [Website Widget](https://github.com/munawarjamil/realestate_ai/blob/main/widget/src/main.ts): `widget/src/main.ts`
- [Admin Dashboard](https://github.com/munawarjamil/realestate_ai/blob/main/dashboard/src/router.tsx): `dashboard/src/router.tsx`
- [Dashboard API Client](https://github.com/munawarjamil/realestate_ai/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`

### API and Identity

- [Authentication](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/auth/router.py): `src/app/modules/auth/router.py`
- [Tenant Management](https://github.com/munawarjamil/realestate_ai/tree/main/src/app/modules/tenants): `src/app/modules/tenants`
- [Widget Sessions](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/widget/router.py): `src/app/modules/widget/router.py`
- [Chat API](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/router.py): `src/app/modules/chat/router.py`

### Conversation AI

- [Conversation Service](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/service.py): `src/app/modules/chat/service.py`
- [LangGraph Agent](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/graph_runtime.py): `src/app/modules/chat/graph_runtime.py`
- [Broker Handoff](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/socketio_server.py): `src/app/modules/chat/socketio_server.py`
- [Document RAG](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/knowledge/retrieval.py): `src/app/modules/knowledge/retrieval.py`
- [Document Ingestion](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/knowledge/ingestion_runner.py): `src/app/modules/knowledge/ingestion_runner.py`

### Agency Operations

- [Property Search](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/properties/service.py): `src/app/modules/properties/service.py`
- [Mortgage Calculator](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/calculator/engine.py): `src/app/modules/calculator/engine.py`
- [Viewing Bookings](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/bookings/service.py): `src/app/modules/bookings/service.py`
- [CRM Leads](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/leads/service.py): `src/app/modules/leads/service.py`

### State and Integrations

- [PostgreSQL](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/db/session.py): `src/app/db/session.py`
- [Qdrant Vectors](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/integrations/qdrant/client.py): `src/app/integrations/qdrant/client.py`
- [LLM Provider](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/integrations/llm/client.py): `src/app/integrations/llm/client.py`
- [Redis Pub/Sub](https://github.com/munawarjamil/realestate_ai/blob/main/src/app/modules/chat/redis_pubsub.py): `src/app/modules/chat/redis_pubsub.py`

### Other components

- **Visitors**
- **Agency Brokers**
- **Platform Admins**

## Connections

- Visitors → Website Widget: chat through (evidence: `README.md`)
- Website Widget → Widget Sessions: opens session (evidence: `README.md`)
- Widget Sessions → Conversation Service: uses chat service (evidence: `src/app/modules/widget/router.py`)
- Conversation Service → Document RAG: retrieves context (evidence: `src/app/modules/chat/service.py`)
- Conversation Service → LangGraph Agent: runs agent
- LangGraph Agent → LLM Provider: calls model
- LangGraph Agent → Property Search: searches listings (evidence: `README.md`)
- LangGraph Agent → Mortgage Calculator: calculates mortgage (evidence: `README.md`)
- LangGraph Agent → Viewing Bookings: books viewings (evidence: `README.md`)
- Document Ingestion → Qdrant Vectors: indexes vectors
- Agency Brokers → Admin Dashboard: manage conversations (evidence: `README.md`)
- Admin Dashboard → Dashboard API Client: requests data (evidence: `dashboard/src/router.tsx`)
- Dashboard API Client → Chat API: streams chat (evidence: `dashboard/src/api/client.ts`)
- Dashboard API Client → Authentication: authenticates (evidence: `dashboard/src/api/client.ts`)
- Dashboard API Client → Tenant Management: manages tenants (evidence: `dashboard/src/api/client.ts`)
- Dashboard API Client → CRM Leads: manages leads
- Chat API → Conversation Service: delegates requests
- Conversation Service → CRM Leads: qualifies visitors
- Agency Brokers → Broker Handoff: takes over chats (evidence: `README.md`)
- Broker Handoff → Redis Pub/Sub: publishes events (evidence: `README.md`)
- Broker Handoff → LangGraph Agent: dispatches chat (evidence: `src/app/modules/chat/socketio_server.py`)
- Platform Admins → Admin Dashboard: administers platform (evidence: `README.md`)
- Conversation Service → PostgreSQL: stores conversations (evidence: `src/app/modules/chat/service.py`)
- Document Ingestion → Document RAG: feeds retrieval
- Viewing Bookings → PostgreSQL: persists bookings
- CRM Leads → PostgreSQL: persists leads
