# rcun-org/rcun-rooms architecture

> Architecture diagram of the GitHub repository rcun-org/rcun-rooms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rcun-org/rcun-rooms
- Repository: https://github.com/rcun-org/rcun-rooms

## Overview

##### Что это за проект (тип и назначение)
По 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% L1 — System Context (C4-L1)
  %% =========================
  subgraph L1["L1 — System Context"]
    direction TB

    User["User / Browser"]:::external
    Web["rcun-web (Frontend)"]:::external
    Clients["Other API Clients (Postman/CLI)"]:::external

    AuthSvc["RCUN Auth Service (JWT issuer)"]:::external
    RoomsSvc["RCUN Rooms Service (this repo)"]:::service
    DB[("Neon PostgreSQL")]:::db

    User -->|"uses"| Web
    User -->|"uses"| Clients

    Web -->|"HTTPS REST (JSON)\n/rooms, /api/room*, /health/*"| RoomsSvc
    Clients -->|"HTTP(S) REST (JSON)"| RoomsSvc

    Web -->|"login"| AuthSvc
    AuthSvc -->|"issues JWT"| Web

    RoomsSvc -->|"SQL via Prisma ORM"| DB
    AuthSvc -.->|"shared secret\nAUTH_JWT_SECRET"| RoomsSvc
  end

  %% =========================
  %% L2 — Container / Runtime (C4-L2)
  %% =========================
  subgraph L2["L2 — Container / Runtime"]
    direction TB

    Render["Render (Web Service host)"]:::platform
    DockerC["rcun-rooms Docker Container"]:::container
    NestApp["NestJS App Process\n(listens on :5004)"]:::service
    Entry["Container Entrypoint\n(prisma migrate deploy)"]:::ops
    Env["Runtime Env Vars\nROOMS_DATABASE_URL\nAUTH_JWT_SECRET"]:::config
    NeonDB[("Neon PostgreSQL (managed)")]:::db

    Render -->|"runs"| DockerC
    DockerC -->|"exec"| Entry
    Entry -->|"then starts"| NestApp
    Env -->|"configures"| Entry
    Env -->|"configures"| NestApp
    NestApp -->|"connects (Prisma)"| NeonDB
  end

  %% =========================
  %% L3 — Components inside rcun-rooms (C4-L3)
  %% =========================
  subgraph L3["L3 — Components inside rcun-rooms (NestJS)"]
    direction TB

    subgraph Boot["Bootstrap"]
      direction TB
      Main["main.ts\nNestFactory bootstrap"]:::code
      AppModule["AppModule\n(composition root)"]:::module
      Main -->|"creates app"| AppModule
    end

    subgraph Modules["NestJS Modules"]
      direction TB

      subgraph RoomsMod["RoomsModule"]
        direction TB
        RoomsCtl["RoomsController\n/rooms*"]:::controller
        AliasCtl["ApiRoomAliasController\n/api/room* (compat)"]:::controller
        RoomsSvcComp["RoomsService\n(business logic)"]:::service

        subgraph DTOs["DTO Contracts"]
          direction TB
          CreateDTO["CreateRoomDto"]:::dto
          UpdateDTO["UpdateRoomDto"]:::dto
        end

        RoomsCtl -->|"validates input"| CreateDTO
        RoomsCtl -->|"validates input"| UpdateDTO
        AliasCtl -->|"validates input"| CreateDTO
        AliasCtl -->|"validates input"| UpdateDTO

        RoomsCtl -->|"calls"| RoomsSvcComp
        AliasCtl -->|"calls"| RoomsSvcComp
      end

      subgraph AuthMod["AuthModule (JWT verification)"]
        direction TB
        JwtGuard["JwtAuthGuard\n(protects mutating endpoints)"]:::auth
        JwtStrategy["JwtStrategy\n(verifies JWT via AUTH_JWT_SECRET)"]:::auth
        JwtGuard -->|"delegates validate"| JwtStrategy
      end

      subgraph PrismaMod["PrismaModule (DB access)"]
        direction TB
        PrismaSvc["PrismaService\n(PrismaClient wrapper)"]:::data
      end

      subgraph HealthMod["HealthModule"]
        direction TB
        HealthCtl["HealthController\n/health/liveness\n/health/readiness"]:::controller
      end
    end

    %% Cross-module wiring (typical NestJS flow)
    RoomsCtl -->|"for protected routes"| JwtGuard
    AliasCtl -->|"for protected routes"| JwtGuard

    RoomsSvcComp -->|"CRUD via Prisma"| PrismaSvc
    HealthCtl -.->|"optional readiness DB check"| PrismaSvc

    PrismaSvc -->|"queries"| L3DB[("PostgreSQL (Neon)")]:::db
  end

  %% =========================
  %% Delivery pipeline (CI/CD)
  %% =========================
  subgraph CI["Delivery Pipeline"]
    direction TB
    GH["GitHub Actions\n(build/test/push)"]:::cicd
    DH["Docker Hub\nmaksat1/rcun-rooms:latest"]:::registry
    Hook["Render Deploy Hook"]:::cicd
    RenderDeploy["Render Deploy\n(pull image + run)"]:::platform

    GH -->|"docker build + push"| DH
    GH -->|"trigger"| Hook
    Hook -->|"deploy"| RenderDeploy
    DH -->|"image pull"| RenderDeploy
  end

  %% Tie delivery to runtime
  RenderDeploy -->|"updates service"| Render

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click Main "https://github.com/rcun-org/rcun-rooms/blob/main/src/main.ts"
  click AppModule "https://github.com/rcun-org/rcun-rooms/blob/main/src/app.module.ts"

  click RoomsMod "https://github.com/rcun-org/rcun-rooms/blob/main/src/rooms/rooms.module.ts"
  click RoomsCtl "https://github.com/rcun-org/rcun-rooms/blob/main/src/rooms/rooms.controller.ts"
  click AliasCtl "https://github.com/rcun-org/rcun-rooms/blob/main/src/rooms/api-room-alias.controller.ts"
  click RoomsSvcComp "https://github.com/rcun-org/rcun-rooms/blob/main/src/rooms/rooms.service.ts"
  click CreateDTO "https://github.com/rcun-org/rcun-rooms/blob/main/src/rooms/dto/create-room.dto.ts"
  click UpdateDTO "https://github.com/rcun-org/rcun-rooms/blob/main/src/rooms/dto/update-room.dto.ts"
  click DTOs "https://github.com/rcun-org/rcun-rooms/tree/main/src/rooms/dto"

  click AuthMod "https://github.com/rcun-org/rcun-rooms/blob/main/src/auth/auth.module.ts"
  click JwtGuard "https://github.com/rcun-org/rcun-rooms/blob/main/src/auth/guards/jwt-auth.guard.ts"
  click JwtStrategy "https://github.com/rcun-org/rcun-rooms/blob/main/src/auth/strategies/jwt.strategy.ts"

  click PrismaMod "https://github.com/rcun-org/rcun-rooms/blob/main/src/prisma/prisma.module.ts"
  click PrismaSvc "https://github.com/rcun-org/rcun-rooms/blob/main/src/prisma/prisma.service.ts"
  click L3DB "https://github.com/rcun-org/rcun-rooms/blob/main/prisma/schema.prisma"
  click NeonDB "https://github.com/rcun-org/rcun-rooms/blob/main/prisma/schema.prisma"
  click DB "https://github.com/rcun-org/rcun-rooms/blob/main/prisma/schema.prisma"
  click Entry "https://github.com/rcun-org/rcun-rooms/blob/main/docker-entrypoint.sh"

  click HealthMod "https://github.com/rcun-org/rcun-rooms/blob/main/src/health/health.module.ts"
  click HealthCtl "https://github.com/rcun-org/rcun-rooms/blob/main/src/health/health.controller.ts"

  click DH "https://github.com/rcun-org/rcun-rooms/tree/main/Dockerfile"
  click DockerC "https://github.com/rcun-org/rcun-rooms/blob/main/docker-compose.yml"
  click GH "https://github.com/rcun-org/rcun-rooms/blob/main/.github/workflows/deploy.yml"
  click RenderDeploy "https://github.com/rcun-org/rcun-rooms/blob/main/render.yaml"
  click Env "https://github.com/rcun-org/rcun-rooms/blob/main/.env.example"

  %% Prisma migrations artifacts
  click CI "https://github.com/rcun-org/rcun-rooms/tree/main/prisma/migrations"
  click Hook "https://github.com/rcun-org/rcun-rooms/blob/main/prisma/migrations/20240207000000_init/migration.sql"

  %% Tests
  click Clients "https://github.com/rcun-org/rcun-rooms/blob/main/test/app.e2e-spec.ts"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440
  classDef service fill:#D6EFFF,stroke:#2B6CB0,stroke-width:1.5px,color:#102A43
  classDef controller fill:#E6FFFA,stroke:#0F766E,stroke-width:1.5px,color:#0B3B36
  classDef module fill:#E9D8FD,stroke:#6B46C1,stroke-width:1.5px,color:#2D1B69
  classDef auth fill:#FFE4E6,stroke:#BE123C,stroke-width:1.5px,color:#3F0A17
  classDef data fill:#FFF7ED,stroke:#C2410C,stroke-width:1.5px,color:#3B1D0E
  classDef db fill:#FFF1F2,stroke:#9F1239,stroke-width:1.5px,color:#3B0A12
  classDef container fill:#E0E7FF,stroke:#3730A3,stroke-width:1.5px,color:#1E1B4B
  classDef platform fill:#F1F5F9,stroke:#334155,stroke-width:1.5px,color:#0F172A
  classDef cicd fill:#F0FDF4,stroke:#166534,stroke-width:1.5px,color:#052E16
  classDef registry fill:#FEFCE8,stroke:#A16207,stroke-width:1.5px,color:#3F2A00
  classDef ops fill:#FAFAFA,stroke:#525252,stroke-width:1.5px,color:#171717
  classDef config fill:#F5F3FF,stroke:#5B21B6,stroke-width:1.5px,color:#2E1065
  classDef dto fill:#FDF2F8,stroke:#9D174D,stroke-width:1.5px,color:#500724
  classDef code fill:#E2E8F0,stroke:#1F2937,stroke-width:1.5px,color:#0B1220
```
