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

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

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

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 Карта слоев и компонентов

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 при старте приложения.

8.3 KiB Raw Blame History Unescape Escape