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, jwt, cors, database + index.ts
├── config/
│   ├── env.ts
│   └── index.ts
├── modules/
│   ├── auth/               # controller, service, repository, routes,
│   ├── users/              # schemas, dto, types, middleware, index.ts
│   ├── 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`.
- [ ] Зависимости идут в одну сторону.