# 6. Техническая архитектура, стек и состав компонентов

## 6.1 Общая архитектурная схема

Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений.

<NamedMermaidDiagram name="architecture-overview" />

## 6.2 Состав прикладных сервисов

Согласно действующей карте деплоя в составе проекта используются следующие сервисы:

- `web-frontend` — клиентский и менеджерский веб-интерфейс
- `apollo-backend` — сервер GraphQL и бизнес-логика
- `vault` — централизованное хранилище секретов
- `tg-bot` — Telegram-контур
- `max-bot` — MAX-контур
- `bonus-bot` — бонусный мессенджерный контур

Основные прикладные сервисы `web-frontend` и `apollo-backend` разворачиваются через `dokploy_webhook` на сервере `main`.

## 6.3 Технологический стек фронтенда

Клиентская часть программного продукта реализуется на следующих технологиях:

- `Nuxt 4` — прикладной веб-фреймворк
- `Vue 3` — библиотека пользовательского интерфейса
- `@nuxtjs/apollo` и `@vue/apollo-composable` — работа с GraphQL
- `GraphQL Code Generator` — генерация типизированных GraphQL-документов
- `Tailwind CSS` и `daisyUI` — базовая стилизация интерфейсов
- `Storybook` — контур изоляционного просмотра компонентов
- `VitePress` — подготовка проектной документации

## 6.4 Технологический стек серверной части

Серверная часть программного продукта реализуется на следующих технологиях:

- `Node.js` — среда выполнения
- `Express 5` — HTTP-сервер
- `Apollo Server 5` — GraphQL-сервер
- `Prisma 7` — доступ к данным и ORM-слой
- `PostgreSQL` — основное хранилище данных
- `Zod` — валидация структур данных в прикладных сценариях
- `Nodemailer` — отправка уведомлений по электронной почте

## 6.5 Архитектура клиентской части

Клиентская часть организована по следующим слоям:

- страницы `app/pages` — входные экранные формы
- компоненты `app/components` — переиспользуемые элементы интерфейса
- composables `app/composables` — клиентская логика и представление данных
- GraphQL-документы `graphql/operations` — отдельные запросы и мутации
- сгенерированная типизированная схема `app/composables/graphql/generated.ts`
- серверные proxy и интеграционные обработчики `server/api`

Ключевые экранные маршруты текущей реализации:

- `/products` и `/products/[slug]` — каталог и карточка товара
- `/cart` — корзина
- `/client-orders` и `/client-orders/[id]` — клиентские заявки и заказы
- `/clients` и `/clients/[id]` — менеджерский контур клиентов
- `/orders` и `/orders/[id]` — менеджерский контур заказов
- `/catalog-settings` — административные настройки каталога
- `/bonus-program`, `/bonus-system/*` — бонусный контур

## 6.6 Карта слоев и компонентов

<NamedMermaidDiagram name="component-map" />

## 6.7 Архитектура серверной части

Серверная часть организована по следующим основным модулям:

- `src/server.js` — инициализация HTTP-сервера и GraphQL-сервера
- `src/schema.graphql` — контракт GraphQL API
- `src/resolvers.js` — реализация GraphQL-операций
- `src/context.js` — построение контекста запроса
- `src/auth.js` — аутентификация и токены доступа
- `src/access.js` — правила авторизации и проверки ролей
- `src/prisma-client.js` — точка подключения Prisma
- `src/messenger*.js`, `src/telegram*.js`, `src/max-mini-app.js` — мессенджерный контур и мини-приложения

## 6.8 Взаимодействие фронтенда и backend

Взаимодействие клиентской и серверной части строится через GraphQL API.

На стороне Nuxt используется серверный proxy-маршрут `/api/graphql`, который:

- принимает запросы браузера
- прокидывает cookie и авторизационные заголовки
- перенаправляет запрос в `apollo-backend`
- возвращает результат в клиентское приложение

Такой подход позволяет:

- изолировать прямой backend endpoint от браузерного клиента
- централизованно передавать авторизационные данные
- поддерживать единый клиентский GraphQL endpoint

## 6.9 Интеграционные и вспомогательные HTTP-точки

Помимо GraphQL API, во фронтенд-контуре реализованы вспомогательные серверные маршруты:

- `/api/graphql` — proxy в backend GraphQL API
- `/api/auth/messenger-start` — запуск сценариев messenger login / connect
- `/api/dadata/address` — подсказки адресов
- `/api/dadata/bank` — подсказки банковских реквизитов
- `/api/dadata/party` — подсказки контрагентов
- `/api/messenger-avatar/[connectionId]` — выдача изображений, связанных с мессенджерными подключениями

## 6.10 Компонентные требования к реализации

Архитектура программного продукта должна сохранять следующие правила:

- экранная логика должна находиться на уровне страниц и composables
- переиспользуемые элементы интерфейса должны быть вынесены в компоненты
- каждый GraphQL-документ должен храниться в отдельном `.graphql` файле
- клиентский код должен использовать сгенерированные типизированные документы
- серверная логика доступа к данным должна проходить через Prisma
- бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом

## 6.11 Требования к конфигурации и секретам

Сервисы программного продукта должны получать прикладные секреты из `Vault`.

В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.