From c8f46ac6d403491c3115f1f82c1624af222cd39f Mon Sep 17 00:00:00 2001
From: neo <397763@gmail.com>
Date: Wed, 10 Jun 2026 21:01:21 +0500
Subject: [PATCH] Add architecture diagram and component description

---
 ARCHITECTURE.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 ARCHITECTURE.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..b20302d
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,135 @@
+# 🏗️ Архитектура calls24
+
+## Система: от звонка до звонка
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        КЛИЕНТ (бизнес)                              │
+│   Звонки операторов (WAV/MP3)  →  SIP-линии  →  CRM (Bitrix24)     │
+└────────┬──────────────────────────────┬──────────────────┬──────────┘
+         │                              │                  │
+         ▼                              ▼                  ▼
+┌─────────────────────┐  ┌────────────────────┐  ┌──────────────────┐
+│  calls24-аналитика   │  │  SIP-коннектор     │  │  calls24-робот   │
+│  (FastAPI + LLM)    │  │  (WebSIP Proxy)    │  │  (Yandex Realtime│
+│                     │  │                    │  │   WebSocket)      │
+│  • STT (распозн.)  │  │  SIP ←→ WebSocket  │  │                  │
+│  • LLM-анализ      │  │  RTP ↔ Media       │  │  • STT→LLM→TTS   │
+│  • Паттерны продаж  │  │  (аудио микшир.)   │  │  (задержка <1с)  │
+│  • Рекомендации    │  │                    │  │  • Brand Voice   │
+└────────┬────────────┘  └────────┬───────────┘  └────────┬─────────┘
+         │                        │                        │
+         ▼                        │                        │
+┌─────────────────────────────────────────────────────────────────────┐
+│                    calls24-ядро (FastAPI)                           │
+│                                                                     │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
+│  │ PostgreSQL│  │  Qdrant  │  │   Redis  │  │  Yandex AI API  │   │
+│  │(звонки,  │  │(векторы  │  │(очереди, │  │ (speech-realtime│   │
+│  │ скрипты) │  │ звонков) │  │ кэш)     │  │  -250923)       │   │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘   │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │                 Замкнутый цикл обучения                       │  │
+│  │                                                              │  │
+│  │  Робот звонит → Запись звонка → Анализ → Улучшение скрипта   │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Компоненты
+
+### 1. calls24-аналитика (voice-analyzer)
+```
+voice-analyzer/
+├── main.py           # FastAPI (порт 8460)
+├── stt.py            # Yandex STT (locazli) / Yandex Speech
+├── analyzer.py       # LLM-анализ звонков (Qwen35B / Yandex GPT)
+├── pattern.py        # Выявление паттернов продаж
+├── report.py         # Генерация отчёта (HTML/PDF)
+└── .env              # API ключи
+```
+
+**Функции:**
+- Приём аудиофайлов (WAV/MP3, до 100МБ)
+- Распознавание речи (Yandex STT / Whisper)
+- Анализ текста: скрипт, тайминги, возражения, конверсия
+- Сравнение операторов: кто лучше, почему
+- Генерация отчёта: «что нужно исправить»
+- Экспорт паттернов для генерации скрипта
+
+### 2. calls24-робот (voice-bot)
+```
+voice-bot/
+├── main.py           # FastAPI (порт 8461)
+├── sip_proxy.py      # WebSIP Proxy (SIP ←→ WebSocket)
+├── realtime.py       # Yandex Realtime WebSocket client
+├── script.py         # Управление скриптом (state machine)
+├── memory.py         # Память контекста разговора (Redis)
+└── .env
+```
+
+**Функции:**
+- Приём входящих / исходящие звонки
+- Yandex Realtime API (STT→LLM→TTS в реальном времени)
+- State Machine: приветствие → qualification → предложение → возражения → закрытие
+- Контекстная память (текущий клиент, история, CRM-данные)
+- Запись звонков для последующего анализа
+
+### 3. calls24-ядро (core)
+```
+core/
+├── api.py            # Общий API (REST + WebSocket)
+├── models.py         # Pydantic модели (Call, Script, Pattern)
+├── db.py             # PostgreSQL / Qdrant
+├── scheduler.py      # Расписание звонков, напоминания
+├── billing.py        # Оплата за лид/бронь
+├── integrations.py   # Bitrix24, AmoCRM, 1С
+└── auth.py           # Авторизация клиентов
+```
+
+## Базы данных
+
+### PostgreSQL
+```
+calls (id, customer_id, type, recording_url, status, created_at)
+call_transcripts (call_id, role, text, start_time, end_time)
+call_analysis (call_id, score, script_issues, objections, conversion)
+scripts (id, name, version, state_machine_json, created_at)
+patterns (id, script_id, type, text, win_rate, context)
+customers (id, name, company, industry, phone, created_at)
+leads (id, customer_id, call_id, status, revenue, created_at)
+```
+
+### Qdrant (векторный поиск)
+```
+collection: call_embeddings
+  - call_id: string
+  - embedding: float[768]  (text-embedding-3-large)
+  - payload: {customer_id, type, score, script_issues}
+
+collection: script_patterns
+  - pattern_id: string
+  - embedding: float[768]
+  - payload: {type, text, win_rate, context}
+```
+
+## Поток данных
+
+### Анализ звонка
+```
+Аудиофайл → STT → Текст → LLM-анализ → Паттерны → Отчёт
+   ↓                                           ↓
+ запись в PG                          скрипт для робота
+```
+
+### Звонки робота
+```
+SIP-линия → WebSIP → WebSocket → Yandex Realtime
+                                    ↓
+                            STT → LLM → TTS → Аудио
+                                    ↓
+                          Context Memory (Redis)
+                                    ↓
+                         Запись → Анализ → Улучшение
+```