Перейти к содержанию

0004 — Целевая архитектура и технологический стек

  • Дата: 2026-08-21.
  • Статус: Принято.
  • Ответственный: владелец проекта.

Контекст

После проверки frontend-прототипа потребовалось заранее определить совместимую production-архитектуру, чтобы не собирать backend, frontend и инфраструктуру как несвязанные системы и не переписывать их при каждом новом этапе.

Решение

  • Product-репозиторий остаётся npm workspaces монорепозиторием.
  • Frontend: React 19, TypeScript, Vite, React Router, TanStack Query и React Hook Form.
  • Backend: Node.js 24 LTS, TypeScript, Fastify и модульный монолит.
  • API: REST /api/v1, TypeBox, JSON Schema и OpenAPI.
  • Данные: PostgreSQL 18, Drizzle и сохранённые SQL-миграции.
  • Фоновые процессы: отдельный worker и pg-boss поверх PostgreSQL.
  • Тесты: Vitest, PostgreSQL integration tests и Playwright.
  • Развёртывание: Docker Compose, reverse proxy, health checks и неизменные image digests.
  • Redis, vector database, RAG, message broker и микросервисы не добавляются заранее.

Подробная схема хранится в docs/ARCHITECTURE.md.

Причины

Модульный монолит соответствует размеру команды и текущему продукту, сохраняет простые транзакции и позволяет выделять процессы только после доказанной нагрузки. PostgreSQL закрывает источник истины, сессии, outbox и очередь первого этапа без дополнительного runtime-кластера. React/Vite сохраняет уже созданную UI-систему; Next.js не даёт обязательной пользы для закрытого кабинета без SEO-задачи.

Последствия

  • Прежняя отсрочка постоянной архитектуры снята.
  • Точные patch-версии фиксируются при реализации, а не в этом решении.
  • Better Auth остаётся кандидатом до отдельного PoC.
  • Архитектурное решение не разрешает установку зависимостей или создание backend-кода без соответствующей задачи.
  • Полный продуктовый backend по-прежнему зависит от контрольной проверки первого сценария по решению 0008.

Откат или замена

Замена runtime, frontend-framework, PostgreSQL или модульного монолита требует нового ADR с миграционным планом. Локальную библиотеку можно заменить без изменения этого решения, если внешние контракты и принципы остаются прежними.