# tecso-dev/sorinflow-data-mamager architecture

> Architecture diagram of the GitHub repository tecso-dev/sorinflow-data-mamager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tecso-dev/sorinflow-data-mamager
- Repository: https://github.com/tecso-dev/sorinflow-data-mamager

## Overview

SorinFlow is a Persian real-estate workspace whose main flow collects Divar listings, stores and enriches property records, then matches opportunities to CRM customers for follow-up. Staff use a role-aware dashboard; customers have a separate portal. The README documents additional collection scheduling, authenticated contact extraction, messaging, AI, and operational integrations. Edges rely on README statements or shown source references; unsampled implementation details are represented only where the README identifies the capability.

Main entry points: [`app/crm/match_engine.py`](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/crm/match_engine.py) (Automatic match engine), [`app/scraper/divar_scraper.py`](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/scraper/divar_scraper.py) (Divar scraper), [`app/api/routes`](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/api/routes) (API routers), [`frontend-next/src/app/portal`](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/frontend-next/src/app/portal) (Customer portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Divar collection"]
  node_scraper["Divar scraper<br/>[divar_scraper.py]"]
  node_divar_sessions["Divar sessions<br/>[divar_session.py]"]
  node_scrape_queue["Scrape queue and schedules<br/>[scrape_queue.py]"]
end

subgraph group_inventory["Property intelligence"]
  node_property_store[("Property inventory<br/>[property.py]")]
  node_listing_reader["Listing reader<br/>[listing_reader.py]"]
  node_embeddings["Listing embeddings<br/>[embeddings.py]"]
  node_match_service["Property matching<br/>[match_service.py]"]
  node_llm["Model gateway<br/>[llm.py]"]
  node_assistant["Telegram assistant<br/>[assistant.py]"]
end

subgraph group_crm["CRM and portal"]
  node_portal_ui["Customer portal"]
  node_match_engine["Automatic match engine<br/>[match_engine.py]"]
  node_crm["CRM workflow"]
  node_portal_bridge["Portal request bridge<br/>[portal_bridge.py]"]
end

subgraph group_access["Users and messaging"]
  node_dashboard["Staff dashboard"]
  node_auth["Authentication and permissions"]
  node_sms_email["SMS and email"]
end

subgraph group_operations["Runtime and integrations"]
  node_api["API routers"]
  node_database[("Database and cache<br/>[database.py]")]
  node_supervisor["Background supervision<br/>[supervisor.py]"]
  node_gcp["Google Cloud export<br/>[pipeline.py]"]
end

node_staff(("Staff"))
node_visitor(("Portal visitor"))
node_divar{{"Divar"}}
node_telegram{{"Telegram"}}

node_staff -->|"uses"| node_dashboard
node_visitor -->|"uses"| node_portal_ui
node_dashboard -.->|"requests"| node_api
node_portal_ui -.->|"requests"| node_api
node_api -->|"guards"| node_auth
node_api -->|"starts collection"| node_scraper
node_scraper -->|"collects listings"| node_divar
node_divar_sessions -->|"authenticates"| node_divar
node_scrape_queue -->|"dispatches jobs"| node_scraper
node_scraper -->|"stores listings"| node_property_store
node_property_store -->|"persists in"| node_database
node_listing_reader -->|"requests analysis"| node_llm
node_embeddings -->|"requests embeddings"| node_llm
node_match_service -->|"uses similarity"| node_embeddings
node_match_engine -->|"judges listings"| node_property_store
node_match_engine -->|"scores matches"| node_match_service
node_match_engine -->|"records matches"| node_portal_bridge
node_match_engine -->|"notifies consultants"| node_crm
node_crm -->|"sends messages"| node_sms_email
node_portal_ui -.->|"submits requests"| node_portal_bridge
node_assistant -.->|"uses model gateway"| node_llm
node_supervisor -->|"supervises loops"| node_scrape_queue
node_supervisor -->|"runs exporter"| node_gcp
node_gcp -.->|"exports backups"| node_telegram

click node_dashboard "https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/frontend-next/src/app/panel/(app)"
click node_portal_ui "https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/frontend-next/src/app/portal"
click node_api "https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/api/routes"
click node_auth "https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/auth"
click node_scraper "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/scraper/divar_scraper.py"
click node_divar_sessions "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/divar_session.py"
click node_scrape_queue "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/scrape_queue.py"
click node_property_store "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/models/property.py"
click node_database "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/database.py"
click node_listing_reader "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/ai/listing_reader.py"
click node_embeddings "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/ai/embeddings.py"
click node_match_service "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/match_service.py"
click node_match_engine "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/crm/match_engine.py"
click node_crm "https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/crm"
click node_portal_bridge "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/crm/portal_bridge.py"
click node_llm "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/llm.py"
click node_sms_email "https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/services"
click node_assistant "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/ai/assistant.py"
click node_supervisor "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/supervisor.py"
click node_gcp "https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/gcp/pipeline.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_scraper,node_divar_sessions,node_scrape_queue toneBlue
class node_property_store,node_listing_reader,node_embeddings,node_match_service,node_llm,node_assistant toneAmber
class node_portal_ui,node_match_engine,node_crm,node_portal_bridge toneMint
class node_dashboard,node_auth,node_sms_email toneRose
class node_api,node_database,node_supervisor,node_gcp,node_staff,node_visitor,node_divar,node_telegram toneIndigo
```

## Components

### Divar collection

- [Divar scraper](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/scraper/divar_scraper.py): `app/scraper/divar_scraper.py`
- [Divar sessions](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/divar_session.py): `app/services/divar_session.py`
- [Scrape queue and schedules](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/scrape_queue.py): `app/services/scrape_queue.py`

### Property intelligence

- [Property inventory](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/models/property.py): `app/models/property.py`
- [Listing reader](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/ai/listing_reader.py): `app/ai/listing_reader.py`
- [Listing embeddings](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/ai/embeddings.py): `app/ai/embeddings.py`
- [Property matching](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/match_service.py): `app/services/match_service.py`
- [Model gateway](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/llm.py): `app/services/llm.py`
- [Telegram assistant](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/ai/assistant.py): `app/ai/assistant.py`

### CRM and portal

- [Customer portal](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/frontend-next/src/app/portal): `frontend-next/src/app/portal`
- [Automatic match engine](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/crm/match_engine.py): `app/crm/match_engine.py`
- [CRM workflow](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/crm): `app/crm`
- [Portal request bridge](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/crm/portal_bridge.py): `app/crm/portal_bridge.py`

### Users and messaging

- [Staff dashboard](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/frontend-next/src/app/panel/(app)): `frontend-next/src/app/panel/(app)`
- [Authentication and permissions](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/auth): `app/auth`
- [SMS and email](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/services): `app/services`

### Runtime and integrations

- [API routers](https://github.com/tecso-dev/sorinflow-data-mamager/tree/main/app/api/routes): `app/api/routes`
- [Database and cache](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/database.py): `app/database.py`
- [Background supervision](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/supervisor.py): `app/services/supervisor.py`
- [Google Cloud export](https://github.com/tecso-dev/sorinflow-data-mamager/blob/main/app/services/gcp/pipeline.py): `app/services/gcp/pipeline.py`

### Other components

- **Staff**
- **Portal visitor**
- **Divar**
- **Telegram**

## Connections

- Staff → Staff dashboard: uses (evidence: `README.md`)
- Portal visitor → Customer portal: uses (evidence: `README.md`)
- Staff dashboard → API routers: requests
- Customer portal → API routers: requests
- API routers → Authentication and permissions: guards (evidence: `README.md`)
- API routers → Divar scraper: starts collection (evidence: `README.md`)
- Divar scraper → Divar: collects listings (evidence: `README.md`)
- Divar sessions → Divar: authenticates (evidence: `README.md`)
- Scrape queue and schedules → Divar scraper: dispatches jobs (evidence: `README.md`)
- Divar scraper → Property inventory: stores listings (evidence: `README.md`)
- Property inventory → Database and cache: persists in (evidence: `app/database.py`)
- Listing reader → Model gateway: requests analysis (evidence: `app/ai/listing_reader.py`)
- Listing embeddings → Model gateway: requests embeddings (evidence: `app/ai/embeddings.py`)
- Property matching → Listing embeddings: uses similarity (evidence: `app/services/match_service.py`)
- Automatic match engine → Property inventory: judges listings (evidence: `app/crm/match_engine.py`)
- Automatic match engine → Property matching: scores matches (evidence: `app/crm/match_engine.py`)
- Automatic match engine → Portal request bridge: records matches (evidence: `app/crm/match_engine.py`)
- Automatic match engine → CRM workflow: notifies consultants (evidence: `README.md`)
- CRM workflow → SMS and email: sends messages (evidence: `README.md`)
- Customer portal → Portal request bridge: submits requests
- Telegram assistant → Model gateway: uses model gateway
- Background supervision → Scrape queue and schedules: supervises loops (evidence: `app/services/supervisor.py`)
- Background supervision → Google Cloud export: runs exporter (evidence: `app/services/gcp/pipeline.py`)
- Google Cloud export → Telegram: exports backups
