vidconf/docs

Documentation Index

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

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

• README проекта — обзор VidConf, стек, структура монорепо
• Design System — цветовые токены, типографика, компоненты, мокапы
• Dev Setup — локальная разработка (Docker, миграции, тесты)
• API Reference — HTTP endpoints, примеры запросов

Архитектура

• Architecture Overview — система компонентов, data flow, design decisions
• Database Schema — ER-диаграмма, описание 14 таблиц, ключевые решения
• Plugin Contracts — как работают плагины AI (Transcriber/Summarizer), как добавить свой
• Пресеты инсталлятора & профили оборудования — 5 вариантов, автодетект железа, требования ресурсов

Разработка

• Backend README — FastAPI, модели, миграции, тесты, плагины
• Frontend README — React SPA, компоненты, стайлинг
• Workers README — Celery, транскрибация, суммаризация, уведомления

ADR (Architectural Decision Records)

• 000-template.md — стандартный шаблон ADR для проекта
• Направление: добавлять ADR для крупных архитектурных решений

По темам

Интерфейс комнаты конференции

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

Авторизация & безопасность

• Argon2 хэширование паролей Auth API
• JWT токены (access + refresh)
• Роли: admin, user
• HTTPS/TLS (Nginx Reverse Proxy)
• Email верификация

Видеоконференции

• LiveKit SFU + Coturn TURN — Dev Setup с профилем media
• Per-track audio (без диаризации)
• WebRTC via LiveKit JS SDK
• Webhook обработка событий — Conferences API
• Architecture

Чат конференции

• WebSocket чат в реальном времени — Chat API
• Аутентификация по 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

Динамические конференции

• Конференции как пользовательские сущности (номер, slug, владелец)
• Номер (9 цифр) и постоянная ссылка (base64url slug)
• Мгновенные и плановые конференции — Conferences API
• Закреплённые конференции с повторением (weekly/biweekly/monthly/every_n_days)
• Гостевой доступ (display_name обязателен, email факультативен)
• ADR-001, Schema

Асинхронные задачи

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

Deployment & инсталляция

• Инсталлятор install.sh с автодетектом железа (5 пресетов)
• 5 пресетов: MVP, +чат, +AI min/medium/max
• Раздельные очереди Celery (transcription/summarize/notify)
• Мониторинг (Prometheus + Grafana)
• Инсталлятор & пресеты
• Мониторинг
• Масштабирование
• Ёмкость

Файловая структура 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
2. Ставите локально? → Dev Setup
3. Добавляете фичу? → нужный раздел (backend/frontend/db/plugins) + обновить docs
4. Запускаете в prod? → Hardware Profiles
5. Расширяете AI? → Plugin Contracts

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

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