Integ Docs | API

Appearance

Бизнес-логика и потоки данных ​

Описание взаимодействия модулей и потоков данных в приложении.

Архитектура системы ​

mermaid
flowchart LR
    Admin["Admin Panel<br/>(React/Vue)"]
    IntegAPI["Integ API<br/>(NestJS)"]
    GatewayService["Gateway Service<br/>(HTTP клиент)"]
    IntegCore["integ-core<br/>(External API)"]
    DB["PostgreSQL<br/>(Database)"]

    Admin -->|REST API| IntegAPI
    IntegAPI -->|Proxy| GatewayService
    GatewayService -->|HTTP (x-access-token)| IntegCore
    IntegAPI -->|CRUD| DB

Основные потоки данных ​

1. Аутентификация и авторизация ​

mermaid
sequenceDiagram
    participant User as Пользователь
    participant Admin as Admin Panel
    participant Auth as Auth Module
    participant UsersService as Users Service
    participant DB as PostgreSQL

    User->>Admin: Вход (email, password)
    Admin->>Auth: POST /api/auth/sign-in
    Auth->>UsersService: Поиск пользователя
    UsersService->>DB: SELECT * FROM users
    DB-->>UsersService: User Entity
    UsersService-->>Auth: IUser Interface
    Auth->>Auth: Проверка пароля (bcryptjs)
    Auth->>Auth: Генерация JWT токена
    Auth-->>Admin: { accessToken, user }
    Admin->>Admin: Сохранение токена
    Admin->>Admin: Редирект на Dashboard

Компоненты:

  • Auth Module - логика аутентификации
  • JWT Guard - проверка токена на каждый запрос
  • Users Service - работа с пользователями в БД

Результат: Пользователь получает JWT токен, который использует для всех последующих запросов.

2. Получение списка интеграций ​

mermaid
sequenceDiagram
    participant Admin as Admin Panel
    participant IntegAPI as Integrations Module
    participant GatewayService as Gateway Service
    participant IntegCore as integ-core API

    Admin->>IntegAPI: GET /api/integrations
    IntegAPI->>IntegAPI: JWT Guard проверка
    IntegAPI->>GatewayService: listIntegrations()
    GatewayService->>IntegCore: GET /admin/integrations<br/>(Header: x-access-token)
    IntegCore-->>GatewayService: [IIntegCoreIntegration]
    GatewayService-->>IntegAPI: Результат
    IntegAPI-->>Admin: JSON с интеграциями

Компоненты:

  • Integrations Controller - REST endpoint
  • Gateway Service - HTTP клиент к внешнему API
  • integ-core - внешний сервис с интеграциями

Ключевые моменты:

  • Все запросы требуют JWT аутентификацию
  • Gateway Service использует custom header x-access-token
  • Данные проксируются напрямую от integ-core

3. Создание secret для интеграции ​

mermaid
sequenceDiagram
    participant Admin as Admin Panel
    participant IntegAPI as Secrets API
    participant SecretsService as Secrets Service
    participant CryptoModule as Crypto Module
    participant D1 as Cloudflare D1

    Admin->>IntegAPI: POST /api/secrets
    IntegAPI->>IntegAPI: JWT Guard + Validate DTO
    IntegAPI->>SecretsService: create(integration, key, value)
    SecretsService->>CryptoModule: encrypt(value)
    CryptoModule-->>SecretsService: encrypted_value
    SecretsService->>D1: INSERT INTO creds
    D1-->>SecretsService: { id }
    SecretsService-->>IntegAPI: Created Secret
    IntegAPI-->>Admin: { id, key, createdAt }

Компоненты:

  • Secrets Service - управление secrets
  • Crypto Module - шифрование чувствительных данных
  • Cloudflare D1 - хранилище secrets

Ключевые моменты:

  • Secrets шифруются перед сохранением
  • Secrets хранятся в Cloudflare D1 (таблица creds)
  • Вся коммуникация защищена JWT

4. Вызов handler интеграции ​

mermaid
sequenceDiagram
    participant Admin as Admin Panel
    participant IntegAPI as Integrations API
    participant HandlersService as Handlers Service
    participant GatewayService as Gateway Service
    participant IntegCore as integ-core

    Admin->>IntegAPI: POST /api/integrations/slack/invoke
    Admin->>IntegAPI: Body: { handler: "send_message", args: {...} }
    IntegAPI->>IntegAPI: JWT Guard + Validate DTO
    IntegAPI->>HandlersService: invokeHandler(integrationName, handler, args)
    HandlersService->>GatewayService: invokeHandler(integrationName, {...})
    GatewayService->>IntegCore: POST /admin/integrations/slack/invoke<br/>(x-access-token header)
    IntegCore-->>GatewayService: { success: true, data: {...} }
    GatewayService-->>HandlersService: Result
    HandlersService-->>IntegAPI: Результат
    IntegAPI-->>Admin: { success: true, data: {...} }

Компоненты:

  • Handlers Service - управление handlers
  • Gateway Service - проксирование к integ-core

Особенности:

  • Handlers могут иметь default arguments
  • Параметры динамичны (зависят от handler'а)
  • Все вызовы асинхронны

Роль каждого модуля в бизнес-процессе ​

Core Module ​

  • Инициализация приложения и БД
  • Конфигурация TypeORM для работы с PostgreSQL
  • Глобальные interceptors для обработки запросов

Auth Module ​

  • Регистрация новых пользователей
  • Вход (login) пользователей
  • Генерация JWT токенов
  • Проверка токенов (JWT Guard)

Users Module ​

  • Хранение информации о пользователях
  • CRUD операции с пользователями
  • Управление профилями

Integrations Module ​

  • REST API для управления интеграциями
  • Валидация входных данных (DTOs)
  • Проксирование запросов к Gateway Service

Gateway Service ​

  • HTTP клиент к integ-core
  • Управление access token для integ-core
  • Обработка ошибок при взаимодействии

Shared Module ​

  • Crypto - шифрование secrets
  • Redis - кеширование часто используемых данных
  • Swagger - документирование API
  • Base Entity - базовая структура для всех сущностей

MCP Module ​

  • AI интеграция через Model Context Protocol
  • Предоставление инструментов для AI моделей
  • Расширение функциональности для AI

Взаимодействие с integ-core ​

Архитектура ​

┌─────────────────┐
│   Admin Panel   │
└────────┬────────┘
         │ REST API
         ▼
┌─────────────────────────────────┐
│     Integ API (NestJS)          │
│  ┌───────────────────────────┐  │
│  │ Integrations Controller   │  │
│  ├───────────────────────────┤  │
│  │ Gateway Service (Proxy)   │  │
│  │ + JWT Auth + Validation   │  │
│  └───────────────────────────┘  │
└────────┬────────────────────────┘
         │ HTTP x-access-token
         ▼
┌──────────────────────────────────┐
│  integ-core (External API)       │
│  - Интеграции                    │
│  - Credentials                   │
│  - Handlers                      │
└──────────────────────────────────┘

Протокол взаимодействия ​

Аутентификация:

http
Header: x-access-token: <access-token>

Endpoints integ-core:

GET    /admin/integrations              # Список интеграций
GET    /admin/integrations/:name        # Одна интеграция
GET    /admin/integrations/:name/creds  # Credentials
POST   /admin/integrations/:name/creds  # Создать credential
PATCH  /admin/integrations/:name/creds/:key     # Обновить
DELETE /admin/integrations/:name/creds/:key     # Удалить
GET    /admin/integrations/:name/handlers       # Handlers
POST   /admin/integrations/:name/invoke         # Invoke handler

Особенности ​

  1. Полное проксирование - Integ API не хранит интеграции, только проксирует
  2. Шифрование - Secrets шифруются Crypto Module перед сохранением
  3. Кеширование - Часто используемые данные кешируются в Redis
  4. Обработка ошибок - Gateway Service обрабатывает ошибки и возвращает null

Безопасность ​

Уровни защиты ​

  1. JWT Аутентификация - Защита REST API

    • Только авторизованные пользователи
    • Проверка на каждый запрос через JWT Guard

  2. x-access-token - Защита взаимодействия с integ-core

    • Хранится в Doppler (не в коде)
    • Передается в каждом запросе к внешнему API

  3. Encryption - Защита secrets

    • Шифрование перед сохранением
    • Использование Crypto Module

  4. DTO Валидация - Защита от невалидных данных

    • class-validator для валидации
    • Отклонение некорректных запросов на уровне DTO

Производительность ​

Кеширование ​

typescript
// Redis cache через Shared Module
- Интеграции
- Secrets (с TTL)
- Handlers

// Инвалидация кеша при изменениях

Пагинация ​

typescript
// findMany всегда возвращает paginated результаты
{
  data: [...],
  totalCount: 100,
  page: 1
}

Следующие шаги ​