# Documentation Index

Полная документация проекта VidConf. Начните с нужного вам раздела.

## Быстрый старт

- **[README проекта](../README.md)** — обзор VidConf, стек, структура монорепо
- **[Design System](../design/DESIGN_SYSTEM.md)** — цветовые токены, типографика, компоненты, мокапы
- **[Dev Setup](deploy/dev-setup.md)** — локальная разработка (Docker, миграции, тесты)
- **[API Reference](api/README.md)** — HTTP endpoints, примеры запросов

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

- **[Architecture Overview](architecture/README.md)** — система компонентов, data flow, design decisions
- **[Database Schema](db/schema.md)** — ER-диаграмма, описание 14 таблиц, ключевые решения
- **[Plugin Contracts](plugins/contracts.md)** — как работают плагины AI (Transcriber/Summarizer), как добавить свой
- **[Пресеты инсталлятора & профили оборудования](deploy/hardware-profiles.md)** — 5 вариантов, автодетект железа, требования ресурсов

## Разработка

- **[Backend README](../backend/README.md)** — FastAPI, модели, миграции, тесты, плагины
- **[Frontend README](../frontend/README.md)** — React SPA, компоненты, стайлинг
- **[Workers README](../workers/README.md)** — Celery, транскрибация, суммаризация, уведомления

## ADR (Architectural Decision Records)

- **[000-template.md](architecture/adr/000-template.md)** — стандартный шаблон ADR для проекта
- Направление: добавлять ADR для крупных архитектурных решений

## По темам

### Интерфейс комнаты конференции
- Настройки устройств (микрофон, камера, персист в localStorage) — [Conference Room UI](architecture/conference-room-ui.md)
- Аватары участников (или инициалы при отсутствии)
- Fullscreen API (кнопка)
- Document Picture-in-Picture для сетки (Chrome/Edge 116+)
- Video Picture-in-Picture для спикера (Safari/Firefox фолбэк)
- Демонстрация экрана/окна/вкладки (любой участник, focus-раскладка, last-wins)
- LiveKit-метаданные с avatar_url

### Авторизация & безопасность
- Argon2 хэширование паролей [Auth API](api/auth.md)
- JWT токены (access + refresh)
- Роли: admin, user
- HTTPS/TLS (Nginx Reverse Proxy)
- Email верификация

### Видеоконференции
- LiveKit SFU + Coturn TURN — [Dev Setup с профилем media](deploy/dev-setup.md)
- Per-track audio (без диаризации)
- WebRTC via LiveKit JS SDK
- Webhook обработка событий — [Conferences API](api/conferences.md)
- [Architecture](architecture/README.md#4-livekit-sfu)

### Чат конференции
- WebSocket чат в реальном времени — [Chat API](api/chat.md)
- Аутентификация по LiveKit-токену
- Гостевой доступ (отправка под гостевым именем)
- Broadcast через Redis pub/sub
- Тоггл `chat.enabled` из настроек инстанса

### Транскрибация & суммаризация
- Plugin contracts (Transcriber, Summarizer)
- NullTranscriber, NullSummarizer (no-op по умолчанию)
- faster-whisper для STT (3 модели: small/medium/large-v3, уровни min/medium/max)
- Qwen3.5 для LLM (3 модели: 4B/9B/35B-A3B, Q4_K_M, уровни min/medium/max)
- Матрица уровней AI (ADR-004), инсталлятор с автодетектом, раздельные очереди Celery, метрики, eval-корпус
- Pluggable реализации via [Plugin Contracts](plugins/contracts.md)

### Динамические конференции
- Конференции как пользовательские сущности (номер, slug, владелец)
- Номер (9 цифр) и постоянная ссылка (base64url slug)
- Мгновенные и плановые конференции — [Conferences API](api/conferences.md)
- Закреплённые конференции с повторением (weekly/biweekly/monthly/every_n_days)
- Гостевой доступ (display_name обязателен, email факультативен)
- [ADR-001](architecture/adr/001-dynamic-conferences-pivot.md), [Schema](db/schema.md#conferences)

### Асинхронные задачи
- Redis broker + Celery worker/beat инфраструктура — [Workers README](../workers/README.md)
- Периодические задачи (beat): очистка зависших сеансов/конференций, восстановление зависших саммари/уведомлений
- Celery-задачи (транскрибация, суммаризация, уведомления, приглашения)
- Идемпотентный pipeline (recording → transcribing → summarizing → notified)
- [Workers README](../workers/README.md)

### Deployment & инсталляция
- Инсталлятор `install.sh` с автодетектом железа (5 пресетов)
- 5 пресетов: MVP, +чат, +AI min/medium/max
- Раздельные очереди Celery (transcription/summarize/notify)
- Мониторинг (Prometheus + Grafana)
- [Инсталлятор & пресеты](deploy/hardware-profiles.md)
- [Мониторинг](deploy/monitoring.md)
- [Масштабирование](deploy/scaling.md)
- [Ёмкость](deploy/capacity.md)

## Файловая структура docs/

```
docs/
├── architecture/       Архитектурные решения
│   ├── README.md      Обзор системы
│   ├── conference-room-ui.md  Интерфейс комнаты (PiP, аватары, настройки устройств)
│   ├── frontend-themes.md  Светлая/тёмная тема оболочки
│   └── adr/           Architectural Decision Records
│       └── 000-template.md
├── api/               HTTP & WebSocket API
│   ├── README.md      Endpoints, примеры, коды ошибок
│   ├── auth.md        Аутентификация
│   ├── users.md       Профиль пользователя, поиск
│   ├── teams.md       Справочник команд
│   ├── conferences.md Управление конференциями
│   ├── chat.md        Текстовый чат
│   └── admin.md       Администраторский API
├── db/                База данных
│   └── schema.md      ER-диаграмма, таблицы, миграции
├── plugins/           AI-плагины
│   ├── contracts.md   Интерфейсы, фабрика, как расширить
│   ├── transcriber.md Transcriber плагины
│   └── summarizer.md  Summarizer плагины
├── deploy/            Deployment & инструменты
│   ├── dev-setup.md   Локальная разработка
│   ├── hardware-profiles.md  Пресеты инсталлятора (5 вариантов)
│   ├── install.md     Инсталлятор `install.sh` (автодетект железа)
│   ├── env.md          Справочник переменных окружения
│   ├── llm-setup.md    Установка модели LLM
│   ├── monitoring.md  Prometheus + Grafana
│   ├── scaling.md     Горизонтальное масштабирование
│   ├── capacity.md    Калькулятор нагрузки
│   └── quality-tiers.md  Методика и результаты оценки качества суммаризации по уровням AI
└── README.md          Этот файл
```

## Правила

- **Без документации не мёржится** — каждое изменение функциональности включает обновление docs
- **По факту кода** — docs читают из реального кода, не выдумывают
- **Язык** — русский для описания, имена кода как в коде
- **Mermaid диаграммы** — ER, архитектура, data flow
- **Ссылки** — всегда абсолютные, между файлами в docs/

## Начните отсюда

1. Читаете проект впервые? → [Architecture Overview](architecture/README.md)
2. Ставите локально? → [Dev Setup](deploy/dev-setup.md)
3. Добавляете фичу? → нужный раздел (backend/frontend/db/plugins) + обновить docs
4. Запускаете в prod? → [Hardware Profiles](deploy/hardware-profiles.md)
5. Расширяете AI? → [Plugin Contracts](plugins/contracts.md)

## Контакты & вопросы

- Issues: GitHub Issues
- Обсуждение архитектуры: ADR в `docs/architecture/adr/`
- Код без docs: не мёржится по политике проекта