# aweretelnikov-png/small-business-demo architecture

> Architecture diagram of the GitHub repository aweretelnikov-png/small-business-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aweretelnikov-png/small-business-demo
- Repository: https://github.com/aweretelnikov-png/small-business-demo

## Overview

This repository is a demo business-automation suite: sales data becomes PostgreSQL reporting, staff and customers get a document-grounded AI FAQ, and website leads are stored, notified, and synchronized with Twenty CRM. The graph preserves those separate workflows and the CRM status-webhook return path. AI retrieval/model wiring and some dashboard runtime details are documented capabilities; their implementation is not included in the sampled source, so those links reflect documentation rather than inspected calls.

Main entry points: [`crm-leads/backend/app/main.py`](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/main.py) (FastAPI), [`crm-leads/backend/app/services/leads.py`](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/leads.py) (Lead services), [`crm-leads/backend/app/services/integrations.py`](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/integrations.py) (Integration dispatcher), [`ai-faq/docker-compose.yml`](https://github.com/aweretelnikov-png/small-business-demo/blob/master/ai-faq/docker-compose.yml) (Open WebUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analytics["Sales analytics"]
  node_etl["ETL orchestration<br/>[run_all.py]"]
  node_customer_load["Customer loader<br/>[load_customers.py]"]
  node_lead_deal_load["Lead and deal loaders"]
  node_raw_data["CSV and XLSX"]
  node_sales_db[("Sales PostgreSQL<br/>[docker-compose.yml]")]
  node_sales_views["Sales reporting views"]
end

subgraph group_ai["AI FAQ"]
  node_client_docs["Client knowledge"]
  node_staff_docs["Staff knowledge"]
  node_faq_rag["Retrieval and embeddings"]
  node_webui["Open WebUI<br/>[docker-compose.yml]"]
end

subgraph group_crm["Lead and CRM flow"]
  node_lead_form["Lead form<br/>[app.js]"]
  node_lead_api["FastAPI<br/>[main.py]"]
  node_lead_service["Lead services<br/>[leads.py]"]
  node_crm_db[("CRM PostgreSQL<br/>[database.py]")]
  node_integrations["Integration dispatcher<br/>[integrations.py]"]
  node_webhook["Webhook processing<br/>[twenty_webhook.py]"]
end

subgraph group_reporting["Reporting surfaces"]
  node_sales_metabase["Sales dashboards<br/>[docker-compose.yml]"]
  node_crm_metabase["CRM dashboard"]
end

node_business(("Business data"))
node_faq_user(("FAQ user"))
node_model["Ollama models"]
node_website_user(("Website visitor"))
node_telegram["Telegram"]
node_twenty["Twenty CRM"]

node_business -->|"provides files"| node_raw_data
node_etl -->|"runs loader"| node_customer_load
node_etl -->|"runs loaders"| node_lead_deal_load
node_raw_data -->|"reads customers"| node_customer_load
node_raw_data -->|"reads sales data"| node_lead_deal_load
node_customer_load -->|"writes customers"| node_sales_db
node_lead_deal_load -->|"writes sales records"| node_sales_db
node_sales_db -->|"feeds views"| node_sales_views
node_sales_views -->|"supports dashboards"| node_sales_metabase
node_faq_user -->|"asks question"| node_webui
node_client_docs -->|"grounds answers"| node_faq_rag
node_staff_docs -->|"grounds answers"| node_faq_rag
node_faq_rag -->|"retrieves context"| node_webui
node_webui -->|"requests completion"| node_model
node_webui -->|"returns answer"| node_faq_user
node_website_user -->|"submits lead"| node_lead_form
node_lead_form -->|"posts lead"| node_lead_api
node_lead_api -->|"saves lead"| node_lead_service
node_lead_service -->|"writes lead"| node_crm_db
node_lead_api -->|"dispatches integrations"| node_integrations
node_integrations -->|"sends notification"| node_telegram
node_integrations -->|"syncs lead"| node_twenty
node_integrations -->|"updates sync status"| node_lead_service
node_twenty -->|"posts stage webhook"| node_lead_api
node_lead_api -->|"verifies and processes"| node_webhook
node_webhook -->|"updates status history"| node_lead_service
node_lead_service -->|"writes status"| node_crm_db
node_crm_db -->|"provides analytics"| node_crm_metabase

click node_etl "https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/etl/run_all.py"
click node_customer_load "https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/etl/load_customers.py"
click node_lead_deal_load "https://github.com/aweretelnikov-png/small-business-demo/tree/master/analytics/etl"
click node_raw_data "https://github.com/aweretelnikov-png/small-business-demo/tree/master/analytics/data/raw"
click node_sales_db "https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/docker-compose.yml"
click node_sales_views "https://github.com/aweretelnikov-png/small-business-demo/tree/master/analytics/sql"
click node_sales_metabase "https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/docker-compose.yml"
click node_client_docs "https://github.com/aweretelnikov-png/small-business-demo/tree/master/ai-faq/knowledge"
click node_staff_docs "https://github.com/aweretelnikov-png/small-business-demo/tree/master/ai-faq/internal_knowledge"
click node_faq_rag "https://github.com/aweretelnikov-png/small-business-demo/tree/master/ai-faq"
click node_webui "https://github.com/aweretelnikov-png/small-business-demo/blob/master/ai-faq/docker-compose.yml"
click node_lead_form "https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/frontend/app.js"
click node_lead_api "https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/main.py"
click node_lead_service "https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/leads.py"
click node_crm_db "https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/database.py"
click node_integrations "https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/integrations.py"
click node_webhook "https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/twenty_webhook.py"
click node_crm_metabase "https://github.com/aweretelnikov-png/small-business-demo/tree/master/crm-leads/sql"

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_etl,node_customer_load,node_lead_deal_load,node_raw_data,node_sales_db,node_sales_views,node_faq_user toneBlue
class node_client_docs,node_staff_docs,node_faq_rag,node_webui toneAmber
class node_lead_form,node_lead_api,node_lead_service,node_crm_db,node_integrations,node_webhook toneMint
class node_sales_metabase,node_crm_metabase toneRose
class node_business,node_model,node_website_user,node_telegram,node_twenty toneIndigo
```

## Components

### Sales analytics

- [ETL orchestration](https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/etl/run_all.py): `analytics/etl/run_all.py`
- [Customer loader](https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/etl/load_customers.py): `analytics/etl/load_customers.py`
- [Lead and deal loaders](https://github.com/aweretelnikov-png/small-business-demo/tree/master/analytics/etl): `analytics/etl`
- [CSV and XLSX](https://github.com/aweretelnikov-png/small-business-demo/tree/master/analytics/data/raw): `analytics/data/raw`
- [Sales PostgreSQL](https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/docker-compose.yml): `analytics/docker-compose.yml`
- [Sales reporting views](https://github.com/aweretelnikov-png/small-business-demo/tree/master/analytics/sql): `analytics/sql`

### AI FAQ

- [Client knowledge](https://github.com/aweretelnikov-png/small-business-demo/tree/master/ai-faq/knowledge): `ai-faq/knowledge`
- [Staff knowledge](https://github.com/aweretelnikov-png/small-business-demo/tree/master/ai-faq/internal_knowledge): `ai-faq/internal_knowledge`
- [Retrieval and embeddings](https://github.com/aweretelnikov-png/small-business-demo/tree/master/ai-faq): `ai-faq`
- [Open WebUI](https://github.com/aweretelnikov-png/small-business-demo/blob/master/ai-faq/docker-compose.yml): `ai-faq/docker-compose.yml`

### Lead and CRM flow

- [Lead form](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/frontend/app.js): `crm-leads/frontend/app.js`
- [FastAPI](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/main.py): `crm-leads/backend/app/main.py`
- [Lead services](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/leads.py): `crm-leads/backend/app/services/leads.py`
- [CRM PostgreSQL](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/database.py): `crm-leads/backend/app/database.py`
- [Integration dispatcher](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/integrations.py): `crm-leads/backend/app/services/integrations.py`
- [Webhook processing](https://github.com/aweretelnikov-png/small-business-demo/blob/master/crm-leads/backend/app/services/twenty_webhook.py): `crm-leads/backend/app/services/twenty_webhook.py`

### Reporting surfaces

- [Sales dashboards](https://github.com/aweretelnikov-png/small-business-demo/blob/master/analytics/docker-compose.yml): `analytics/docker-compose.yml`
- [CRM dashboard](https://github.com/aweretelnikov-png/small-business-demo/tree/master/crm-leads/sql): `crm-leads/sql`

### Other components

- **Business data**
- **FAQ user**
- **Ollama models**
- **Website visitor**
- **Telegram**
- **Twenty CRM**

## Connections

- Business data → CSV and XLSX: provides files
- ETL orchestration → Customer loader: runs loader
- ETL orchestration → Lead and deal loaders: runs loaders
- CSV and XLSX → Customer loader: reads customers
- CSV and XLSX → Lead and deal loaders: reads sales data
- Customer loader → Sales PostgreSQL: writes customers
- Lead and deal loaders → Sales PostgreSQL: writes sales records
- Sales PostgreSQL → Sales reporting views: feeds views
- Sales reporting views → Sales dashboards: supports dashboards
- FAQ user → Open WebUI: asks question
- Client knowledge → Retrieval and embeddings: grounds answers
- Staff knowledge → Retrieval and embeddings: grounds answers
- Retrieval and embeddings → Open WebUI: retrieves context
- Open WebUI → Ollama models: requests completion
- Open WebUI → FAQ user: returns answer
- Website visitor → Lead form: submits lead
- Lead form → FastAPI: posts lead
- FastAPI → Lead services: saves lead
- Lead services → CRM PostgreSQL: writes lead
- FastAPI → Integration dispatcher: dispatches integrations
- Integration dispatcher → Telegram: sends notification
- Integration dispatcher → Twenty CRM: syncs lead
- Integration dispatcher → Lead services: updates sync status
- Twenty CRM → FastAPI: posts stage webhook
- FastAPI → Webhook processing: verifies and processes
- Webhook processing → Lead services: updates status history
- Lead services → CRM PostgreSQL: writes status
- CRM PostgreSQL → CRM dashboard: provides analytics