# Оценка текущего стека Qadam

## Паспорт документа

- Статус документа: historical snapshot
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при следующей крупной ревизии стека или архитектурного контура
- Область применения: зафиксированная оценка пригодности текущего стека на момент аудита
- Связанные документы:
  - [Текущее состояние](../project/current-state.md)
  - [Roadmap](../project/roadmap.md)
  - [Платформенный design](../../specs/qadam-platform/design.md)

_Актуализировано на 28 марта 2026 года._

## 1. Краткое заключение

Текущий стек Qadam в целом подходит для всех ближайших и среднесрочных планов проекта: MVP, buyer/seller/admin core, CRM v1.0, billing, публичный каталог, seller dashboard и первые мобильные клиенты.

Главный вывод:

- ядро стека менять не нужно;
- переписывать проект на другой backend/frontend/runtime сейчас нецелесообразно;
- узкие места проекта сейчас находятся не в выборе языка или фреймворка, а в зрелости процессов, quality gates, фоновых задачах, storage и наблюдаемости.

Иными словами: проблема проекта сейчас не "не тот стек", а "стек нормальный, но экосистема вокруг него ещё не доведена до уровня следующей фазы роста".

## 2. Фактический стек проекта

### Прикладной слой

- Frontend: Next.js 16 + React 19 + App Router
- Backend: NestJS 10 + Fastify
- Язык: TypeScript
- Репозиторионная модель: split `qadam-core` + `qadam-web` с сохранённым workspace/DX-наследием `pnpm`

### Слой данных

- Основная БД: PostgreSQL
- ORM: Prisma
- Кэш и infra state: Redis (`ioredis`)

### Общие контракты

- Общие типы и схемы: `@repo/shared`
- Валидация: Zod

### Frontend: состояние и UX

- Server state: TanStack Query
- i18n: `next-intl`
- UI/state helpers: Radix UI, React Context для catalog filters, Tailwind CSS 4, SVGR

### Логирование и эксплуатация

- Логирование: Pino + `nestjs-pino`
- Внешний лог-транспорт: Axiom, опционально
- Production runtime на текущем сервере: `systemd` + `nginx` + host PostgreSQL/Redis

## 3. Насколько стек подходит под текущий этап

### 3.1. Для MVP и стабилизации

Подходит хорошо.

Почему:

- один язык на весь стек ускоряет разработку;
- разделение на `qadam-core` и `qadam-web` уже выполнено, но общая contract-driven модель и `pnpm`-экосистема всё ещё удобны для быстрой итерации;
- NestJS хорошо подходит для доменного backend с кабинетами, ролями, модерацией и billing-логикой;
- Next.js хорошо подходит для публичного SEO-каталога и кабинетов в одном проекте;
- PostgreSQL и Redis более чем достаточны для текущего масштаба.

Вывод:

- для ближайших 6-12 месяцев стек менять не нужно;
- основные усилия должны идти не в rewrite, а в стабилизацию и completion существующих потоков.

### 3.2. Для кабинетов buyer/seller/admin

Подходит хорошо.

Почему:

- NestJS удобно держит модульную структуру `auth`, `buyer`, `seller`, `admin`, `lead`, `review`, `reference`;
- общие Zod-схемы между backend и frontend снижают дрейф контрактов;
- TanStack Query хорошо закрывает кабинетные сценарии с мутациями и инвалидацией данных;
- App Router и SSR позволяют держать публичную и приватную часть в одном web-приложении.

Ограничение:

- сейчас bottleneck не в стеке, а в UX-полировке, тестовом покрытии и консистентности потоков.

### 3.3. Для CRM v1.0

Подходит, но уже с оговорками.

CRM-функции вроде календаря, расписания, групп, клиентов, ролей и бронирований можно реализовать на текущем стеке без смены ядра.

Почему:

- PostgreSQL хорошо подходит под транзакционные данные расписания, бронирований, ролей и клиентов;
- NestJS и Prisma достаточно удобны для бизнес-правил и transactional writes;
- Next.js подходит для seller-facing CRM UI.

Что понадобится добавить:

- нормальный background jobs layer;
- более дисциплинированный domain design для расписаний, booking conflicts и audit trail;
- более сильный e2e-контур для кабинетных сценариев.

Вывод:

- для CRM стек менять не надо;
- но без слоя фоновых задач и системной тестовой дисциплины CRM начнёт быстро усложнять проект.

### 3.4. Для биллинга и платежей

Подходит условно.

Billing и payment flows на текущем стеке реализуемы, но требуют не смены стека, а усиления инфраструктурных практик.

Что хорошо:

- PostgreSQL подходит для инвойсов, статусов, проводок, reconciliation и audit trail;
- NestJS подходит для интеграций с платёжными шлюзами и webhook processing;
- Redis можно использовать для idempotency, rate limiting и технических блокировок.

Что обязательно нужно до внедрения платежей:

- queue/job system;
- outbox/idempotency patterns;
- error tracking и alerting;
- строгая модель финансовых статусов и неизменяемых записей.

Вывод:

- стек подходит;
- до платежей нужно дорастить инженерную зрелость, а не менять язык или фреймворк.

### 3.5. Для мобильного направления

Подходит.

Причины:

- backend уже живёт как API-ориентированный слой;
- TypeScript и React-экосистема естественно ведут к React Native / Expo как самому экономичному пути;
- shared contracts можно частично использовать и для mobile-клиента.

Рекомендация:

- если mobile действительно пойдёт в ближайшие этапы, не менять backend;
- в качестве мобильного стека сначала смотреть в сторону React Native / Expo, а не отдельной новой backend-архитектуры.

### 3.6. Для аналитики и роста

Текущее OLTP-ядро подходит только частично.

Здесь важно разделять два слоя:

- операционный контур;
- аналитический контур и витрины.

Operational stack на PostgreSQL + Prisma + NestJS подходит.
Но для серьёзной аналитики, seller dashboards, cohort/funnel, PMF metrics и billing-аналитики со временем нужен отдельный аналитический контур.

Текущий EventLog и CDC-заготовки — это хороший старт, но не конечное решение.

Вывод:

- менять основной стек не нужно;
- аналитика должна развиваться как отдельная подсистема, а не как перегрузка основной PostgreSQL-базы.

## 4. Сильные стороны текущего стека

### Единый TypeScript-контур

Это сильное решение для текущей команды и стадии продукта.

Плюсы:

- быстрее онбординг;
- меньше переключения контекста;
- проще разделять DTO, схемы и типы;
- меньше накладных расходов на MVP и ранний рост.

### Next.js + NestJS

Это хорошая пара для продукта, где одновременно есть:

- публичный SEO-каталог;
- кабинетная логика;
- доменный backend с ролями и модулями;
- перспектива mobile API.

### PostgreSQL + Prisma

Для текущего и среднесрочного масштаба это хороший выбор.

Плюсы:

- транзакционность;
- предсказуемость;
- простая эксплуатация;
- хорошая скорость команды;
- возможность эволюции схемы по мере роста.

### Redis

Подходит как вспомогательный инфраструктурный слой.

Уже сейчас полезен для:

- refresh token storage;
- кэша;
- технических блокировок и rate limiting.

Потенциально полезен и дальше для job queues.

### Split-репозитории с общим контрактным контуром

Для текущего размера команды и платформы уже более уместна не монорепо-модель, а связка двух репозиториев:

- `qadam-core` для backend, Prisma, OpenAPI и канонической документации;
- `qadam-web` для frontend и web delivery.

Сильная сторона здесь не в самом факте разделения, а в том, что контракт между ними уже формализуется через OpenAPI и shared engineering workflow.

Это упрощает:

- передачу проекта отдельной frontend-команде;
- автономную эволюцию web и backend;
- сохранение единого contract layer без runtime-сцепки репозиториев.

## 5. Слабые места и риски текущего стека

### 5.1. Слишком "свежий" frontend-инструментарий

Связка:

- Next.js 16
- React 19
- Tailwind 4
- React Compiler
- Turbopack

сама по себе рабочая, но более рискованная по сравнению с консервативным production-набором.

Вывод:

- это не повод делать rewrite;
- но это повод жёстко фиксировать версии и не обновлять frontend toolchain без реальной необходимости.

### 5.2. Нет полноценного web-тестового контура

Сейчас это один из самых слабых участков проекта.

Проблема:

- стек подходит, но не защищён от регрессий в UI и end-to-end потоках.

Это не проблема выбора Next.js.
Это проблема незавершённой инженерной обвязки.

### 5.3. Отсутствует нормальный слой фоновых задач и workflow

Для следующих фаз проекта он обязателен.

Без него начнут болеть:

- уведомления;
- webhooks;
- платежи;
- биллинг;
- экспорты;
- фоновые пересчёты;
- аналитические CDC-процессы.

### 5.4. Локальное файловое хранение не годится для долгосрочного production

Для roadmap-портала локальное хранение допустимо.
Для основного продукта, медиа и seller content в долгую это слабое место.

Нужен переход на object storage.

### 5.5. Наблюдаемость пока не дотягивает до следующей фазы

Pino и Axiom — хороший старт, но для CRM, billing и mobile этого недостаточно.

Нужны:

- error tracking;
- алерты;
- service-level мониторинг;
- более чёткий operational runbook;
- post-deploy smoke automation.

### 5.6. Конфигурационный дрейф между хостовым деплоем и Docker-деплоем

Это не flaw самого стека, но серьёзный operational risk.

Если его не убрать, команда будет спорить не о продукте, а о том, какой runtime вообще является настоящим production.

## 6. Нужно ли менять стек

### Короткий ответ

Нет, ядро стека менять не нужно.

### Не нужно менять

- TypeScript как основной язык
- split `qadam-core` / `qadam-web`
- Next.js как основную web-платформу
- NestJS как backend-платформу
- PostgreSQL как основную операционную базу данных
- Prisma как основной ORM
- Redis как инфраструктурный слой для кэша и токенов

### Нужно не менять, а усилить

- тестовую инфраструктуру;
- deploy pipeline;
- background jobs;
- object storage;
- observability;
- аналитический контур.

## 7. Что стоит добавить в стек без переписывания ядра

### Добавить в ближайший этап

- Playwright для web smoke/e2e
- error tracking уровня Sentry или аналогичного сервиса
- job queue: BullMQ как наиболее естественное продолжение при уже используемом Redis
- object storage: S3-совместимое хранилище для медиа и файлов

### Добавить в среднесрочной перспективе

- outbox/idempotency patterns для billing и payments
- отдельный analytics stack или warehouse
- feature flags / release controls
- uptime и TLS monitoring

### Добавлять только при реальной необходимости

- Elasticsearch / OpenSearch / Meilisearch для поиска
- workflow engine
- event bus / Kafka-подобную инфраструктуру
- микросервисы

Сейчас всё это преждевременно.

## 8. Что точно не стоит делать сейчас

- Не переписывать backend на Go, Java, Python или другой стек ради "масштабируемости".
- Не выносить модули в микросервисы.
- Не менять PostgreSQL на NoSQL в качестве основного transactional store.
- Не заменять Next.js только потому, что есть отдельные проблемы с hydration или CSS.
- Не вводить сложную распределённую архитектуру раньше, чем появится реальная организационная и нагрузочная потребность.

## 9. Практическая рекомендация по фазам

### Фаза 1. Сейчас

- Оставить ядро без изменений.
- Закрыть quality gates, buyer/seller/admin core и ops drift.

### Фаза 2. Перед CRM и биллингом

- Добавить job queue.
- Добавить object storage.
- Добавить web e2e/smoke.
- Усилить monitoring/error tracking.

### Фаза 3. Перед ростом и аналитикой

- Развести operational и analytical контуры по-настоящему.
- Не грузить основную БД тяжёлой BI-аналитикой.

### Фаза 4. Перед масштабированием mobile

- Зафиксировать API contract discipline.
- При необходимости вынести mobile-specific API-адаптации, но не переписывать backend.

## 10. Итоговое заключение

Текущий стек для Qadam выбран в целом правильно.

Он:

- хорошо подходит для текущего ядра продукта;
- подходит для CRM и billing без смены платформы;
- подходит для mobile как backend-основа;
- требует не смены, а инженерного усиления вокруг себя.

Если формулировать жёстко:

- **rewrite не нужен**;
- **migration на другой стек не оправдана**;
- **правильная стратегия — сохранить ядро и последовательно усиливать подсистемы вокруг него**.