Common Structure

Стандарт структуры common/ директории в goLoot backend.

Назначение

backend/src/common/ — инфраструктурный код (cross-cutting concerns), который используется во всём приложении и не принадлежит конкретному домену.

Текущая структура

common/
├── constants/          # Глобальные константы
│   ├── auth.constants.ts
│   ├── config.ts
│   ├── database.constants.ts
│   ├── http.ts
│   ├── middleware.ts
│   ├── time.constants.ts
│   ├── two-factor.constants.ts
│   ├── url.constants.ts
│   ├── validation.ts
│   └── analytics.constants.ts
├── errors/             # Base error classes
│   └── AppError.ts
├── middleware/         # Fastify middlewares
│   ├── admin-auth.middleware.ts
│   ├── error-handler.ts
│   ├── rate-limits.middleware.ts
│   └── swagger-auth.middleware.ts
├── observability/      # Логирование, метрики, трейсинг
│   ├── logger.ts
│   ├── metrics.ts
│   ├── tracing.ts
│   ├── request-context.ts
│   ├── request-logger.hook.ts
│   ├── http-client.ts
│   ├── business-events.ts
│   └── metrics.routes.ts
├── schemas/            # Базовые схемы
│   └── base.schemas.ts     # StandardResponses, Pagination
├── types/              # TypeScript типы
│   ├── fastify.d.ts
│   ├── fastify-logger.d.ts
│   ├── fastify-schema.d.ts
│   ├── jwt.types.ts
│   └── secrets.types.ts
└── utils/              # Утилиты общего назначения
    ├── analytics-counter.utils.ts
    ├── bigint-serializer.ts
    ├── chart-processor.ts
    ├── controller-utils.ts
    ├── date.utils.ts
    ├── env-validator.ts
    ├── error-handler.ts
    ├── file.utils.ts
    ├── secrets.service.ts
    └── transaction-helper.ts

Что ДОЛЖНО быть в common/

Директория	Содержимое	Примеры
constants/	HTTP статусы, лимиты, валидация	HTTP_STATUS, VALIDATION_PATTERNS
errors/	Base error classes	AppError
middleware/	Fastify middlewares	admin-auth, rate-limits, error-handler
types/	Fastify types, JWT types	fastify.d.ts, jwt.types.ts
utils/	Общие утилиты	date.utils, error-handler, transaction-helper
schemas/	Базовые схемы ответов	StandardResponses, Pagination
observability/	Логирование, метрики (подробнее)	logger, metrics, tracing

Что НЕ ДОЛЖНО быть в common/

Тип	Куда переместить
Domain-specific schemas	domains/{domain}/schemas/
Domain-specific services	domains/{domain}/services/
Domain-specific constants	domains/{domain}/constants/
Бизнес-логика (XP, calculations)	Соответствующий домен

Правило определения принадлежности

Когда код относится к common/

• Используется в 3+ доменах → возможно cross-cutting, рассмотреть common/
• Используется в 2 доменах → один из них "владелец", переместить туда
• Используется в 1 домене → переместить в домен

Пример:

• date.utils.ts — используется везде → common/
• telegram-validation.ts — только Telegram домен → domains/telegram/utils/
• xp.service.ts — только Users домен → domains/users/services/