# rohangawande2303/multi-tenant-real-estate-crm architecture

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

- Interactive diagram: https://gitdiagram.com/rohangawande2303/multi-tenant-real-estate-crm
- Repository: https://github.com/rohangawande2303/multi-tenant-real-estate-crm

## Overview

Social Pulse is a multi-tenant real-estate CRM for agencies and developers. Users manage projects, teams, lead pipelines, analytics, and telecalling activity; external advertising and website forms can also submit leads. The backend routes API requests, scopes database access by tenant schema, and processes inbound leads with source-specific normalization and deduplication. The README documents the frontend-to-API-to-PostgreSQL deployment and major product capabilities. Some endpoint implementations were not sampled, so their internal call relationships are omitted rather than inferred.

Main entry points: [`backend/app/api/endpoints/webhooks.py`](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/webhooks.py) (Webhook receiver), [`backend/app/api/api.py`](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/api.py) (API router), [`backend/app/api/endpoints/ingest_google.py`](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/ingest_google.py) (Google Ads ingestion), [`backend/app/models/lead.py`](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/lead.py) (Lead records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["CRM interface"]
  node_web["CRM screens"]
end

subgraph group_api["API and access"]
  node_api_router["API router<br/>[api.py]"]
  node_auth["Authentication and RBAC"]
end

subgraph group_leads["Lead operations"]
  node_lead_api["Lead management API<br/>[leads.py]"]
  node_lead_store[("Lead records<br/>[lead.py]")]
  node_lead_dedupe["Lead deduplication"]
  node_import_export["Lead import and export<br/>[import_export.py]"]
  node_import_service["Import processing<br/>[import_service.py]"]
end

subgraph group_tenants["Tenant data"]
  node_tenant_provision["Tenant provisioning<br/>[tenant_service.py]"]
  node_tenant_context["Tenant schema context<br/>[database.py]"]
  node_tenant_model[("Tenant and user records<br/>[models.py]")]
end

subgraph group_insights["Integrations and insights"]
  node_webhook_ingress["Webhook receiver<br/>[webhooks.py]"]
  node_webhook_handlers["Source handlers"]
  node_webhook_security["Webhook verification"]
  node_google_ingest["Google Ads ingestion<br/>[ingest_google.py]"]
  node_website_ingest["Website form ingestion<br/>[ingest_website.py]"]
  node_integrations[("Integration configuration<br/>[integration.py]")]
  node_webhook_log[("Webhook audit records<br/>[webhook_log.py]")]
  node_dashboard["Dashboard and analytics<br/>[dashboard.py]"]
  node_activity[("Activity and audit<br/>[lead_activity.py]")]
end

node_user(("CRM user"))
node_external_sources{{"Ad and form sources"}}
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_web
node_web -->|"calls API"| node_api_router
node_api_router -->|"routes auth"| node_auth
node_api_router -->|"routes leads"| node_lead_api
node_api_router -->|"routes webhooks"| node_webhook_ingress
node_api_router -->|"routes ingestion"| node_google_ingest
node_api_router -->|"routes ingestion"| node_website_ingest
node_tenant_provision -->|"creates tenant"| node_tenant_model
node_tenant_provision -->|"creates schema"| node_postgres
node_tenant_context -->|"sets schema"| node_postgres
node_webhook_ingress -->|"dispatches handler"| node_webhook_handlers
node_webhook_ingress -->|"verifies signature"| node_webhook_security
node_webhook_ingress -->|"reads config"| node_integrations
node_webhook_ingress -->|"records requests"| node_webhook_log
node_webhook_ingress -->|"writes leads"| node_lead_store
node_google_ingest -->|"checks duplicates"| node_lead_dedupe
node_google_ingest -->|"writes leads"| node_lead_store
node_google_ingest -->|"reads integration"| node_integrations
node_website_ingest -->|"writes leads"| node_lead_store
node_website_ingest -->|"updates stats"| node_integrations
node_external_sources -.->|"submits leads"| node_webhook_ingress
node_external_sources -.->|"submits leads"| node_google_ingest
node_external_sources -->|"submits forms"| node_website_ingest
node_import_export -.->|"calls import"| node_import_service
node_import_service -->|"creates leads"| node_lead_store
node_web -.->|"views CRM data"| node_postgres
node_dashboard -.->|"queries analytics"| node_postgres
node_lead_api -.->|"manages leads"| node_lead_store

click node_web "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/tree/main/frontend/src/app/(dashboard)"
click node_api_router "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/api.py"
click node_auth "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/tree/main/backend/app/auth"
click node_tenant_provision "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/services/tenant_service.py"
click node_tenant_context "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/core/database.py"
click node_tenant_model "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/auth/models.py"
click node_lead_api "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/leads.py"
click node_lead_store "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/lead.py"
click node_lead_dedupe "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/core/lead_deduplication.py"
click node_import_export "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/import_export.py"
click node_import_service "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/services/import_service.py"
click node_webhook_ingress "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/webhooks.py"
click node_webhook_handlers "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/tree/main/backend/app/api/webhook_handlers"
click node_webhook_security "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/utils/webhook_security.py"
click node_google_ingest "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/ingest_google.py"
click node_website_ingest "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/ingest_website.py"
click node_integrations "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/integration.py"
click node_webhook_log "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/webhook_log.py"
click node_dashboard "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/dashboard.py"
click node_activity "https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/lead_activity.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_web,node_user toneBlue
class node_api_router,node_auth,node_postgres toneAmber
class node_lead_api,node_lead_store,node_lead_dedupe,node_import_export,node_import_service toneMint
class node_tenant_provision,node_tenant_context,node_tenant_model toneRose
class node_webhook_ingress,node_webhook_handlers,node_webhook_security,node_google_ingest,node_website_ingest,node_integrations,node_webhook_log,node_dashboard,node_activity,node_external_sources toneIndigo
```

## Components

### CRM interface

- [CRM screens](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/tree/main/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`

### API and access

- [API router](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/api.py): `backend/app/api/api.py`
- [Authentication and RBAC](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/tree/main/backend/app/auth): `backend/app/auth`

### Lead operations

- [Lead management API](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/leads.py): `backend/app/api/endpoints/leads.py`
- [Lead records](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/lead.py): `backend/app/models/lead.py`
- [Lead deduplication](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/core/lead_deduplication.py): `backend/app/core/lead_deduplication.py`
- [Lead import and export](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/import_export.py): `backend/app/api/endpoints/import_export.py`
- [Import processing](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/services/import_service.py): `backend/app/services/import_service.py`

### Tenant data

- [Tenant provisioning](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/services/tenant_service.py): `backend/app/services/tenant_service.py`
- [Tenant schema context](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Tenant and user records](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/auth/models.py): `backend/app/auth/models.py`

### Integrations and insights

- [Webhook receiver](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/webhooks.py): `backend/app/api/endpoints/webhooks.py`
- [Source handlers](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/tree/main/backend/app/api/webhook_handlers): `backend/app/api/webhook_handlers`
- [Webhook verification](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/utils/webhook_security.py): `backend/app/utils/webhook_security.py`
- [Google Ads ingestion](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/ingest_google.py): `backend/app/api/endpoints/ingest_google.py`
- [Website form ingestion](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/ingest_website.py): `backend/app/api/endpoints/ingest_website.py`
- [Integration configuration](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/integration.py): `backend/app/models/integration.py`
- [Webhook audit records](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/webhook_log.py): `backend/app/models/webhook_log.py`
- [Dashboard and analytics](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/api/endpoints/dashboard.py): `backend/app/api/endpoints/dashboard.py`
- [Activity and audit](https://github.com/rohangawande2303/multi-tenant-real-estate-crm/blob/main/backend/app/models/lead_activity.py): `backend/app/models/lead_activity.py`

### Other components

- **CRM user**
- **Ad and form sources**
- **PostgreSQL**

## Connections

- CRM user → CRM screens: uses
- CRM screens → API router: calls API
- API router → Authentication and RBAC: routes auth (evidence: `backend/app/api/api.py`)
- API router → Lead management API: routes leads (evidence: `backend/app/api/api.py`)
- API router → Webhook receiver: routes webhooks (evidence: `backend/app/api/api.py`)
- API router → Google Ads ingestion: routes ingestion (evidence: `backend/app/api/api.py`)
- API router → Website form ingestion: routes ingestion (evidence: `backend/app/api/api.py`)
- Tenant provisioning → Tenant and user records: creates tenant (evidence: `backend/app/services/tenant_service.py`)
- Tenant provisioning → PostgreSQL: creates schema (evidence: `backend/app/services/tenant_service.py`)
- Tenant schema context → PostgreSQL: sets schema (evidence: `backend/app/core/database.py`)
- Webhook receiver → Source handlers: dispatches handler (evidence: `backend/app/api/endpoints/webhooks.py`)
- Webhook receiver → Webhook verification: verifies signature (evidence: `backend/app/api/endpoints/webhooks.py`)
- Webhook receiver → Integration configuration: reads config (evidence: `backend/app/api/endpoints/webhooks.py`)
- Webhook receiver → Webhook audit records: records requests (evidence: `backend/app/api/endpoints/webhooks.py`)
- Webhook receiver → Lead records: writes leads (evidence: `backend/app/api/endpoints/webhooks.py`)
- Google Ads ingestion → Lead deduplication: checks duplicates (evidence: `backend/app/api/endpoints/ingest_google.py`)
- Google Ads ingestion → Lead records: writes leads (evidence: `backend/app/api/endpoints/ingest_google.py`)
- Google Ads ingestion → Integration configuration: reads integration (evidence: `backend/app/api/endpoints/ingest_google.py`)
- Website form ingestion → Lead records: writes leads (evidence: `backend/app/api/endpoints/ingest_website.py`)
- Website form ingestion → Integration configuration: updates stats (evidence: `backend/app/api/endpoints/ingest_website.py`)
- Ad and form sources → Webhook receiver: submits leads
- Ad and form sources → Google Ads ingestion: submits leads
- Ad and form sources → Website form ingestion: submits forms (evidence: `backend/app/api/endpoints/ingest_website.py`)
- Lead import and export → Import processing: calls import
- Import processing → Lead records: creates leads (evidence: `backend/app/services/import_service.py`)
- CRM screens → PostgreSQL: views CRM data
- Dashboard and analytics → PostgreSQL: queries analytics
- Lead management API → Lead records: manages leads
