From f9f8d22f8d4c8e4070cba484886628495a2e856d Mon Sep 17 00:00:00 2001 From: joylessorchid Date: Tue, 24 Mar 2026 12:39:52 +0300 Subject: [PATCH] docs: update CLAUDE.md and README.md for v0.0.1 - CLAUDE.md: add dev:https command, UI Architecture section (design system, room layout, screen share, sidebar), new Known Issues (HTTPS, chat duplication, self-ban), https:// in trustedOrigins note - README.md: add dev:https command, features list for v0.0.1, screen share mention, HTTPS note for LAN, self-ban protection in API table --- CLAUDE.md | 21 ++++++++++++++++++--- README.md | 21 ++++++++++++++++++--- 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9f1d4e0..06fbafa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,8 +43,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co │ │ ├── login/ & register/ # Auth pages │ │ └── page.tsx # Landing │ ├── components/ -│ │ ├── room/ # ChatPanel, ModerationPanel -│ │ └── lobby/ # WaitingRoom, LobbyManager +│ │ ├── room/ # ChatPanel, ModerationPanel (with self-ban protection) +│ │ └── lobby/ # WaitingRoom, LobbyManager (scrollable) │ ├── lib/ # prisma, auth, auth-helpers, livekit, redis, rate-limit, lobby-pubsub, chat-pubsub │ ├── middleware.ts # Dev protection (DEV_ACCESS_KEY, ALLOWED_IPS) │ └── types/ @@ -106,6 +106,7 @@ Clients → Traefik (LB) → Next.js (x2 replicas) → PgBouncer (pool 25, max 5 ```bash # Dev npm run dev # Next.js dev server (localhost:3000) +npm run dev:https # Dev server with self-signed HTTPS (media devices on LAN) docker compose up -d postgres minio redis pgbouncer # DB + Storage + Redis + PgBouncer npm run lint # TypeScript type-check (tsc --noEmit) @@ -182,7 +183,7 @@ DEV_ACCESS_KEY=mySecretKey123 - `better-auth` handles registration/login via `/api/auth/[...all]` catch-all route - **Client:** `auth-client.ts` uses `createAuthClient()` without `baseURL` — auto-detects current origin (works from any IP/domain) -- **Server:** `auth.ts` uses `BETTER_AUTH_URL` for `baseURL` and `BETTER_AUTH_TRUSTED_ORIGINS` (comma-separated) for CSRF origin validation. Without `BETTER_AUTH_TRUSTED_ORIGINS`, auto-detects all machine IPs via `os.networkInterfaces()` + localhost on ports 3000–3010 +- **Server:** `auth.ts` uses `BETTER_AUTH_URL` for `baseURL` and `BETTER_AUTH_TRUSTED_ORIGINS` (comma-separated) for CSRF origin validation. Without `BETTER_AUTH_TRUSTED_ORIGINS`, auto-detects all machine IPs via `os.networkInterfaces()` + localhost on ports 3000–3010, both `http://` and `https://` protocols - First admin: first registered user automatically becomes ADMIN (via `databaseHooks.user.create.before` in `auth.ts`) - **No `"type"` field in `package.json`** — removed to fix Turbopack ESM/CJS conflict in dev mode. Next.js handles ESM in `.ts/.tsx` automatically @@ -222,6 +223,20 @@ DEV_ACCESS_KEY=mySecretKey123 | `setup.sh doctor` crashes on .env check | Comments in `.env.example` parsed as variable names by `set -euo pipefail` | Fixed parsing logic | | `setup.sh update` runs git pull after stash declined | Missing `else` branch after stash prompt | Fixed control flow | | Auth form resets on non-localhost (no error shown) | `trustedOrigins` fallback only had `localhost:3000`, CSRF rejected other origins silently | `auth.ts` auto-allows ports 3000–3010 + `LAN_HOST`; `setup.sh dev` auto-detects LAN IP | +| Media devices blocked on LAN (not HTTPS) | Browsers require secure context for getUserMedia | `npm run dev:https` (Next.js `--experimental-https`), `setup.sh dev` auto-uses HTTPS | +| Chat messages duplicated | Race: SSE delivers msg before POST response, seenIds doesn't have real id yet | Check if SSE already delivered the message before replacing optimistic | +| Ban self crashes room | No server-side check for self-ban/kick | API rejects `targetSessionId === session.user.id`, UI hides buttons for self | + +## UI Architecture + +- **Design system:** CSS custom properties in `globals.css` via Tailwind v4 `@theme` — surface levels (0–3), accent (indigo), status colors, border tokens +- **Room layout (Google Meet style):** + - Minimal top bar (room name + code) + - Video area: `GridLayout` (cameras) or `FocusLayout` (screen share active — carousel + focused view) + - Bottom control bar: mic, camera, screen share | chat, lobby, moderation, hand raise | leave/end +- **Screen share:** auto-detected via `useTracks(Track.Source.ScreenShare)`, switches to focus layout with `CarouselLayout` for camera feeds +- **Sidebar:** 320px right panel for chat, lobby manager, moderation — stacked, each with own scroll +- **Components use LiveKit hooks:** `useLocalParticipant`, `useParticipants`, `useRoomContext`, `useTracks` ## Conventions diff --git a/README.md b/README.md index 75a5ea3..3de62f1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # LiveServer-M1 -Образовательная видеоконференц-платформа на базе LiveKit. AI-транскрипция, модерация, пост-лекционные артефакты. +Образовательная видеоконференц-платформа на базе LiveKit. Демонстрация экрана, AI-транскрипция, модерация, пост-лекционные артефакты. ## Стек @@ -85,7 +85,7 @@ npx prisma db push npm run dev ``` -Приложение: `http://localhost:3000` +Приложение: `http://localhost:3000` (или `https://localhost:3000` с `npm run dev:https` для доступа к камере/микрофону по LAN) **Первый администратор:** первый зарегистрированный пользователь автоматически получает роль ADMIN. @@ -163,6 +163,7 @@ Traefik автоматически получит SSL-сертификат че # Разработка (ручной запуск) npm run dev # Next.js dev server +npm run dev:https # Dev server с HTTPS (для камеры/микрофона по LAN) npm run lint # TypeScript type-check (tsc --noEmit) npm run build -- --webpack # Production build (Webpack, не Turbopack — WASM на Windows) @@ -232,7 +233,7 @@ docker compose logs -f app # | `POST` | `/api/rooms/:id/start` | Старт лекции | | `POST` | `/api/rooms/:id/end` | Завершение лекции | | `GET/POST` | `/api/rooms/:id/lobby` | Управление лобби | -| `POST` | `/api/rooms/:id/moderate` | Kick, ban, mute all | +| `POST` | `/api/rooms/:id/moderate` | Kick, ban, mute all (self-ban protected) | | `POST` | `/api/livekit/token` | Генерация токена LiveKit | ### Требуют участия в комнате (sessionId) @@ -248,3 +249,17 @@ docker compose logs -f app # | **ADMIN** | Всё + глобальная панель, мониторинг всех комнат | | **HOST** | Создание комнат, модерация, настройки безопасности | | **GUEST** | Вход по ссылке, участие в лекции (без регистрации) | + +## Возможности v0.0.1 + +- Видеоконференции (камера, микрофон, демонстрация экрана) +- Google Meet-style UI: нижняя панель управления, тёмная тема +- Автофокус при демонстрации экрана (карусель камер + фокус на экране) +- Зал ожидания (lobby) с SSE через Redis pub/sub +- PIN-коды для комнат (bcrypt + rate limiting) +- Real-time чат (SSE + optimistic UI, дедупликация) +- Модерация: kick, ban по fingerprint, mute all +- Поднятие руки (вебинар-режим) +- Первый пользователь автоматически → ADMIN +- HTTPS для локальной разработки (`--experimental-https`) +- Универсальный setup.sh (install/dev/doctor/status/update)