Технологический стек
Зачем нужно
Документ фиксирует обязательный технологический стек, в котором реализуется экосистема. Стек выбран один на всю платформу, чтобы домены были взаимозаменяемы по навыкам разработчиков и инфраструктуре.
Backend
| Слой | Технология | Версия |
|---|---|---|
| Язык | TypeScript | 5.4+ |
| Runtime | Node.js | 22 LTS |
| Фреймворк | NestJS | 10+ |
| Менеджер пакетов | pnpm | 9+ |
| ORM | Prisma | 5+ |
| Валидация | Zod | 3+ |
| Логирование | pino | 9+ |
| HTTP-клиент | undici (через NestJS HttpModule) | — |
| Очереди / шина | Redis Streams через BullMQ для задач, NATS JetStream для domain events; Kafka допустима только через будущий ADR | — |
| Кэш | Redis | 7+ |
| Тесты | Vitest, supertest | — |
Все 7 доменов используют один backend-стек. Любое отклонение — через ADR.
База данных
| Назначение | Технология |
|---|---|
| Основная OLTP | PostgreSQL 16+ |
| Кэш и сессии | Redis 7+ |
| Поиск | PostgreSQL FTS / pg_trgm, Meilisearch для расширенного поиска по витрине и task-bank |
| Аналитика | ClickHouse (опционально для management; стартуем с PostgreSQL + materialized views) |
| Файлы | S3-совместимое хранилище (MinIO в dev, S3 в prod) |
Подробности conventions: data-baseline.md.
Frontend
| Слой | Технология |
|---|---|
| Язык | TypeScript 5.4+ |
| Фреймворк | Next.js 14+ (App Router) |
| UI-библиотека | React 18+ |
| State | TanStack Query, Zustand |
| Формы | React Hook Form + Zod |
| Стили | CSS Modules + общие токены (platform/ui-system.md); Tailwind не используется для приложений, допускается для лендингов витрины |
| Сборка | Turbopack (Next.js native) |
| Тесты | Vitest, Playwright |
| Иконки | shared icon set из UI Kit |
Витрина может использовать дополнительный SSG-режим Next.js или отдельный тонкий сервер (Astro) — решается через ADR на этапе разработки storefront.
Инфраструктура
| Назначение | Технология |
|---|---|
| Контейнеры | Docker, Docker Compose в dev |
| Оркестрация | Kubernetes (target prod) |
| CI | GitHub Actions |
| Реестр образов | GHCR / private registry |
| Секреты | Kubernetes Secrets + sealed-secrets, dev — .env (никогда в git) |
| Мониторинг | OpenTelemetry → Grafana + Prometheus + Loki + Tempo |
| Errors | Sentry |
| Email/SMS | внешние транспорты, абстракция в identity (transports.md) |
Языки и инструменты разработки
- pnpm workspaces для монорепо;
- ESLint + Prettier с общим preset;
- Commitlint и conventional commits;
- Changesets для версионирования внутренних пакетов;
- Husky/lefthook опционально для локальных хуков;
- Renovate для зависимостей.
Структура монорепо
systematika/
├── apps/
│ ├── identity-api/
│ ├── identity-admin-web/
│ ├── storefront-api/
│ ├── storefront-web/
│ ├── crm-api/
│ ├── crm-web/
│ ├── lms-api/
│ ├── lms-web/
│ ├── task-bank-api/
│ ├── task-bank-web/
│ ├── competitions-api/
│ ├── competitions-web/
│ ├── management-api/
│ └── management-web/
├── packages/
│ ├── api-contracts/ # общие DTO и Zod-схемы
│ ├── auth-client/ # клиент identity для других доменов
│ ├── events-bus/ # клиент шины событий
│ ├── reference-data/ # справочники subject/level/format
│ ├── ui-kit/ # общие React-компоненты и токены
│ ├── observability/ # logger, tracer, metrics
│ ├── permissions/ # модель permissions и проверки
│ └── testing/ # фикстуры и хелперы
├── infra/
│ ├── docker/
│ ├── k8s/
│ └── migrations/
└── docs-site/
Что запрещено
- Использовать в одном домене другой backend-фреймворк или язык без ADR.
- Реализовывать собственный логгер, формат ошибок, валидатор поверх Zod внутри домена.
- Подключать ORM, отличный от Prisma, без ADR.
- Использовать собственные UI-токены и компоненты, дублирующие UI Kit.
- Хранить секреты в коде, конфигах репозитория или в
.env.exampleс реальными значениями.