How rcun-org/rcun-rooms works
Что это за проект (тип и назначение)
По README и дереву файлов это backend-микросервис “RCUN Rooms” для управления “комнатами” совместного просмотра.
• Runtime/Framework: NestJS (TypeScript)
• Данные: Prisma ORM + PostgreSQL (Neon)
• Auth: JWT, общий секрет AUTH_JWT_SECRET (ожидается внешний сервис rcun-auth, но в этом репо он не присутствует)
• Экспонируемые интерфейсы: HTTP REST API (включая health endpoints)
• Деплой: Docker/Compose, GitHub Actions → Docker Hub, Render (render.yaml)
• Важный нюанс: это “rooms” microservice, который может использовать общую БД с auth-сервисом или отдельную (см. .env и README).
Итого: диаграмма должна быть в стиле C4/контейнеры + компоненты внутри сервиса: внешние зависимости (клиенты/шлюз/другие сервисы/БД) и внутренняя NestJS-модульная структура.
Как читать структуру проекта (ключевые части)
Верхний уровень:
• src/main.ts — bootstrap HTTP сервера Nest (порт 5004 по README)
• src/app.module.ts — корневой модуль, собирает остальные модули
• src/rooms/* — доменная область “Rooms”: controller/service/dto/module
• src/auth/* — JWT guard/strategy/module (локальная проверка токена, без выдачи токенов)
• src/prisma/* — PrismaService и модуль для доступа к БД
• src/health/* — readiness/liveness
• prisma/schema.prisma, prisma/migrations/* — модель данных и миграции
• Dockerfile, docker-entrypoint.sh, docker-compose.yml — контейнеризация; entrypoint запускает prisma migrate deploy
• .github/workflows/deploy.yml — CI/CD: сборка/пуш образа и триггер Render hook
• render.yaml — описание сервиса для Render
Архитектурный паттерн здесь типичный для NestJS:
Controller → Service → PrismaService(DB), плюс Guard/Strategy для аутентификации на защищённых эндпоинтах.
Clients
• rcun-web (упомянут alias /api/room)
• возможно другие клиенты (Postman/CLI) — опционально
RCUN Rooms service (этот репо)
• HTTP API :5004
• REST endpoints /rooms, /rooms/:id, invite endpoint и health
Auth provider
• Логически: “rcun-auth” как отдельный микросервис (в репо отсутствует, но зависимость на общий AUTH_JWT_SECRET означает доверие к токенам, которые он выдаёт)
• На диаграмме показать как внешний сервис: “JWT issuer”
Database
• Neon PostgreSQL
• Подключение через ROOMS_DATABASE_URL (или shared DB)
• Prisma как слой доступа
CI/CD & Runtime окружение (по важности)
• GitHub Actions → Docker Hub (maksat1/rcun-rooms:latest) → Render deploy hook → Render Web Service
Внутренний уровень (компонентная диаграмма внутри сервиса)
• AppModule (composition root)
• RoomsModule
• RoomsController
• ApiRoomAliasController (alias-роуты /api/room... для совместимости с rcun-web)
• RoomsService
• DTO (create/update) — как контракты входных данных
• AuthModule
• JwtAuthGuard
• JwtStrategy (валидация JWT подписи/claims через AUTH_JWT_SECRET)
• PrismaModule
• PrismaService → PostgreSQL
• HealthModule
• HealthController (readiness/liveness)
Связи и взаимодействия (что рисовать стрелками)
Ниже — минимальный “истинный” поток запросов, который нужно отразить стрелками:
Client → Rooms HTTP API
• Неавторизованные: GET /rooms, GET /rooms/:id (по README JWT нужен для mutating endpoints)
• Авторизованные: POST/PATCH/DELETE, invite
RoomsController / ApiRoomAliasController → JwtAuthGuard (для защищённых роутов)
• Guard дергает JwtStrategy для валидации токена
Controller → RoomsService
• Оркестрация бизнес-логики (например, проверка owner для update/delete/invite — README говорит “owner”)
RoomsService → PrismaService → PostgreSQL(Neon)
• CRUD по сущностям, определённым в schema.prisma
HealthController → (опционально PrismaService)
• Readiness часто включает проверку БД; liveness обычно просто “процесс жив”. Если в коде health реально проверяет БД — отразить стрелкой, если нет — оставить как самостоятельный endpoint.
Auth dependency (внешняя)
• Rooms сервис не ходит в rcun-auth по сети (по дереву нет клиента), он доверяет JWT, подписанному общим секретом.
• На диаграмме это лучше показать так:
rcun-auth issues JWT → client приносит JWT → rcun-rooms verifies JWT (shared secret).
Важные архитектурные акценты именно этого проекта
1) Модульность NestJS: отдельные модули rooms/auth/prisma/health — удобно рисовать как компоненты внутри контейнера.
2) Prisma как граница данных: все обращения к PostgreSQL должны проходить через PrismaService.
3) JWT-only verification: нет OAuth flows, нет user DB в этом сервисе (судя по дереву). Авторизация — через guard/strategy.
4) Alias controller для rcun-web: это интеграционная деталь, стоит подписать как “compatibility routes”.
5) Автомиграции при старте контейнера: docker-entrypoint.sh + prisma migrate deploy — важная часть runtime-архитектуры (особенно для readiness и инцидентов).
Как именно нарисовать “лучшие и самые точные” диаграммы (рекомендуемый набор)
Чтобы покрыть проект максимально детально и не “перемудрить”, сделай 3 диаграммы (или 3 уровня на одной):
System Context (L1)
Сущности:
• User/Browser (rcun-web)
• RCUN Rooms Service
• Neon PostgreSQL
• RCUN Auth Service (JWT issuer)
• (Опционально) Render/Docker Hub/GitHub Actions как deployment окружение
Стрелки:
• Browser → Rooms: HTTPS REST
• Browser → Auth: login/receive JWT (контекстно)
• Auth → Browser: JWT
• Rooms → Neon Postgres: SQL via Prisma
Container/Runtime (L2) — “что реально запущено”
Контейнеры/узлы:
• rcun-rooms Docker container (NestJS app)
• Neon Postgres (managed)
• (Опционально) Render Web Service (как хостинг контейнера)
Добавь подписи:
• Port 5004
• Env vars: ROOMS_DATABASE_URL, AUTH_JWT_SECRET
• Startup: prisma migrate deploy (entrypoint)
**Компоненты (прямо из src/*):**
• Controllers: RoomsController, ApiRoomAliasController, HealthController
• Services: RoomsService, PrismaService
• Auth: JwtAuthGuard, JwtStrategy
• Modules: RoomsModule, AuthModule, PrismaModule, HealthModule, AppModule
Стрелки:
• Controllers → Guard/Strategy (для защищённых)
• Controllers → RoomsService
• RoomsService → PrismaService → DB
• HealthController → (PrismaService?) → DB (если проверяет)
Обязательные элементы оформления (чтобы диаграмма была “инженерной”)
• Чёткие подписи:
• “rcun-rooms (NestJS)”
• “Prisma ORM”
• “Neon PostgreSQL”
• “JWT (shared secret AUTH_JWT_SECRET)”
• “/rooms, /api/room alias, /health/*”
• Направленные стрелки:
• подпиши протокол (HTTP/HTTPS) и тип данных (JWT, JSON)
• Цвета/формы (простое правило):
• Внешние системы — один цвет/форма (например, серые прямоугольники)
• Внутренние компоненты Nest — другой (например, синие)
• Данные/хранилища — цилиндр
• CI/CD — пунктир/отдельная зона “Delivery pipeline”
• Рамка “RCUN Rooms Microservice”
• Внутри — рамки модулей NestJS
Конкретные подсказки “куда смотреть в коде”, чтобы уточнить детали на диаграмме
Чтобы диаграмма была максимально точной, проверь в этих файлах и добавь детали, которые там найдёшь:
• src/main.ts: порт, глобальные префиксы, pipes/validation, swagger (если есть)
• src/app.module.ts: какие модули реально импортируются
• src/rooms/*.controller.ts: какие эндпоинты реально публичные, какие под guard
• src/auth/guards/jwt-auth.guard.ts и src/auth/strategies/jwt.strategy.ts: откуда берётся secret, какие claims нужны (userId и т.п.)
• prisma/schema.prisma: какие таблицы/relations (Room, membership, invites и т.д.) — можно на отдельной ER-диаграмме
• docker-entrypoint.sh: порядок migrate/generate/start (это влияет на “startup flow”)
Что добавить “по максимуму компонентов” без лишней фантазии
• Отдельно отрисуй:
• “Rooms REST API”
• “Alias API for rcun-web”
• “Auth verification layer (JWT Guard/Strategy)”
• “Persistence layer (PrismaService)”
• “Migration on startup”
• “Health endpoints (liveness/readiness)”
• И отдельно — “Delivery pipeline”: GitHub Actions → Docker Hub → Render
Так ты получишь максимально подробную и при этом правдивую архитектурную картину, полностью соответствующую дереву проекта и README.