153 lines
9.5 KiB
Markdown
153 lines
9.5 KiB
Markdown
# 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: не мёржится по политике проекта
|