# Архитектура аналога Perplexity.ai — полная спецификация

Документ описывает полную архитектуру системы на базе микросервисов K3s с акцентом на:
- **ВСЕ сервисы в `services/`.** Папка `apps/` удаляется. Микросервисная архитектура: chat, search, discover, finance, travel, auth, library, memory, create, notifications, projects, web (UI), cache-worker.
- **~10 000 DAU** (ежедневных пользователей)
- **Клиентская логика** — максимум на клиенте; персональные данные — только для аккаунтов
- **Предварительная обработка и кэш** — новости, finance, travel, повторяющиеся запросы
- **Полное совпадение** с Perplexity.ai по страницам и логике

---

## 1. Карта страниц (URL-структура, 1:1 Perplexity)

| URL | Страница | Описание |
|-----|----------|----------|
| `/` | Home | Поисковая строка + виджеты discover/новости |
| `/search`, `/search/new?q=` | Search | Поисковый чат (Quick/Pro/Deep) |
| `/c/[threadId]` | Chat/Thread | Окно конкретного чата/треда |
| `/finance` | Finance | Рынок, heatmap, вкладки |
| `/finance/[ticker]` | Ticker Detail | Детальная страница акции/индекса |
| `/finance/predictions/[id]` | Predictions | Polymarket prediction markets |
| `/travel` | Travel | Trending, Inspiration Cards, отели, маршруты |
| `/discover` | Discover | Новости по темам (или часть Home) |
| `/library` | Library | История поисков, сохранённые треды |
| `/spaces` | Spaces | Список проектов/пространств |
| `/spaces/templates` | Space Templates | Шаблоны Spaces |
| `/collections/[id]` | Collections | Публичные коллекции (read-only Space) |
| `/patents` | Patents | Поиск и анализ патентов |
| Profile/Settings | Account | Профиль, Preferences, Personalize, Billing, My Connectors |
| — | Desktop app | Electron/Tauri (pplx.ai-аналог) |
| — | iOS / Android | Нативные приложения, voice search |
| — | Chrome extension | Расширение для браузера |

---

## 2. Карта функциональностей

### 2.1 Сводная матрица

| Категория | Функционал | Клиент | Сервер (обязательно) | Кэш/Фоново |
|-----------|------------|--------|----------------------|------------|
| **Поиск** | Quick Search | ✅ UI, локальное состояние | LLM, Researcher | ✅ Кэш по query_hash |
| **Поиск** | Pro Search | ✅ UI, стриминг | LLM, Mastra workflow | ✅ Кэш по query_hash |
| **Поиск** | Deep Research | ✅ UI, прогресс | LLM, Mastra | ✅ Кэш по query_hash |
| **Discover** | Новости по темам | ✅ Рендер | Агрегация | ✅ **Pre-compute + Redis** |
| **Finance** | Рынок, heatmap, watchlist | ✅ Рендер, watchlist в LS | Агрегация данных | ✅ **Pre-compute + Redis** |
| **Travel** | Маршруты, отели | ✅ UI stepper | Агрегация, LLM | ✅ **Pre-compute популярных** |
| **Проекты** | Spaces, файлы | ✅ CRUD UI | Хранение файлов, эмбеддинги | — |
| **Чат** | Сообщения, история | ✅ localStorage / IndexedDB | Только LLM, без хранения | Опционально: user preference |
| **Медиа** | Images, Videos | ✅ Рендер | SearXNG proxy | ✅ Кэш по query |
| **Виджеты** | Погода, акции, калькулятор | ✅ Калькулятор на клиенте | API-прокси | ✅ Погода/акции по ключу |
| **Профиль** | Account, prefs | ✅ Preferences в LS | Auth только (SSO) | — |
| **Биллинг** | Тарифы, оплата | ✅ UI | ЮKassa, лимиты | — |
| **Collections** | Публичные шаблоны | ✅ Рендер | projects-svc | Redis/PostgreSQL |
| **Library** | История, сохранённое | ✅ UI | library-svc (аккаунты) | PostgreSQL |
| **Memory** | Персональная память AI | ✅ UI | memory-svc | PostgreSQL + Redis |
| **Create/Labs** | Дашборды, отчёты, экспорт | ✅ UI | chat-svc + create-svc | — |
| **Patents** | Поиск патентов | ✅ Рендер | search-svc + patents API | Redis |
| **Export thread** | Экспорт тредов в PDF/MD | ✅ UI | create-svc / library-svc | — |
| **Notifications** | Push, email, напоминания | ✅ Клиент + SW | notifications-svc | — |
| **PWA/Офлайн** | Service worker, установка | ✅ SPA | Static + SW | — |
| **Model Council** | 3 модели параллельно, синтез | ✅ UI (Max) | chat-svc | — |
| **Background Assistant** | Фоновые задачи (Max) | ✅ Desktop/Mobile | chat-svc + queue | — |

### 2.2 Детальное описание функциональностей

#### A. Поисковый чат (Core)
| Функция | Описание |
|---------|----------|
| Quick Search | 1 запрос, базовые модели, без хранения истории |
| Pro Search | Многошаговый поиск, Mastra workflow, параллельные actions |
| Deep Research | Расширенный анализ, отчёт, визуализация этапов |
| **Answer Modes** | Standard, Focus, Academic, Writing + вертикали (Travel, Finance) |
| **Travel Mode** | Отдельный системный промпт, фокус на отели/маршруты/бронирование |
| Классификация | Classifier → skipSearch, sources, widgets |
| Actions | webSearch, academicSearch, socialSearch, scrapeURL, uploadsSearch (параллельно) |
| Writer | Финальный ответ с цитированием источников |
| **Step-by-step Learning** | Режим обучения: подсказки, guided questions, уровень сложности |
| **Response preferences** | Настройки формата/стиля ответов (Preferences) |
| **Input bar «+»** | Меню: файлы, источники, режимы (Quick/Pro/Deep/Create/Learn) |
| **Model Council** | Запуск 3 моделей параллельно → сравнение → синтез ответа (Max) |

#### B. Discover (Новости)
| Функция | Описание |
|---------|----------|
| Агрегация новостей | По темам: tech, finance, travel, world, science |
| Суммаризация | LLM-сводка каждой новости/блока |
| Обновление | Фоновая задача каждые 15–30 мин |
| Кэш | Redis: `discover:{topic}:{date}` TTL 30 мин |

#### C. Finance
| Функция | Описание |
|---------|----------|
| Market Summary | Индексы, futures, VIX |
| Heatmap S&P 500 | Сектора, gainers/losers |
| **Вкладки** | Crypto, Earnings, Predictions, Screener, Politicians Watchlist, Watchlist |
| Recent Developments | Новости с суммаризацией и таймстампами |
| **Popular Spaces for Finance Research** | Блок коллекций по категории finance (SEC, Buffett, S&P Transcripts) |
| Standouts | Выделенные акции с кратким LLM-анализом |
| Watchlist | Клиент: localStorage; сервер: агрегация данных по тикерам |
| **Analyst ratings** | Рейтинги аналитиков по акциям (FMP, Benzinga и т.п.) |
| **Auditable financials** | Ссылки на SEC filings в ответах и на странице тикера |
| **ETF Holdings** | Детали холдингов ETF на странице тикера |
| **Heatmap hover** | Live-синтез причины движения цены при наведении (LLM on demand) |
| **Stock graphs** | Графики в ответах чата (мобильный/desktop) |
| Кэш | Redis: `finance:summary`, `finance:heatmap`, `finance:news:{ticker}` TTL 2–5 мин |

#### D. Travel
| Функция | Описание |
|---------|----------|
| Trending Destinations | Карточки с изображениями (pre-compute) |
| **Inspiration Cards** | Курируемые статьи («Лучшие тропы в Словении», «Лесные отели в Швеции») |
| Поиск мест, маршруты | Генерация itineraries (LLM) |
| Отели | Tripadvisor (рейтинги, отзывы, ссылки) |
| **Партнёрское бронирование** | Tripadvisor, Selfbook (прямое бронирование) |
| Stepper UI | Поиск → Места → Маршрут → Отели → Билеты |
| Answer Mode: Travel | Вертикаль чата с фокусом на путешествия |
| Кэш | Redis: `travel:trending`, `travel:inspiration`, `travel:itinerary:{hash}` TTL 1–24 ч |

#### E. Collections (публичные)
| Функция | Описание |
|---------|----------|
| Collections | Публичные read-only Spaces с предзагруженным контекстом |
| Категории | finance, travel, product, research — для Popular Spaces |
| Примеры | SEC Findings, Buffett letters, S&P 500 Transcripts |
| API | `GET /collections?category=finance`, `GET /collections/:id` |

#### F. Проекты (Spaces)
| Функция | Описание |
|---------|----------|
| CRUD проектов | Создание, переименование, архивация |
| Файлы в проекте | Загрузка, парсинг, эмбеддинги |
| Чаты в проекте | Контекст проекта во всех чатах |
| Internal Knowledge Search | Поиск по файлам + веб |
| Space Templates | Шаблоны под финансы, маркетинг, продукт, travel |

#### G. Library
| Функция | Описание |
|---------|----------|
| История поисков | Список тредов для авторизованного пользователя |
| Сохранённое | Saved threads, закладки |
| **Гости** | Только localStorage/IndexedDB, при закрытии — потеря |
| **Аккаунты** | Синхронизация на сервере (library-svc, PostgreSQL) |

#### H. Медиа
| Функция | Описание |
|---------|----------|
| Search Images | SearXNG, LLM формирует query |
| Search Videos | SearXNG, LLM формирует query |
| Кэш | Redis: `media:images:{query_hash}`, `media:videos:{query_hash}` TTL 1 ч |

#### I. Виджеты
| Функция | Описание |
|---------|----------|
| Weather | API (Open-Meteo и т.п.) |
| Stock | Yahoo Finance / Financial Modeling Prep |
| Calculation | **Полностью на клиенте** (mathjs и т.п.) |
| Кэш | Погода/акции: Redis по location/ticker TTL 5–15 мин |

#### J. Профиль и Connectors
| Функция | Описание |
|---------|----------|
| Account | Аватар, имя, email (только просмотр) |
| Preferences | Appearance, Language, Autosuggest, Homepage widgets, **Response preferences** |
| Personalize | Watchlists, настройки персонализации |
| Billing | Подписка, история платежей |
| **My Connectors** | Интеграции (Google Drive, Dropbox и т.п.) — Pro/общие пользователи |
| **App Connectors** | Enterprise: SharePoint, OneDrive, Box — автосинхронизация файлов в Space |

#### K. Memory (персональная память AI)
| Функция | Описание |
|---------|----------|
| Хранение | memory-svc, PostgreSQL (user_id, key, value, embedding) |
| Извлечение | Семантический поиск по памяти при каждом запросе (если Pro/Max) |
| Формат | Факты, предпочтения, контекст из прошлых тредов |
| UI | Просмотр/удаление памяти в Profile → Personalize |
| Enterprise Memory | Организационная память (org_id), доступна всем участникам |

#### L. Create / Labs
| Функция | Описание |
|---------|----------|
| Генерация | Таблицы, отчёты, дашборды по запросу (Pro) |
| Экспорт | .xlsx, .csv, .md, .pdf из ответов |
| Image generation | Генерация изображений (Pro, DALL·E/Stable Diffusion) |
| API | `POST /api/v1/create` — тип (table/dashboard/image), prompt |

#### M. Patents
| Функция | Описание |
|---------|----------|
| Страница | `/patents` — поиск по USPTO, EPO, патентам РФ |
| Интеграция | patents API или Google Patents; LLM-суммаризация |
| Кэш | Redis `patents:{query_hash}` TTL 1 ч |

#### N. Enterprise
| Функция | Описание |
|---------|----------|
| **Audit logs** | Логи: query, answer, model, sources, user_id, timestamp (compliance) |
| **Granular feature access** | Доступ к API, список Spaces, модели по ролям админа |
| **Domain-based sign-up** | Ограничение регистрации по верифицированным доменам email |
| **Usage guidelines** | Guidelines организации на homepage для членов |
| **Enterprise Memory** | Общая память на уровень org |

#### O. Клиентские приложения
| Платформа | Описание |
|----------|----------|
| **Desktop** | Electron или Tauri, единый код с web |
| **iOS / Android** | React Native или Capacitor; **voice search** (Web Speech API / native) |
| **Chrome extension** | Всплывающее окно, быстрый поиск со страницы |
| **PWA / Офлайн** | Service worker кэширует статику (JS, CSS, assets); workbox; установка на домашний экран; офлайн-fallback |

#### O.1 Export thread
| Функция | Описание |
|---------|----------|
| API | `POST /api/v1/library/threads/:id/export` или `POST /api/v1/export` с `contentType: 'thread'` |
| Форматы | PDF, Markdown |
| Реализация | create-svc или library-svc; рендер треда → PDF (puppeteer/jsPDF) или MD (template) |
| UI | Кнопка Export в окне чата/треда |

#### O.2 Notifications
| Функция | Описание |
|---------|----------|
| **Push** | Web Push API (VAPID); уведомление при готовности ответа (Pro/Deep); настройки в Preferences |
| **Email** | Опция «уведомить по email при завершении» для долгих запросов (Deep Research) |
| **Напоминания** | «Напомнить через N» — отложенная задача, push/email по расписанию |
| **Сервис** | notifications-svc; очереди (Redis/Bull) или вызов от chat-svc по событию |

#### O.3 Model Council (Max)
| Функция | Описание |
|---------|----------|
| Логика | Запрос → параллельный запуск 3 выбранных моделей (GPT-4, Claude, и др.) |
| Синтез | Отдельный LLM-вызов для сравнения и сведения в единый ответ |
| UI | Выбор моделей в input bar; side-by-side или сводный вид |
| API | `POST /api/v1/chat` с `modelCouncil: true`, `models: ['gpt-4','claude','...']` |

#### O.4 Background Assistant (Max)
| Функция | Описание |
|---------|----------|
| Назначение | Выполнение задач в фоне (Desktop/Mobile app), когда приложение свёрнуто |
| Архитектура | Queue (Redis/Bull); worker подхватывает задачи; push при готовности |
| Сценарии | «Найди отели в Париже» → фон → уведомление с результатом |
| API | `POST /api/v1/tasks` (создать фоновую задачу); polling или WebSocket/SSE для статуса |

#### P. Образование
| Функция | Описание |
|---------|----------|
| **Step-by-step Learning** | Режим в input bar «+»; ответы с подсказками, guided questions |
| **Quizzes / Flashcards** | Генерация тестов и карточек по теме (Pro/Education) |
| **Education Pro** | Тариф со скидкой для студентов/преподавателей (верификация) |

---

## 3. Микросервисы K3s

### 3.1 Карта сервисов

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT (SPA / PWA)                                  │
│  Next.js (SSR для статики) / React SPA — максимум логики, localStorage, IndexedDB │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    │                   │                   │
                    ▼                   ▼                   ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│   API Gateway         │ │   Auth Service         │ │   Web (CDN/Static)    │
│   (Kong / Traefik)    │ │   (Keycloak/Supabase)  │ │   S3/MinIO + CDN      │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                         BACKEND MICROSERVICES (K3s)                               │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │ chat-svc    │  │ search-svc  │  │ discover-svc│  │ finance-svc │            │
│  │ LLM, Mastra │  │ SearXNG,    │  │ News feed   │  │ Market data │            │
│  │ Writer      │  │ Scraper     │  │ Summari-zer│  │ Heatmap     │            │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │
│                                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │ travel-svc  │  │ media-svc   │  │ projects-svc│ │ cache-worker│            │
│  │ Itineraries │  │ Images/Videos│ │ Files,      │  │ Pre-compute │            │
│  │ Tripadvisor │  │ SearXNG     │  │ Embeddings  │  │ Background  │            │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │
│                                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │ billing-svc │  │ upload-svc  │  │ library-svc │  │ memory-svc   │            │
│  │ ЮKassa      │  │ File parse  │  │ Threads,     │  │ AI Memory,   │            │
│  │ Subscriptions│ │ Embeddings  │  │ History      │  │ Enterprise  │            │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  # Create, Audit, Notifications   │
│  │ create-svc  │  │ audit-svc   │  │notifications│                                    │
│  │ Tables,     │  │ Query+Answer│  │ Push, Email │                                    │
│  │ Dashboards  │  │ logging     │  │ Reminders   │                                    │
│  └─────────────┘  └─────────────┘  └─────────────┘                                    │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                         ИНФРАСТРУКТУРА                                           │
│  Redis (кэш + сессии) │ PostgreSQL (billing, projects) │ MinIO (файлы)          │
│  SearXNG (self-hosted) │ LLM Provider (OpenAI/Ollama)   │ Vector DB (optional)   │
└─────────────────────────────────────────────────────────────────────────────────┘
```

### 3.2 Описание микросервисов

| Сервис | Язык | Replicas (10k DAU) | Назначение |
|--------|------|--------------------|------------|
| **api-gateway** | — (Kong/Traefik) | 2 | Роутинг, rate limit, JWT validation |
| **auth-svc** | Node/Go | 2 | SSO (Google, Apple, Email magic link), JWT |
| **chat-svc** | Node.js | 3–5 | LLM, Mastra workflow, Writer, streaming |
| **search-svc** | Node.js | 3 | SearXNG, scrape, Researcher actions |
| **discover-svc** | Node.js | 2 | Агрегация новостей, суммаризация (фоново) |
| **finance-svc** | Node.js | 2 | Market data, heatmap, news по тикерам |
| **travel-svc** | Node.js | 2 | Itineraries, Tripadvisor, trending |
| **media-svc** | Node.js | 2 | Images/Videos через SearXNG |
| **projects-svc** | Node.js | 2 | CRUD проектов, файлы, эмбеддинги, **Collections** |
| **billing-svc** | Node.js | 1 | ЮKassa, subscriptions, лимиты |
| **upload-svc** | Node.js | 2 | Парсинг PDF/DOCX, embedding, chunking |
| **library-svc** | Node.js | 2 | История тредов, сохранённое для аккаунтов |
| **memory-svc** | Node.js | 2 | Персональная память AI, Enterprise Memory, векторный поиск |
| **create-svc** | Node.js | 1–2 | Create (таблицы, дашборды), экспорт, image generation |
| **audit-svc** | Node.js | 1 | Audit logs для Enterprise (query, answer, model, user) |
| **notifications-svc** | Node.js | 1–2 | Web Push, Email, напоминания; очереди задач |
| **cache-worker** | Node.js | 1–2 | Cron: pre-compute discover, finance, travel inspiration |

### 3.3 K3s манифесты (базовая структура)

```yaml
# namespaces
perplexica-prod
perplexica-cache

# Deployments с HPA
chat-svc:     min 2, max 8, CPU 70%
search-svc:   min 2, max 6
discover-svc: min 1, max 4
finance-svc:  min 1, max 4
travel-svc:   min 1, max 3
media-svc:    min 1, max 4
projects-svc: min 1, max 4 (включая Collections)
upload-svc:   min 1, max 4
library-svc:  min 1, max 3
memory-svc:   min 1, max 3
create-svc:   min 1, max 2
audit-svc:    min 1, max 1
notifications-svc: min 1, max 2
billing-svc:  min 1, max 2
cache-worker: min 1, max 1 (CronJob)
auth-svc:     min 2, max 4
```

---

## 3. Стратегия кэширования и предобработки

### 3.1 Ключевой принцип

> **Не суммировать и не обрабатывать по запросу то, что можно сделать заранее и переиспользовать.**

### 3.2 Кэш-слои

| Слой | Что кэширует | Ключ | TTL | Источник |
|------|--------------|------|-----|----------|
| **Discover** | Новости по теме + суммаризация | `discover:{topic}` | 30 мин | cache-worker каждые 15 мин |
| **Finance** | Market summary, heatmap | `finance:summary`, `finance:heatmap` | 5 мин | cache-worker каждые 2 мин |
| **Finance** | News по тикеру | `finance:news:{ticker}` | 15 мин | cache-worker при обновлении |
| **Travel** | Trending destinations | `travel:trending` | 6 ч | cache-worker каждые 4 ч |
| **Travel** | Inspiration Cards | `travel:inspiration` | 6 ч | cache-worker каждые 4 ч |
| **Travel** | Популярные маршруты | `travel:itinerary:{hash}` | 24 ч | On first request, reuse |
| **Search** | Идентичные запросы | `search:{query_hash}:{mode}` | 1–24 ч | On first request |
| **Media** | Images/Videos query | `media:{type}:{query_hash}` | 1 ч | On first request |
| **Widgets** | Погода, акции | `widget:{type}:{key}` | 5–15 мин | On first request |

### 3.4 Cache-worker (фоновые задачи)

```
Cron расписание:
├── */2 * * * *   finance:summary, finance:heatmap
├── */15 * * * *  discover:{topic} для всех тем
├── 0 */4 * * *   travel:trending, travel:inspiration (Inspiration Cards)
└── 0 * * * *     Инвалидация устаревших search cache
```

### 3.5 Логика поискового кэша

1. Входящий запрос → `query_hash = sha256(normalize(query) + mode + sources)`
2. Проверка Redis: `GET search:{query_hash}`
3. Если есть → отдать из кэша (без LLM)
4. Если нет → выполнить полноценный flow, сохранить в кэш
5. Популярные запросы (частота > N/день) → приоритет в cache-worker для pre-warm

---

## 4. Клиентская архитектура (без хранения данных)

### 4.1 Что на клиенте (включая My Connectors UI)

| Компонент | Реализация |
|-----------|------------|
| UI/UX | React, Next.js (SSR только для статики) |
| Состояние чата | Zustand/Context — в памяти, при refresh теряется (или опционально IndexedDB) |
| Preferences | localStorage: theme, language, units |
| Watchlist (finance) | localStorage |
| Калькулятор | Полностью локально (mathjs) |
| Роутинг | Client-side |
| **PWA / Офлайн** | Service worker (Workbox): кэш static (JS, CSS, assets); offline fallback; manifest для установки |

### 4.2 Что храним / не храним

**Не храним на сервере (гости):**
- История чатов — только в памяти/IndexedDB клиента
- Preferences — только в localStorage

**Храним для аккаунтов:**
- История тредов, сохранённое — library-svc (PostgreSQL)
- Projects, файлы, подписка — projects-svc, billing-svc
- Кэш поиска — обезличенный по query_hash, без user_id

### 4.3 Режимы пользователя

| Режим | Данные | Описание |
|-------|--------|----------|
| **Гость** | Всё на клиенте | Чат в памяти, при закрытии — потеря |
| **Аккаунт** | Auth + billing | Проекты, подписка — в БД; чаты опционально |

### 4.4 UI/UX требования

| Область | Требование |
|---------|------------|
| **Discover, Finance, Travel** | Skeleton/placeholder при cold start; timeout с сообщением; кнопка повтора при ошибке |
| **Поиск (Pro/Deep)** | Отображение этапов (Classifier → Researcher → Writer); оценка времени ожидания |
| **Загрузка файлов** | Прогресс по этапам: парсинг → chunking → эмбеддинги; индикация; кнопка Cancel; timeout 300 с |
| **Гости** | Предупреждение при закрытии: история теряется без аккаунта; CTA «Сохранить в аккаунт» |
| **Rate limit** | Сообщение при 429; предупреждение при 80% лимита; предложение апгрейда при достижении |
| **Ошибки** | Сообщение + Retry/Cancel; fallback при частичном сбое (например, виджет не загрузился) |
| **Travel Stepper** | Сохранение состояния шагов при уходе; скелетон между шагами |
| **Мобильный** | Адаптивность heatmap, Discover; жесты; SettingsButtonMobile |

---

## 5. API контракты (основные)

### 5.1 Chat/Search

```
POST /api/v1/chat
  Body: { query, mode?, sources?, fileIds?, answerMode?, learningMode?, responsePrefs? }
  answerMode: 'standard' | 'focus' | 'academic' | 'writing' | 'travel' | 'finance'
  learningMode: boolean  # Step-by-step Learning
  responsePrefs: { format?, length?, tone? }  # из Preferences
  Response: SSE stream
  Cache: Проверка query_hash до вызова LLM

POST /api/v1/search/cached
  Query: ?q=...&mode=...
  Response: JSON (если есть в кэше) или 404 → fallback на /chat
```

### 5.2 Discover

```
GET /api/v1/discover?topic=tech|finance|travel|...
  Response: { items: [{ title, summary, source, url }] }
  Source: Redis, refresh от cache-worker
```

### 5.3 Finance

```
GET /api/v1/finance/summary
GET /api/v1/finance/heatmap
GET /api/v1/finance/news/:ticker
GET /api/v1/finance/watchlist?tickers=AAPL,GOOG
GET /api/v1/finance/analyst-ratings/:ticker   # Analyst ratings
GET /api/v1/finance/sec-filings/:ticker       # Ссылки на SEC filings
GET /api/v1/finance/etf-holdings/:symbol       # ETF Holdings
GET /api/v1/finance/price-context/:ticker     # Heatmap hover: LLM-синтез причины движения
  Response: JSON из Redis / live
```

### 5.4 Travel

```
GET /api/v1/travel/trending
GET /api/v1/travel/inspiration     # Inspiration Cards (pre-compute)
POST /api/v1/travel/itinerary
  Body: { destination, days, preferences }
  Cache: По hash параметров
```

### 5.5 Collections

```
GET /api/v1/collections?category=finance|travel|product|research
GET /api/v1/collections/:id
  Response: Публичный Space с контекстом (read-only)
```

### 5.6 Library

```
GET /api/v1/library/threads        # Для авторизованных
POST /api/v1/library/threads      # Сохранить тред
DELETE /api/v1/library/threads/:id
```

### 5.7 Auth

```
POST /auth/login/email
GET  /auth/oauth/{provider}
POST /auth/refresh
GET  /auth/me
```

### 5.8 Connectors

```
GET /api/v1/connectors            # Список доступных (Pro)
POST /api/v1/connectors/:type    # Подключить (Google Drive, Dropbox)
DELETE /api/v1/connectors/:id    # Отключить
```

### 5.9 Memory

```
GET  /api/v1/memory               # Список записей памяти (Pro/Max)
POST /api/v1/memory              # Добавить запись (внутренний вызов от chat-svc)
DELETE /api/v1/memory/:id        # Удалить запись
```

### 5.10 Create / Labs

```
POST /api/v1/create
  Body: { type: 'table' | 'dashboard' | 'image', prompt, context? }
  Response: { url?, data?, imageUrl? }
  
POST /api/v1/export
  Body: { format: 'xlsx' | 'csv' | 'md' | 'pdf', contentId?, contentType?: 'create' | 'thread' }
  Body (thread): { format: 'pdf' | 'md', threadId }
  Response: blob / download URL
```

### 5.10.1 Export thread

```
POST /api/v1/library/threads/:id/export
  Query: ?format=pdf|md
  Response: blob (application/pdf или text/markdown)
  Реализация: create-svc или library-svc + puppeteer/jsPDF для PDF
```

### 5.11 Patents

```
GET /api/v1/patents?q=...
  Response: { patents: [{ title, abstract, filingDate, url, summary }] }
  Source: Google Patents / USPTO API; LLM-суммаризация; Redis кэш
```

### 5.12 Enterprise Audit

```
GET /api/v1/admin/audit-logs?from=&to=&userId=
  Response: [{ query, answerSnippet, model, sources, userId, timestamp }]
  Только для org admin
```

### 5.13 Notifications

```
POST /api/v1/notifications/subscribe     # Web Push подписка (VAPID)
  Body: { endpoint, keys: { p256dh, auth } }
  
POST /api/v1/notifications/preferences  # Настройки: push при ответе, email, напоминания
  Body: { pushOnAnswer?, emailOnDeepResearch?, reminders?: [...] }
  
POST /api/v1/notifications/remind       # «Напомнить через N»
  Body: { threadId?, query?, remindAt: ISO8601 }
```

### 5.14 Model Council (Max)

```
POST /api/v1/chat
  Body: { ..., modelCouncil: true, models: ['gpt-4o','claude-sonnet','...'] }
  Response: SSE с этапами: 3 ответа → синтез
```

### 5.15 Background Assistant (Max)

```
POST /api/v1/tasks                    # Создать фоновую задачу
  Body: { query, mode?, callback?: 'push' | 'poll' }
  Response: { taskId }
  
GET /api/v1/tasks/:id                 # Статус задачи
  Response: { status, result?, error? }
```

---

## 6. Порядок реализации (best practices)

### Фаза 0 — Инфраструктура
1. K3s кластер, PostgreSQL, Redis, MinIO
2. API Gateway (Traefik/Kong)
3. Auth-svc (Keycloak или Supabase Auth)

### Фаза 1 — Ядро
4. chat-svc с Mastra (Classifier → parallel actions → Writer)
5. search-svc (SearXNG, actions)
6. cache-worker + Redis стратегия
7. Кэш для search по query_hash

### Фаза 2 — Discover + Finance
8. discover-svc + cache-worker pre-compute
9. finance-svc + cache-worker
10. Клиент: Discover, Finance страницы

### Фаза 3 — Travel
11. travel-svc, Tripadvisor, Selfbook
12. Inspiration Cards (cache-worker), Stepper UI
13. Answer Mode: Travel

### Фаза 4 — Проекты, Collections, Library, биллинг
14. projects-svc, upload-svc, **Collections** (Popular Spaces по категориям)
15. library-svc (история для аккаунтов)
16. billing-svc, ЮKassa
17. Клиент: Spaces UI, Library, Profile, Billing, My Connectors

### Фаза 5 — Memory, Create, Finance+, Patents, Enterprise
18. memory-svc (персональная память, Enterprise Memory)
19. create-svc (таблицы, дашборды, экспорт, image generation)
20. finance-svc: Analyst ratings, SEC links, ETF Holdings, heatmap hover, stock graphs
21. Patents page: search-svc + patents API, `/patents`
22. audit-svc (Enterprise audit logs)
23. Enterprise: domain sign-up, usage guidelines, granular feature access
24. Step-by-step Learning, Response preferences, Input bar «+»

### Фаза 6 — Клиенты и образование
25. Desktop app (Electron/Tauri)
26. iOS / Android (React Native/Capacitor), voice search
27. Chrome extension
28. Step-by-step Learning UI, Quizzes/Flashcards
29. Education Pro тариф

### Фаза 7 — Export, Notifications, PWA, Model Council, Background
30. Export thread: POST /library/threads/:id/export (PDF, MD)
31. PWA: Service worker (Workbox), manifest, offline fallback
32. notifications-svc: Web Push (VAPID), email, напоминания
33. Model Council (Max): параллельный запуск 3 моделей, синтез
34. Background Assistant (Max): POST /tasks, queue, push при готовности

### Фаза 8 — Оптимизация
35. Pre-warm популярных запросов в cache-worker
36. CDN для статики
37. Мониторинг, алерты, SLO

---

## 7. Латенси по сценариям (пользователь)

| Сценарий | Ожидаемое время | Cold / промах кэша |
|----------|-----------------|--------------------|
| Discover / Finance (кэш) | <500 ms | 5–30 с |
| Finance редкий тикер | 10–20 с (cold fill) | — |
| Travel itinerary | 15–60 с | — |
| Pro/Deep Search | 30–120 с | — |
| Загрузка файла (эмбеддинги) | 30–300 с | — |
| Медиа (Images/Videos) | 3–10 с | — |

## 8. Оценка нагрузки (10k DAU)

| Метрика | Оценка | Решение |
|---------|--------|---------|
| RPS пиковый | ~50–100 | HPA, 3–5 реплик chat-svc |
| LLM вызовов/день | ~30k (3 на юзера) | Кэш снижает до ~10k |
| Redis memory | ~4–8 GB | Кэш discover/finance/search |
| Storage | ~100 GB | Файлы проектов, логи |

---

## 9. Безопасность и compliance

- HTTPS везде
- JWT с коротким TTL (15 мин), refresh token
- Rate limiting: 100 req/min на IP, 300 Pro Search/день (Free)
- Не логировать персональные запросы в plaintext
- Кэш — только по hash, без привязки к user_id