Архитектура

Ветка-эталон: main · Тип: Nx-монорепозиторий · Рантайм: NestJS 11 (Node 22)

Общая идея

CrewsForge Back — это набор самостоятельных NestJS-приложений (микросервисы по домену), которые собираются из общих библиотек внутри одного Nx-workspace. Каждый сервис деплоится отдельно, но переиспользует единый слой конфигов, клиентов к инфраструктуре, доменных фич и общих утилит.

Единственная общая точка данных — одна PostgreSQL-схема (Prisma), генерируемая из apps/core-api/prisma/schema.prisma и используемая всеми сервисами через prisma-client.

Приложения (apps/)

Сервис	Роль	Транспорт	Документация
auth-api	Аутентификация customer/employee/admin, JWT, сессии, верификация, сброс пароля	HTTP + Cookie	auth-api
user-api	Пользователи, профили, роли, справочники, аватары	HTTP	user-api
project-api	Проекты и машина статусов	HTTP	project-api
admin-api	Админ-панель: пользователи и проекты	HTTP	admin-api
ai-agent-service	Реалтайм-чат с AI-агентом	WebSocket + RabbitMQ	ai-agent-service
core-api	Держатель Prisma-схемы, миграций и сидов (не бизнес-сервис)	—	core-api

Каждое приложение (apps/<name>/src/main.ts + app/app.module.ts) — тонкая оболочка: bootstrap, глобальные пайпы/фильтры, Swagger, CLS-транзакции и подключение доменных модулей из libs/. Бизнес-логики в apps/ практически нет.

Слои библиотек (libs/apis/)

libs/apis/
├── core/         # Доменное ядро без зависимостей (ни NestJS, ни инфраструктуры)
│   ├── money/               # округление, комиссия, сплит сеттлмента
│   ├── domain-events/       # каталог routing keys и типы payload'ов шины
│   └── platform-calendar/   # рабочие часы и дни платформы
├── configs/      # Типизированные конфиг-модули (env + валидация Joi)
│   ├── shared/   # app, redis, s3, smtp, rabbit
│   └── auth-api/ # jwt-customer, jwt-employee, jwt-admin
├── providers/    # Доменная логика, сгруппированная по сервисам
│   ├── auth-api/          # customer-auth, employee-auth, admin-auth, session, token, user-auth
│   ├── user-api/          # customer, employee, profile, user
│   ├── project-api/       # project
│   ├── admin-api/         # admin-user, admin-project
│   ├── ai-agent-service/  # agent-chat
│   └── email-sender-api/  # sender
├── shared/       # Guards, decorators, filters, helpers, mapper, validators
└── utils/        # Клиенты инфраструктуры: prisma, redis, s3, rabbit, mailer

Внутри каждого providers/<service>/ действует деление:

• data-access/ — DTO, константы, типы, интерфейсы (без логики, без контроллеров);
• features/<feature>/ — модуль фичи: *.module.ts, *.controller.ts, *.service.ts, *.repository.ts.

Диаграмма зависимостей

flowchart TD
    subgraph apps[apps/ — приложения]
        AUTH[auth-api]
        USER[user-api]
        PROJ[project-api]
        ADMIN[admin-api]
        AI[ai-agent-service]
    end

    subgraph providers[libs/apis/providers — доменные фичи]
        P_AUTH[auth-api/*]
        P_USER[user-api/*]
        P_PROJ[project-api/*]
        P_ADMIN[admin-api/*]
        P_AI[ai-agent-service/*]
        P_MAIL[email-sender-api/*]
    end

    subgraph shared[libs/apis/shared + configs]
        SH[shared: guards/decorators/helpers/mapper]
        CFG[configs: app/redis/s3/smtp/rabbit/jwt-*]
    end

    subgraph utils[libs/apis/utils — клиенты]
        PRISMA[prisma-client]
        REDIS[redis-client]
        S3[s3-client]
        RABBIT[rabbit-client]
        MAILER[mailer-client]
    end

    subgraph infra[Инфраструктура]
        PG[(PostgreSQL)]
        RD[(Redis)]
        MQ[(RabbitMQ)]
        S3B[(S3)]
        SMTP[(SMTP)]
        WAL[(Внешний AI-агент Walrider)]
    end

    AUTH --> P_AUTH --> SH
    USER --> P_USER --> SH
    PROJ --> P_PROJ --> SH
    ADMIN --> P_ADMIN --> SH
    AI --> P_AI --> SH

    P_AUTH --> P_MAIL
    SH --> CFG

    P_AUTH --> PRISMA & REDIS
    P_USER --> PRISMA & S3
    P_PROJ --> PRISMA
    P_ADMIN --> PRISMA
    P_AI --> PRISMA & RABBIT
    P_MAIL --> MAILER

    PRISMA --> PG
    REDIS --> RD
    RABBIT --> MQ
    S3 --> S3B
    MAILER --> SMTP
    P_AI -.->|через RabbitMQ| WAL

Ключевые архитектурные решения

• Единая БД, много сервисов. Все сервисы работают с одной схемой Prisma. Границы доменов — на уровне кода (модули), не на уровне баз.
• CLS + транзакции. Каждый сервис поднимает ClsModule c ClsPluginTransactional (@nestjs-cls/transactional-adapter-prisma) — транзакции прокидываются через контекст запроса, а X-Request-Id генерируется в middleware.
• Тонкие приложения, толстые библиотеки. Приложение = композиция модулей. Это позволяет переиспользовать одни и те же фичи в разных сервисах (например, WalriderThreadRepository встречается и в project-api, и в ai-agent-service поверх общей Prisma-схемы).
• Разделение по типам пользователей. customer / employee / admin имеют отдельные JWT-конфиги, стратегии и guard’ы (см. auth-api).
• Walrider — сквозная фича. Диалог с AI-агентом (thread/message/state) пронизывает несколько сервисов (см. walrider).

Как читать эту документацию

1. Начни с этого раздела и tech-stack — общий контекст.
2. conventions — паттерны, по которым устроена каждая фича (важно для дописывания нового).
3. data-flow — путь запроса сквозь слои.
4. 03-services/ — по одному сервису/домену: назначение, эндпоинты, зависимости, точки расширения.
5. 05-data/ — схема БД, миграции, сиды.
6. 04-shared-and-utils/ и 06-operations/ — общие библиотеки, env, деплой.