docs/ARCHITECTURE.md

# Архитектура проекта

## Обзор

SEO AI Editor построен на архитектуре клиент-сервер с использованием FastAPI для backend и простого HTML/JavaScript для frontend.

## Структура проекта

```
seo_ai_editor/
├── main.py              # Точка входа, FastAPI приложение
├── logic.py             # Бизнес-логика и алгоритмы анализа
├── models.py            # Pydantic модели данных
├── requirements.txt     # Python зависимости
├── templates/
│   └── index.html       # Frontend интерфейс
├── docs/                # Документация
│   ├── API.md
│   ├── ARCHITECTURE.md
│   └── DEVELOPMENT.md
└── README.md            # Основная документация
```

## Компоненты системы

### 1. Backend (FastAPI)

#### `main.py` - Веб-сервер

**Ответственность:**
- Инициализация FastAPI приложения
- Роутинг HTTP запросов
- Предзагрузка моделей при старте
- Обработка запросов и формирование ответов

**Ключевые функции:**
- `startup_event()` - загрузка моделей при старте
- `read_root()` - отдача главной страницы
- `analyze_text()` - обработка запроса на анализ

#### `logic.py` - Бизнес-логика

Разделен на три модуля:

##### A. SPACY (Лингвистический анализ)

**Модели:**
- Глобальный словарь `LoadedModels` для кэширования загруженных spaCy моделей
- Поддержка 5 языков: en, ru, de, es, it

**Функции:**
- `load_model_if_missing(lang)` - ленивая загрузка моделей
- `load_models()` - предзагрузка всех моделей
- `get_doc(text, lang)` - получение spaCy документа
- `is_valid_token(t)` - фильтрация токенов (удаление мусора)
- `get_lemmas_flat(text, lang)` - получение списка лемм
- `generate_ngrams_safe(text, lang, n)` - генерация N-грамм с умной фильтрацией

**Особенности:**
- Сохранение стоп-слов внутри фраз для читаемости
- Фильтрация N-грамм, состоящих только из стоп-слов
- Обработка больших текстов (max_length = 2,000,000)

##### B. ANALYTICS (N-граммы и BM25)

**Функции:**
- `calculate_ngram_stats()` - статистика по N-граммам (1-4)
- `parse_keywords()` - парсинг ключевых фраз
- `calculate_bm25_recommendations()` - многоуровневый BM25 анализ

**Алгоритм BM25 (с полной декомпозицией фраз):**
1. **Декомпозиция ключевых фраз**: Для каждой ключевой фразы генерируются все возможные под-н-граммы длиной от 1 до 3 слов
   - Пример: фраза "chicken road casino" разбивается на:
     - Униграммы: "chicken", "road", "casino"
     - Биграммы: "chicken road", "road casino"
     - Триграммы: "chicken road casino"
   - Используется скользящее окно по токенам фразы
   - Дубликаты отслеживаются через set для оптимизации
2. Генерация N-грамм для целевого текста и конкурентов (униграммы, биграммы, триграммы)
3. Обучение BM25 модели на корпусе N-грамм для каждого уровня (1, 2, 3)
4. Расчет BM25 скоров для каждой декомпозированной фразы
5. Сравнение скоров целевого текста со средним скором конкурентов
6. Генерация рекомендаций (add/remove/ok) на основе пороговых значений
7. Сортировка результатов: сначала проблемные (add/remove), затем по длине фразы, затем алфавитно

**Пороги:**
- Униграммы: 0.5
- Биграммы: 0.25
- Триграммы: 0.15

**Особенности:**
- Полная декомпозиция позволяет анализировать не только целые фразы, но и их части
- Это особенно полезно для длинных ключевых фраз, которые могут встречаться в тексте частично
- Автоматическое удаление дубликатов при декомпозиции

##### C. BERT / VECTOR ANALYSIS

**Модель:**
- Глобальная переменная `BertModel` для кэширования
- Модель: `paraphrase-multilingual-MiniLM-L12-v2`
- Автоматическое определение устройства (CPU/GPU)

**Функции:**
- `get_bert_model()` - загрузка BERT модели
- `perform_bert_analysis()` - семантический анализ

**Алгоритм BERT анализа:**
1. Разбиение текстов на предложения (chunks)
2. Генерация эмбеддингов для всех chunks и ключевых фраз
3. Расчет косинусного сходства между ключевыми фразами и chunks
4. Global Score: средний максимальный score по всем ключам
5. Detailed Analysis: топ-5 наиболее релевантных chunks для каждой фразы

#### `models.py` - Модели данных

**Pydantic модели:**
- `AnalysisRequest` - входные данные для анализа
- `AnalysisResponse` - структура ответа API

### 2. Frontend

#### `templates/index.html`

**Технологии:**
- Bootstrap 5 для UI
- Vanilla JavaScript (без фреймворков)
- AJAX для взаимодействия с API

**Компоненты:**
- Форма ввода данных
- Табы для отображения результатов
- Динамическое добавление полей конкурентов
- Визуализация результатов анализа

## Поток данных

```
1. Пользователь вводит данные в форму
   ↓
2. JavaScript собирает данные и отправляет POST /analyze
   ↓
3. FastAPI получает запрос, валидирует через Pydantic
   ↓
4. main.py вызывает функции из logic.py:
   - calculate_ngram_stats()
   - parse_keywords()
   - calculate_bm25_recommendations()
   - perform_bert_analysis()
   ↓
5. Каждая функция использует:
   - spaCy для лингвистики
   - BM25 для частотного анализа
   - BERT для семантики
   ↓
6. Результаты собираются в AnalysisResponse
   ↓
7. JSON ответ отправляется клиенту
   ↓
8. JavaScript рендерит результаты в UI
```

## Управление состоянием

### Backend

**Глобальные переменные:**
- `LoadedModels` - кэш загруженных spaCy моделей
- `BertModel` - кэш BERT модели

**Стратегия:**
- Модели загружаются один раз при первом использовании
- Предзагрузка spaCy моделей при старте (опционально)
- BERT модель загружается лениво при первом запросе

### Frontend

**Состояние:**
- `currentData` - последние результаты анализа
- DOM состояние для табов и форм

## Производительность

### Оптимизации

1. **Кэширование моделей:**
   - spaCy модели загружаются один раз
   - BERT модель загружается один раз

2. **Ленивая загрузка:**
   - spaCy модели загружаются только для используемых языков
   - BERT модель загружается при первом запросе

3. **GPU ускорение:**
   - Автоматическое использование CUDA для BERT
   - Значительное ускорение на GPU

4. **Ограничения:**
   - N-граммы ограничены 150 элементами на тип
   - Топ-5 chunks для BERT анализа

### Ограничения

- Максимальная длина текста для spaCy: 2,000,000 символов
- Память: зависит от размера моделей и длины текстов
- Время обработки: зависит от длины текстов и наличия GPU

## Масштабируемость

### Текущие ограничения

- Однопоточная обработка запросов
- Модели загружаются в память
- Нет кэширования результатов

### Возможные улучшения

1. **Асинхронность:**
   - Использование async/await для I/O операций
   - Параллельная обработка конкурентов

2. **Кэширование:**
   - Redis для кэширования результатов
   - Кэширование эмбеддингов

3. **Микросервисы:**
   - Отдельный сервис для BERT
   - Отдельный сервис для spaCy

4. **База данных:**
   - Сохранение истории анализов
   - Статистика использования

## Безопасность

### Текущее состояние

- Нет аутентификации
- Нет ограничений на размер запросов
- Нет валидации входных данных (кроме Pydantic)

### Рекомендации

1. **Валидация:**
   - Ограничение размера текстов
   - Санитизация входных данных

2. **Аутентификация:**
   - API ключи
   - OAuth 2.0

3. **Rate Limiting:**
   - Ограничение количества запросов
   - Защита от DDoS

## Зависимости

### Критические

- `fastapi` - веб-фреймворк
- `spacy` - NLP библиотека
- `sentence-transformers` - BERT модели
- `rank-bm25` - BM25 алгоритм
- `torch` - глубокое обучение

### Вспомогательные

- `uvicorn` - ASGI сервер
- `pydantic` - валидация данных
- `jinja2` - шаблонизация
- `numpy` - численные вычисления

## Расширяемость

### Добавление нового языка

1. Установить spaCy модель для языка
2. Добавить в `MODEL_NAMES` в `logic.py`
3. Добавить опцию в UI (`templates/index.html`)

### Добавление новой модели BERT

1. Изменить модель в `get_bert_model()`
2. Убедиться в совместимости с `sentence-transformers`

### Добавление нового типа анализа

1. Создать функцию в `logic.py`
2. Добавить вызов в `analyze_text()` в `main.py`
3. Добавить поле в `AnalysisResponse`
4. Обновить UI для отображения результатов