04 — Tech Stack
Зафиксированный технический стек проекта. Любое отклонение требует ADR в docs/decisions/.
Сводная таблица
| Layer | Технология | Версия | Обоснование |
|---|---|---|---|
| Runtime | Node.js | 22.x LTS | Установлен на rigabase |
| Package Manager | npm | 10.x | Установлен; альтернативы (pnpm, bun) — на усмотрение разработчика, но без замены документации |
| Frontend Framework | Next.js | 15.x (App Router) | Лучшая поддержка Claude Code, SSR, файловый роутинг |
| Language | TypeScript | 5.x (strict) | Без any без крайней необходимости |
| Styling | Tailwind CSS | 4.x | Минимум boilerplate, дизайн-токены из Vision |
| UI Components | Базовые HTML + Tailwind | — | shadcn/ui допустим, но не обязателен |
| Backend | Next.js Server Actions + API Routes | — | Минимум boilerplate, типобезопасность end-to-end |
| Database | PostgreSQL | 16-alpine | + pgvector extension для эмбеддингов |
| ORM | Drizzle ORM | latest | Близко к SQL, типы автогенерируются |
| Migrations | Drizzle Kit | latest | Идёт в комплекте с Drizzle |
| Auth | Lucia | latest | Open-source, без vendor lock-in. Альтернатива: Auth.js |
| File Storage | MinIO (S3-compatible) | latest | Локальный Docker-контейнер, потом можно мигрировать в Yandex Object Storage |
| AI: Parsing | Anthropic API | Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5 | Прямые вызовы из бэкенда |
| AI: Embeddings | Voyage AI | voyage-3 (1024 dim) | Лучшее качество для русского текста |
| Telegram | grammY | latest | Современный TypeScript SDK |
| Transparency Site | Astro | 4.x | Статический сайт документации |
| Container | Docker + Docker Compose | 29.x | По стандарту инфраструктуры rigabase |
| Reverse Proxy | Nginx Proxy Manager | latest | Уже работает на rigabase |
| HTTPS | Let’s Encrypt | автомат через NPM | — |
| Logging | Docker logs + Sentry | — | Минимум в Phase 1 |
| Monitoring | Sentry (SaaS) | — | Для frontend + backend ошибок |
| CI/CD | GitVerse CI | — | Минимум — билд + деплой Стройплощадки |
Git хостинг
- Primary: GitVerse (
origin) - Mirror: GitHub (
mirror) - Push в оба ремоут одновременно через локальный alias или git hook
Тестирование
| Тип | Инструмент | Применение |
|---|---|---|
| Unit | Vitest | Бизнес-логика (расчёты маржи, матчинг, калькуляторы) |
| Integration | Vitest + supertest | API endpoints |
| E2E | Playwright | Критические флоу: загрузка КП, расчёт маржи, контроль подрядчика |
| Linting | ESLint | TypeScript + Next.js конфиг |
| Formatting | Prettier | Auto-format при сохранении |
| Type checking | tsc —noEmit | В CI и pre-commit |
Зависимости — критические версии
{
"next": "^15.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"typescript": "^5.5.0",
"tailwindcss": "^4.0.0",
"drizzle-orm": "^0.36.0",
"drizzle-kit": "^0.28.0",
"postgres": "^3.4.0",
"lucia": "^3.2.0",
"@anthropic-ai/sdk": "^0.30.0",
"grammy": "^1.30.0",
"pdf-parse": "^1.1.1",
"exceljs": "^4.4.0",
"minio": "^8.0.0",
"voyageai": "^1.0.0"
}
Точные версии и lock-файл — после первого npm install в app/. В этом стартовом пакете lock-файла нет.
Что не используем (и почему)
| Технология | Почему НЕ |
|---|---|
| Convex / Supabase | Vendor lock-in, серверы вне РФ |
| Prisma | На больших схемах медленнее Drizzle, бо́льший client |
| Clerk / Auth0 | Зарубежные SaaS-auth, не для российских данных |
| React Native / Expo | Mobile — Phase 2+ |
| Redux / MobX | Server-first архитектура, минимум клиентского состояния |
| Webpack / Vite напрямую | Идут в комплекте с Next.js / Astro, не настраивать вручную |
| Material UI / Ant Design | Не вписываются в дизайн-эстетику (см. Vision) |
| GraphQL | Избыточно для Phase 1 |
| Kubernetes | Избыточно для одного сервера. Docker Compose достаточно |
| pnpm workspaces / Nx / Turborepo | Phase 1 — один пакет в app/, monorepo не нужен |
| Whisper / расшифровка голоса | Phase 2 (клиент сказал — не приоритет) |
| WhatsApp Business API | Phase 2 (клиент сказал — не нужно) |
Используемые внешние API
| Сервис | Endpoint | Использование | Стоимость |
|---|---|---|---|
| Anthropic API | api.anthropic.com | Парсинг документов | $3-15 / млн токенов в зависимости от модели |
| Voyage AI | api.voyageai.com | Эмбеддинги | $0.06 / млн токенов |
| Telegram Bot API | api.telegram.org | Long-polling, отправка сообщений | Бесплатно |
| Sentry | *.sentry.io | Error reporting | Бесплатный план до 5K events/мес |
| Let’s Encrypt | автоматически через NPM | HTTPS сертификаты | Бесплатно |
Все ключи API хранятся только в .env, никогда в коде, никогда в репозитории.
Развёртывание
Локальная разработка
В Phase 1 разработка — на rigabase напрямую (через Claude Code). Локальная разработка на других машинах возможна, но не обязательна.
Если разворачивать локально для тестирования:
cd /opt/bablo
docker compose up -d
cd app
npm install
npm run dev
Production на rigabase
cd /opt/bablo
git pull
docker compose down
docker compose build
docker compose up -d
docker compose logs -f bablo-app
Подробные скрипты — в infra/scripts/.
Резервные копии
- PostgreSQL dumps ежедневно в 03:00 МСК
- MinIO sync ежедневно
- Удержание: 30 дней локально, далее опционально на внешнее хранилище
- Скрипт:
infra/scripts/backup.sh - Восстановление:
infra/scripts/restore.sh <date>
Мониторинг и алерты инфраструктуры
В Phase 1:
- Sentry — приложение и парсер
- Healthcheck в docker-compose — авто-restart упавших контейнеров
- (Опционально) Cron-задача проверяет, что бэкап создан → если нет, шлёт в Telegram-бот системного админа
В Phase 2:
- Полноценный мониторинг (Grafana + Prometheus или альтернативы)
- Alertmanager → Telegram-канал команды