Backend architecture

Skill Vitammiin/agent-vorcl-flow/skills/backend-architecture

Обязательные правила модульной архитектуры бэкенда — src/modules/* со слоями controller/service/repository/routes/schemas/dto/types/middleware/index. Use ВСЕГДА при создании или изменении структуры backend-кода, новых модулей, эндпоинтов и файлов внутри модуля.From its SKILL.md

Install

npx -y skills add Vitammiin/agent-vorcl-flow --skill backend-architecture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

7.1 KB, as published. Nobody here has run it

Навык: Модульная архитектура бэкенда

Весь backend-код организуется по модулям в src/modules/*. Ниже — обязательные правила структуры, слоёв и зависимостей.

Навигатор. Суть: ответственность слоёв (controller/service/repository/…) → правила зависимостей (поток в одну сторону, импорт только из index.ts). Перед сдачей: чек-лист и правила безопасности. Справочно: полная структура каталогов · пример публичного index.ts.

Структура каталогов

src/
├── app/
│   ├── app.ts
│   ├── server.ts
│   │
│   └── plugins/
│       ├── swagger.plugin.ts
│       ├── jwt.plugin.ts
│       ├── cors.plugin.ts
│       ├── database.plugin.ts
│       └── index.ts
│
├── config/
│   ├── env.ts
│   └── index.ts
│
├── modules/
│   ├── auth/
│   │   ├── controller.ts
│   │   ├── service.ts
│   │   ├── repository.ts
│   │   ├── routes.ts
│   │   ├── schemas.ts
│   │   ├── dto.ts
│   │   ├── types.ts
│   │   ├── middleware.ts
│   │   └── index.ts
│   │
│   ├── users/
│   ├── ai/
│   ├── billing/
│   └── notifications/
│
├── shared/
│   ├── errors/
│   ├── types/
│   └── utils/
│
└── index.ts
.env
.env.example
DOCS.md

Внутри каждого модуля — фиксированный набор файлов:

<module>/
├── controller.ts    # HTTP-слой: разбор запроса, вызов service, формирование ответа
├── service.ts       # бизнес-логика и оркестрация; НЕ знает про HTTP и SQL
├── repository.ts    # доступ к данным; единственное место, где трогаем БД
├── routes.ts        # объявление маршрутов: middleware → controller
├── schemas.ts       # валидация ввода/вывода (zod)
├── dto.ts           # объекты передачи данных на границах модуля
├── types.ts         # доменные типы/интерфейсы модуля
├── middleware.ts    # middleware, специфичный для модуля
└── index.ts         # публичная поверхность модуля (barrel-экспорт)

Ответственность слоёв

controller — только HTTP: валидирует вход через schemas, вызывает service, маппит результат в ответ. Без бизнес-логики и без обращений к БД.
service — вся бизнес-логика и оркестрация. Работает с repository и с другими модулями (через их index.ts). Не знает про req/res и про SQL.
repository — только доступ к данным (SQL/ORM). Единственный слой, который трогает БД. Возвращает доменные типы/DTO, а не сырые строки.
routes — связывает путь + middleware + метод controller. Никакой логики.
schemas — zod-схемы запроса/ответа; из них выводятся типы (z.infer).
dto — форма данных, пересекающих границу модуля (вход в service и выход из него).
types — внутренние доменные типы модуля.
middleware — гварды/проверки, специфичные для модуля (напр. requireAuth).
index.ts — что модуль отдаёт наружу. Другие модули импортируют ТОЛЬКО отсюда.

Правила зависимостей

Поток вызовов строго в одну сторону: routes → controller → service → repository.
Слои не «перепрыгивают»: controller не ходит в repository напрямую; service не трогает req/res.
Межмодульное взаимодействие — только через <module>/index.ts. Внутренности чужого модуля не импортируются.
Общий код (утилиты, конфиг, БД-клиент) живёт вне модулей (src/shared, src/config); модули импортируют его, но не наоборот.
Типы выводятся из schemas (zod z.infer), чтобы валидация и типы не расходились.

Дополнительные правила (безопасность)

Весь ввод валидируется (zod в schemas.ts) до бизнес-логики.
Пароли — только bcrypt-хэш; JWT — всегда проверка подписи и срока.
Rate limiting на публичных эндпоинтах; CORS настроен явно; в production — только HTTPS.
Секреты — только через переменные окружения (.env вне git, .env.example в git).
Зависимости регулярно аудируются (npm audit).

Пример `index.ts` (публичная поверхность)

// modules/auth/index.ts — наружу только то, что нужно другим модулям
export { authService } from "./service";
export { requireAuth } from "./middleware";
export type { AuthUser } from "./types";

Чек-лист нового модуля/эндпоинта

Все 9 файлов на месте (пустые — как заготовки).
Вход валидируется в schemas, типы выведены из них.
Бизнес-логика в service, БД — только в repository.
Наружу торчит только index.ts.
Зависимости идут в одну сторону.