Backend Architecture

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

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

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

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

## Структура каталогов
```
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** — что модуль отдаёт наружу. Другие модули импортируют ТОЛЬКО отсюда.

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

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

## Пример `index.ts` (публичная поверхность)
```ts
// modules/auth/index.ts — наружу только то, что нужно другим модулям
export { authService } from "./service";
export { requireAuth } from "./middleware";
export type { AuthUser } from "./types";
```

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