# Стек проекта

## Принципы выбора

Стек должен одновременно:

- позволить быстро выпустить MVP;
- дать практику востребованной web-разработки;
- поддерживать realtime-функции и дальнейшее масштабирование;
- не создавать лишнюю сложность до появления реальной нагрузки;
- позволить позже разделить систему на самостоятельные GitHub-проекты.

На старте основной backend разрабатывается как модульный монолит. Realtime и обработка медиа могут быть вынесены отдельно, потому что имеют другой профиль нагрузки.

## Основной стек

### Backend

- **Go** — основной язык backend-разработки.
- **net/http** — стандартный HTTP-сервер Go.
- **chi** — легковесный маршрутизатор без скрытой магии.
- **OpenAPI 3.1** — контракт REST API и генерация документации.
- **oapi-codegen** — генерация Go-типов и серверных интерфейсов из OpenAPI.
- **pgx** — драйвер PostgreSQL.
- **sqlc** — генерация типобезопасного Go-кода из SQL.
- **golang-migrate** — миграции базы данных.
- **slog** — структурированные логи.
- **go-playground/validator** — проверка входных данных.

Такой набор дает практику работы с HTTP и SQL напрямую. Это полезнее для профессионального роста, чем начинать с тяжелого фреймворка, скрывающего устройство приложения.

### Frontend

- **React + TypeScript** — основа интерфейса.
- **Vite** — сборка и локальная разработка.
- **React Router** — маршрутизация.
- **TanStack Query** — серверное состояние, кеширование и повторные запросы.
- **React Hook Form + Zod** — формы и валидация.
- **Tailwind CSS** — стилизация и адаптивная верстка.
- **Storybook** — документация и изолированная разработка компонентов.
- **Vitest + React Testing Library** — модульные тесты.
- **Playwright** — end-to-end тесты.

Next.js пока не нужен: в MVP нет подтвержденной необходимости в SSR. При появлении требований к SEO публичную витрину можно перенести на Next.js отдельно.

### Данные

- **PostgreSQL** — основной источник данных.
- **Redis** — кеш, rate limiting, временное состояние, presence и Pub/Sub.
- **S3-совместимое хранилище** — записи, изображения и архивы.
- **MinIO** — локальная замена S3.

MongoDB не требуется: основная модель содержит связанные сущности, транзакции, кошельки и заказы, для которых PostgreSQL подходит лучше.

### Realtime и видео

- **WebSocket** — таймеры, голосования, состояние комнаты и реакции зрителей.
- **LiveKit** — WebRTC-комнаты, веб-камеры, демонстрация экрана и запись.
- **Twitch/YouTube embeds** — встроенные трансляции и чаты, где это разрешено API платформ.
- **FFmpeg** — обработка записей и создание превью.

Собственный WebRTC/SFU-сервер писать не следует: это отдельный сложный продукт, не являющийся основной бизнес-задачей.

### Асинхронные операции

- На старте: PostgreSQL jobs и transactional outbox.
- После появления нескольких потребителей событий: **NATS JetStream**.
- Kafka добавлять только при подтвержденной необходимости в большом event streaming контуре.

NATS проще в эксплуатации и одновременно дает полезный опыт очередей, доставки сообщений, повторной обработки и consumer groups.

### Авторизация и безопасность

- **OAuth 2.1 / OpenID Connect**.
- **Keycloak** для локальной разработки и самостоятельного размещения.
- Короткоживущий access token и ротация refresh token.
- RBAC для ролей: пользователь, стример, эксперт, модератор, администратор.
- Rate limiting, audit log и idempotency keys для критических команд.

### Тестирование

- **testing + testify** — unit-тесты Go.
- **Testcontainers for Go** — интеграционные тесты с PostgreSQL, Redis и NATS.
- **httptest** — тестирование HTTP API.
- **k6** — нагрузочные тесты HTTP и WebSocket.
- **golangci-lint** — статический анализ backend.
- **ESLint + Prettier** — проверка frontend.

### Наблюдаемость

- **OpenTelemetry** — единый стандарт метрик и трассировки.
- **Prometheus + Grafana** — метрики и dashboards.
- **Loki** — централизованные логи.
- **Tempo** — distributed tracing.

### Инфраструктура

- **Docker + Docker Compose** — локальная среда и первый deployment.
- **GitHub Actions** — CI/CD.
- **Caddy** — reverse proxy, HTTPS и простая конфигурация.
- **OpenTofu** — инфраструктура как код после первого deployment.
- **Kubernetes + Helm** — только после появления практической причины и результатов нагрузочного тестирования.

## Архитектура backend

Первый backend — модульный монолит со следующими модулями:

- `identity` — пользователи, роли и авторизация;
- `squads` — сквады, участники и заявки;
- `events` — конфликты, участники, раунды и статусы;
- `interactions` — опросы, голоса, таймеры и игровые механики;
- `wallets` — кошельки и неизменяемый ledger;
- `catalog` — товары, коллекции и остатки;
- `orders` — оформление и состояние заказов;
- `moderation` — проверка результатов и аудит;
- `media` — ссылки на трансляции, записи и архивы.

Внутри модулей использовать понятное разделение:

```text
internal/<module>/
  domain/
  application/
  repository/
  transport/http/
```

Не следует создавать абстракции ради формального следования Clean Architecture. Интерфейсы нужны на реальных границах: база данных, внешние API, очередь сообщений и файловое хранилище.

## Будущие GitHub-проекты

1. **bartered-api** — модульный Go-backend и основная бизнес-логика.
2. **bartered-realtime** — Go WebSocket gateway и управление состоянием live-комнат.
3. **bartered-web** — React-приложение и библиотека UI-компонентов.
4. **bartered-media** — управление LiveKit, FFmpeg и архивами.
5. **bartered-platform** — Docker Compose, CI/CD, OpenTofu, мониторинг и k6.

Разделять код физически следует после стабилизации контрактов. До этого допустимо вести разработку в одном репозитории, сохраняя границы модулей.