# eugene234466/ai-real-estate-lead-assistant architecture

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

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

## Overview

AI Real Estate Lead Assistant provides a prospect web-chat workflow backed by a Flask API: the chat endpoint stores messages, invokes structured AI response generation, updates lead qualification, and can trigger a human-handoff notification. Agents can take over or resume AI; separate backend capabilities cover appointments, scheduled follow-ups, authentication, and CRM pages. The graph combines excerpted calls and SOURCE INDEX references with README-documented capabilities; unsampled page, event, SSE, and domain implementations are represented without inferred call chains.

Main entry points: [`backend/app/modules/conversations/routes.py`](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/conversations/routes.py) (Chat endpoint), [`backend/app/modules/appointments/routes.py`](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/appointments/routes.py) (Appointment API), [`backend/app/modules/followups/tasks.py`](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/followups/tasks.py) (Follow-up tasks), [`backend/app/modules/ai_engine/service.py`](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/service.py) (AI response service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_chat["Chat widget<br/>[ChatWidget.tsx]"]
  node_message_ui["Message display<br/>[MessageBubble.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_crm_pages["CRM pages"]
end

subgraph group_identity["Identity and catalog"]
  node_auth_routes["Authentication API<br/>[routes.py]"]
  node_users[("Users<br/>[models.py]")]
  node_organizations[("Organizations<br/>[models.py]")]
  node_properties[("Properties<br/>[models.py]")]
end

subgraph group_conversation["Conversation and AI"]
  node_chat_routes["Chat endpoint<br/>[routes.py]"]
  node_conversation_data[("Conversations and messages<br/>[models.py]")]
  node_ai_service["AI response service<br/>[service.py]"]
  node_groq["Groq model client<br/>[groq_client.py]"]
  node_output_validation["Output validation<br/>[output_schema.py]"]
end

subgraph group_lifecycle["Lead lifecycle"]
  node_leads[("Lead records<br/>[models.py]")]
  node_lead_states["Lead state machine<br/>[state_machine.py]"]
  node_followup_tasks["Follow-up tasks<br/>[tasks.py]"]
  node_followups[("Follow-up records<br/>[models.py]")]
  node_appointment_routes["Appointment API<br/>[routes.py]"]
  node_appointments[("Appointments<br/>[models.py]")]
  node_notifications[("Notifications<br/>[models.py]")]
  node_event_log[("Event logging")]
end

node_prospect(("Prospect"))
node_agent(("Real estate agent"))
node_db_extensions["Database extensions<br/>[extensions.py]"]
node_tenant_base["Tenant model base<br/>[db_base.py]"]

node_prospect -->|"sends inquiry"| node_chat
node_chat -->|"renders messages"| node_message_ui
node_chat -->|"sends text"| node_api_client
node_api_client -->|"posts message"| node_chat_routes
node_agent -->|"uses CRM"| node_crm_pages
node_crm_pages -.->|"views conversations"| node_chat_routes
node_auth_routes -->|"creates and checks"| node_users
node_auth_routes -->|"creates organization"| node_organizations
node_chat_routes -->|"stores messages"| node_conversation_data
node_chat_routes -->|"selects organization"| node_organizations
node_chat_routes -->|"requests response"| node_ai_service
node_ai_service -->|"loads verified listings"| node_properties
node_ai_service -->|"requests completion"| node_groq
node_ai_service -->|"validates output"| node_output_validation
node_chat_routes -->|"creates or updates"| node_leads
node_chat_routes -->|"applies stage"| node_lead_states
node_chat_routes -->|"records handoff"| node_notifications
node_followup_tasks -->|"schedules and updates"| node_followups
node_followup_tasks -->|"checks inactivity"| node_leads
node_followup_tasks -->|"adds follow-up message"| node_conversation_data
node_followup_tasks -->|"generates message"| node_ai_service
node_followup_tasks -->|"moves to nurture"| node_lead_states
node_appointment_routes -->|"creates appointment"| node_appointments
node_appointment_routes -->|"loads lead"| node_leads
node_appointment_routes -->|"books lead"| node_lead_states
node_appointment_routes -->|"records booking"| node_notifications
node_agent -.->|"books appointment"| node_appointment_routes
node_chat_routes -.->|"logs events"| node_event_log
node_appointment_routes -.->|"logs events"| node_event_log
node_db_extensions -->|"backs models"| node_tenant_base

click node_chat "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/frontend/src/components/chat/ChatWidget.tsx"
click node_message_ui "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/frontend/src/components/chat/MessageBubble.tsx"
click node_api_client "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/frontend/src/api/client.ts"
click node_crm_pages "https://github.com/eugene234466/ai-real-estate-lead-assistant/tree/master/frontend/src/pages"
click node_auth_routes "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/auth/routes.py"
click node_users "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/auth/models.py"
click node_organizations "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/organizations/models.py"
click node_properties "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/properties/models.py"
click node_chat_routes "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/conversations/routes.py"
click node_conversation_data "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/conversations/models.py"
click node_ai_service "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/service.py"
click node_groq "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/groq_client.py"
click node_output_validation "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/output_schema.py"
click node_leads "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/leads/models.py"
click node_lead_states "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/leads/state_machine.py"
click node_followup_tasks "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/followups/tasks.py"
click node_followups "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/followups/models.py"
click node_appointment_routes "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/appointments/routes.py"
click node_appointments "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/appointments/models.py"
click node_notifications "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/notifications/models.py"
click node_event_log "https://github.com/eugene234466/ai-real-estate-lead-assistant/tree/master/backend/app/modules/events"
click node_db_extensions "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/extensions.py"
click node_tenant_base "https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/shared/db_base.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_chat,node_message_ui,node_api_client,node_crm_pages toneBlue
class node_auth_routes,node_users,node_organizations,node_properties,node_db_extensions toneAmber
class node_chat_routes,node_conversation_data,node_ai_service,node_groq,node_output_validation toneMint
class node_leads,node_lead_states,node_followup_tasks,node_followups,node_appointment_routes,node_appointments,node_notifications,node_event_log toneRose
class node_prospect,node_agent,node_tenant_base toneIndigo
```

## Components

### Web experience

- [Chat widget](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/frontend/src/components/chat/ChatWidget.tsx): `frontend/src/components/chat/ChatWidget.tsx`
- [Message display](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/frontend/src/components/chat/MessageBubble.tsx): `frontend/src/components/chat/MessageBubble.tsx`
- [API client](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [CRM pages](https://github.com/eugene234466/ai-real-estate-lead-assistant/tree/master/frontend/src/pages): `frontend/src/pages`

### Identity and catalog

- [Authentication API](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/auth/routes.py): `backend/app/modules/auth/routes.py`
- [Users](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/auth/models.py): `backend/app/modules/auth/models.py`
- [Organizations](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/organizations/models.py): `backend/app/modules/organizations/models.py`
- [Properties](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/properties/models.py): `backend/app/modules/properties/models.py`

### Conversation and AI

- [Chat endpoint](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/conversations/routes.py): `backend/app/modules/conversations/routes.py`
- [Conversations and messages](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/conversations/models.py): `backend/app/modules/conversations/models.py`
- [AI response service](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/service.py): `backend/app/modules/ai_engine/service.py`
- [Groq model client](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/groq_client.py): `backend/app/modules/ai_engine/groq_client.py`
- [Output validation](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/ai_engine/output_schema.py): `backend/app/modules/ai_engine/output_schema.py`

### Lead lifecycle

- [Lead records](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/leads/models.py): `backend/app/modules/leads/models.py`
- [Lead state machine](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/leads/state_machine.py): `backend/app/modules/leads/state_machine.py`
- [Follow-up tasks](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/followups/tasks.py): `backend/app/modules/followups/tasks.py`
- [Follow-up records](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/followups/models.py): `backend/app/modules/followups/models.py`
- [Appointment API](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/appointments/routes.py): `backend/app/modules/appointments/routes.py`
- [Appointments](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/appointments/models.py): `backend/app/modules/appointments/models.py`
- [Notifications](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/modules/notifications/models.py): `backend/app/modules/notifications/models.py`
- [Event logging](https://github.com/eugene234466/ai-real-estate-lead-assistant/tree/master/backend/app/modules/events): `backend/app/modules/events`

### Other components

- **Prospect**
- **Real estate agent**
- [Database extensions](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/extensions.py): `backend/app/extensions.py`
- [Tenant model base](https://github.com/eugene234466/ai-real-estate-lead-assistant/blob/master/backend/app/shared/db_base.py): `backend/app/shared/db_base.py`

## Connections

- Prospect → Chat widget: sends inquiry (evidence: `README.md`)
- Chat widget → Message display: renders messages (evidence: `frontend/src/components/chat/ChatWidget.tsx`)
- Chat widget → API client: sends text (evidence: `frontend/src/components/chat/ChatWidget.tsx`)
- API client → Chat endpoint: posts message (evidence: `frontend/src/api/client.ts`)
- Real estate agent → CRM pages: uses CRM (evidence: `README.md`)
- CRM pages → Chat endpoint: views conversations
- Authentication API → Users: creates and checks (evidence: `backend/app/modules/auth/routes.py`)
- Authentication API → Organizations: creates organization (evidence: `backend/app/modules/auth/routes.py`)
- Chat endpoint → Conversations and messages: stores messages (evidence: `backend/app/modules/conversations/routes.py`)
- Chat endpoint → Organizations: selects organization (evidence: `backend/app/modules/conversations/routes.py`)
- Chat endpoint → AI response service: requests response (evidence: `backend/app/modules/conversations/routes.py`)
- AI response service → Properties: loads verified listings (evidence: `backend/app/modules/ai_engine/service.py`)
- AI response service → Groq model client: requests completion (evidence: `backend/app/modules/ai_engine/service.py`)
- AI response service → Output validation: validates output (evidence: `backend/app/modules/ai_engine/service.py`)
- Chat endpoint → Lead records: creates or updates (evidence: `backend/app/modules/conversations/routes.py`)
- Chat endpoint → Lead state machine: applies stage (evidence: `backend/app/modules/conversations/routes.py`)
- Chat endpoint → Notifications: records handoff (evidence: `backend/app/modules/conversations/routes.py`)
- Follow-up tasks → Follow-up records: schedules and updates (evidence: `backend/app/modules/followups/tasks.py`)
- Follow-up tasks → Lead records: checks inactivity (evidence: `backend/app/modules/followups/tasks.py`)
- Follow-up tasks → Conversations and messages: adds follow-up message (evidence: `backend/app/modules/followups/tasks.py`)
- Follow-up tasks → AI response service: generates message (evidence: `backend/app/modules/followups/tasks.py`)
- Follow-up tasks → Lead state machine: moves to nurture (evidence: `backend/app/modules/followups/tasks.py`)
- Appointment API → Appointments: creates appointment (evidence: `backend/app/modules/appointments/routes.py`)
- Appointment API → Lead records: loads lead (evidence: `backend/app/modules/appointments/routes.py`)
- Appointment API → Lead state machine: books lead (evidence: `backend/app/modules/appointments/routes.py`)
- Appointment API → Notifications: records booking (evidence: `backend/app/modules/appointments/routes.py`)
- Real estate agent → Appointment API: books appointment (evidence: `README.md`)
- Chat endpoint → Event logging: logs events (evidence: `README.md`)
- Appointment API → Event logging: logs events (evidence: `README.md`)
- Database extensions → Tenant model base: backs models (evidence: `backend/app/shared/db_base.py`)
