Document infrastructure and dependency inventory

docs/.vitepress/theme/components/diagramSources.ts

@@ -66,6 +66,57 @@ export const diagramSources: Record<string, string> = {
     Resolvers --> Prisma
     Prisma --> PrismaSchema
     Prisma --> Db`,
+  'infrastructure-topology': `flowchart TB
+    subgraph Repo[Репозиторий fregat]
+      FrontendRepo[web-frontend]
+      BackendRepo[apollo-backend]
+      TgRepo[tg-bot]
+      MaxRepo[max-bot]
+      BonusRepo[bonus-bot]
+      WorkerRepo[hatchet-worker]
+      VaultRepo[vault]
+    end
+
+    subgraph Dokploy[Dokploy]
+      FrontendSvc[web-frontend service]
+      BackendSvc[apollo-backend service]
+      TgSvc[tg-bot service]
+      MaxSvc[max-bot service]
+      BonusSvc[bonus-bot service]
+      WorkerSvc[hatchet-worker service]
+      VaultSvc[vault service]
+    end
+
+    subgraph Infra[Инфраструктурный контур]
+      VaultData[Vault raft storage /vault/data]
+      BackendDb[(PostgreSQL for app)]
+      HatchetEngine[Hatchet engine]
+      HatchetPg[(PostgreSQL for Hatchet)]
+      OneC[1С]
+      Tailscale[Tailscale SSH / diagnostics]
+    end
+
+    FrontendRepo --> FrontendSvc
+    BackendRepo --> BackendSvc
+    TgRepo --> TgSvc
+    MaxRepo --> MaxSvc
+    BonusRepo --> BonusSvc
+    WorkerRepo --> WorkerSvc
+    VaultRepo --> VaultSvc
+
+    FrontendSvc --> BackendSvc
+    BackendSvc --> BackendDb
+    BackendSvc --> VaultSvc
+    TgSvc --> VaultSvc
+    MaxSvc --> VaultSvc
+    BonusSvc --> VaultSvc
+    WorkerSvc --> VaultSvc
+    VaultSvc --> VaultData
+    WorkerSvc --> HatchetEngine
+    HatchetEngine --> HatchetPg
+    BackendSvc -.exchange.-> OneC
+    FrontendSvc -.ops / debug.-> Tailscale
+    BackendSvc -.ops / debug.-> Tailscale`,
   'database-model': `classDiagram
     direction LR
 

docs/tz/technical-architecture.md

@@ -125,3 +125,150 @@
 Сервисы программного продукта должны получать прикладные секреты из `Vault`.
 
 В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.
+
+## 6.12 Инфраструктура, деплой и эксплуатационный контур
+
+Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур.
+
+<NamedMermaidDiagram name="infrastructure-topology" />
+
+Сервисы проекта и способ их развёртывания:
+
+| Сервис | Путь в репозитории | Роль | Deploy mode | Сервер |
+| --- | --- | --- | --- | --- |
+| web-frontend | `web-frontend` | клиентский и менеджерский веб-интерфейс | `dokploy_webhook` | `main` |
+| apollo-backend | `apollo-backend` | GraphQL API и бизнес-логика | `dokploy_webhook` | `main` |
+| hatchet-worker | `hatchet-worker` | фоновый worker-контур | `dokploy_webhook` | `main` |
+| tg-bot | `tg-bot` | Telegram-контур | `dokploy_webhook` | `main` |
+| max-bot | `max-bot` | MAX-контур | `dokploy_webhook` | `main` |
+| bonus-bot | `bonus-bot` | бонусный сервис | `dokploy_webhook` | `main` |
+| vault | `vault` | сервис секретов | `dokploy_webhook` | `main` |
+
+Серверная карта текущего проекта:
+
+- сервер `main`
+- Tailscale user: `root`
+- Tailscale host: `dsrptlab`
+
+Эксплуатационные операции доступа и диагностики выполняются через Tailscale SSH.
+
+## 6.13 Dokploy и цепочка развёртывания
+
+Для основных сервисов проекта используется режим `dokploy_webhook`.
+
+Это означает следующую последовательность:
+
+1. изменения фиксируются в Git-репозитории;
+2. изменения публикуются в `main`;
+3. Dokploy получает webhook-событие;
+4. Dokploy выполняет сборку соответствующего сервиса;
+5. сервис перезапускается с загрузкой секретов из Vault;
+6. после старта выполняются bootstrap-действия, предусмотренные образом и entrypoint-командой.
+
+Текущие особенности прикладных сервисов:
+
+- `web-frontend` стартует через загрузку Vault env и запуск `.output/server/index.mjs`
+- `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js`
+- bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js`
+
+## 6.14 Vault и хранение секретов
+
+Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`.
+
+Текущие инфраструктурные правила работы Vault:
+
+- используется `raft` storage
+- данные Vault сохраняются в `/vault/data`
+- конфигурация сервиса хранится в `vault/config/vault.hcl`
+- при старте выполняется проверка и, при необходимости, автоматический unseal из переменных окружения
+- прикладные сервисы подключаются к Vault через bootstrap-переменные `VAULT_ADDR`, `VAULT_TOKEN`, `VAULT_KV_MOUNT`, `VAULT_SHARED_PATH`, `VAULT_PROJECT_PATH`, `VAULT_ENABLED`
+
+Прикладные сервисы используют общий shell-bootstrap `load-vault-env.sh`, который:
+
+- ожидает доступность Vault по health endpoint
+- загружает shared secrets
+- загружает project secrets
+- экспортирует секреты в runtime environment процесса
+
+## 6.15 Структура сервисных каталогов
+
+Текущая сервисная структура репозитория:
+
+- `web-frontend` — Nuxt-приложение, GraphQL operations, VitePress-документация
+- `apollo-backend` — Apollo Server, Prisma schema, миграции, импорт каталога
+- `tg-bot` — Telegram-сервис
+- `max-bot` — MAX-сервис
+- `bonus-bot` — бонусный сервис
+- `hatchet-worker` — worker-контур
+- `vault` — Dockerfile, конфигурация и entrypoint Vault
+- `hatchet` — docker-compose инфраструктурного контура Hatchet
+
+## 6.16 Контур фоновых процессов
+
+В проекте присутствует отдельный контур фонового исполнения задач:
+
+- `hatchet-worker` как прикладной worker
+- `hatchet-engine` как движок исполнения
+- `hatchet-dashboard` как интерфейс мониторинга
+- отдельный `postgres` для Hatchet-контура
+
+Конфигурация этого контура находится в `hatchet/docker-compose.yml`.
+
+## 6.17 Зафиксированные runtime-версии и технологические зависимости
+
+### Базовые runtime и контейнерные образы
+
+| Компонент | Текущая версия |
+| --- | --- |
+| Node base image для web/backend/bots | `node:22-bookworm-slim` |
+| Vault image | `hashicorp/vault:1.21.3` |
+| Hatchet Postgres | `postgres:15.6` |
+| Nuxt | `4.4.2` |
+| Vue | `3.5.30` |
+| Apollo Server | `5.5.0` |
+| Prisma / Prisma Client | `7.6.0` |
+| Mermaid | `11.14.0` |
+| VitePress | `1.6.4` |
+
+### Основные зависимости фронтенда
+
+| Библиотека | Версия | Назначение |
+| --- | --- | --- |
+| `@nuxtjs/apollo` | `5.0.0-alpha.16` | GraphQL-клиентский слой |
+| `@vue/apollo-composable` | `4.2.2` | composable API для GraphQL |
+| `@apollo/client` | `3.14.1` | Apollo client runtime |
+| `@nuxt/eslint` | `1.15.2` | linting Nuxt-проекта |
+| `@nuxtjs/tailwindcss` | `6.14.0` | Tailwind integration |
+| `daisyui` | `5.5.19` | UI primitives |
+| `graphql` | `16.13.2` | GraphQL runtime |
+| `@sentry/vue` | `10.46.0` | error tracking |
+| `storybook` | `8.6.14` | UI component review |
+
+### Основные зависимости backend
+
+| Библиотека | Версия | Назначение |
+| --- | --- | --- |
+| `@apollo/server` | `5.5.0` | GraphQL server |
+| `@as-integrations/express5` | `1.1.2` | Apollo + Express integration |
+| `express` | `5.2.1` | HTTP server |
+| `@prisma/client` | `7.6.0` | data access |
+| `@prisma/adapter-pg` | `7.6.0` | Prisma adapter |
+| `pg` | `8.20.0` | PostgreSQL driver |
+| `graphql` | `16.13.2` | GraphQL runtime |
+| `zod` | `4.3.6` | validation |
+| `nodemailer` | `8.0.4` | email notifications |
+| `dotenv` | `17.3.1` | env bootstrap in local/runtime layers |
+
+## 6.18 Технические конфигурационные файлы
+
+Ключевые технические файлы текущей реализации:
+
+- `deploy-map.toml` — карта сервисов, deploy mode и серверов
+- `web-frontend/nuxt.config.ts` — конфигурация Nuxt и Apollo
+- `web-frontend/codegen.ts` — конфигурация GraphQL codegen
+- `apollo-backend/prisma.config.ts` — конфигурация Prisma
+- `apollo-backend/prisma/schema.prisma` — модель данных
+- `web-frontend/scripts/load-vault-env.sh` — Vault bootstrap frontend
+- `apollo-backend/scripts/load-vault-env.sh` — Vault bootstrap backend
+- `vault/config/vault.hcl` — конфигурация Vault
+- `vault/entrypoint.sh` — startup/unseal логика Vault