Первоначальная версия VidConf

2026-07-23 01:04:01 +03:00
commit 896455381a
335 changed files with 61527 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,152 @@
+# 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: не мёржится по политике проекта