Integ Docs | API

Appearance

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

Integ API построен на принципах domain-driven design (DDD) и следует модульной архитектуре NestJS.

Обзор архитектуры ​

mermaid
graph TB
    Client[Client Applications]

    subgraph API[Integ API]
        Gateway[API Gateway<br/>main.ts]
        Auth[Auth Module]
        Users[Users Module]
        Integrations[Integrations Module]
        Core[Core Module]
        Shared[Shared Module]
    end

    subgraph External[External Services]
        DB[(PostgreSQL)]
        CF[Cloudflare D1/KV]
    end

    Client -->|HTTP/REST| Gateway
    Gateway --> Auth
    Gateway --> Users
    Gateway --> Integrations

    Auth --> Core
    Users --> Core
    Integrations --> Core

    Auth --> Shared
    Users --> Shared
    Integrations --> Shared

    Core --> DB
    Shared --> CF

Технологический стек ​

Core Technologies ​

  • Framework: NestJS 10.x - прогрессивный Node.js framework
  • Language: TypeScript 5.x - строгая типизация
  • Runtime: Node.js 20.x

Database Layer ​

  • Database: PostgreSQL 16 - надежная реляционная БД
  • ORM: TypeORM 0.3.x - feature-rich ORM с миграциями
  • Migrations: Автоматические миграции с версионированием

Authentication & Security ​

  • Authentication: JWT (JSON Web Tokens)
  • Authorization: Passport.js с кастомными стратегиями
  • Encryption: crypto-js для шифрования секретов
  • Password Hashing: bcryptjs

API & Documentation ​

  • API Style: RESTful
  • Validation: class-validator + class-transformer
  • Documentation: Scalar/OpenAPI 3.0
  • Versioning: URL-based (будущее)

Infrastructure ​

  • Logging: Pino - быстрое структурированное логирование
  • Events: Inngest - event processing
  • Storage: Cloudflare D1/KV - edge хранилище

Структура проекта ​

src/
├── app/                           # Приложение
│   ├── core/                     # Глобальные настройки
│   │   ├── configs/              # Конфигурации (DB, и т.д.)
│   │   ├── interceptors.ts       # Глобальные interceptors
│   │   └── core.module.ts
│   │
│   ├── shared/                   # Общие модули
│   │   ├── decorators/           # Кастомные декораторы
│   │   ├── guards/               # Переиспользуемые guards
│   │   ├── interceptors/         # Переиспользуемые interceptors
│   │   ├── modules/              # Утилитарные модули (crypto, health, logger, mcp, swagger, types)
│   │   └── utils/                # Утилиты
│   │
│   ├── auth/                     # Аутентификация
│   │   ├── access-tokens/        # Токены доступа (M2M)
│   │   ├── controllers/          # Auth контроллеры
│   │   ├── guards/               # Auth guards
│   │   └── auth.module.ts
│   │
│   ├── users/                    # Управление пользователями
│   ├── integrations/             # Управление интеграциями + handlers + prompts
│   ├── emulator/                 # Эмулятор (collections, saved-requests, proxy, secrets)
│   ├── testing/                  # Тестирование AI (scenarios, runs, schedules, chats)
│   ├── third-parties/            # Внешние сервисы (inngest, integ-core)
│   │
│   └── app.module.ts             # Корневой модуль
│
├── environments/                  # Конфигурации окружений
│   ├── environment.ts            # Активная конфигурация (генерируется)
│   └── environment.example.ts    # Шаблон
│
├── migrations/                    # TypeORM миграции
│   ├── 1000000000000-InitialSchemaClean.ts
│   └── index.ts
│
├── types/                        # TypeScript type definitions
│   └── express.d.ts              # Расширения для Express
│
├── data-source.ts                # TypeORM DataSource
└── main.ts                       # Точка входа приложения

Принципы архитектуры ​

1. Domain-Driven Design ​

Каждый домен (auth, users, integrations) — это независимый модуль со своей структурой:

[domain]/
├── controllers/      # REST endpoints
├── services/         # Business logic
├── entities/         # Database models
├── interfaces/       # TypeScript interfaces
├── dtos/            # Data Transfer Objects
└── [domain].module.ts

2. Separation of Concerns ​

  • Controllers - обрабатывают HTTP запросы, валидацию, возвращают responses
  • Services - содержат бизнес-логику
  • Entities - описывают структуру данных в БД
  • Interfaces - используются для типизации (не entity классы!)
  • DTOs - валидация и трансформация входных данных

3. Dependency Injection ​

Все зависимости инжектируются через конструктор:

typescript
constructor(
  private readonly _usersService: UsersService,
  private readonly _jwtService: JwtService
) {}

4. Single Responsibility ​

Каждый модуль/сервис отвечает за одну область функциональности.

Основные модули ​

Core Module ​

Глобальные конфигурации и bootstrapping:

  • TypeORM конфигурация
  • Глобальные interceptors

Shared Module ​

Переиспользуемые компоненты:

  • Декораторы (@CurrentUser, @Public)
  • Guards (роли, права доступа)
  • Interceptors (логирование, трансформация)
  • Утилитарные модули (Swagger, Logger)

Auth Module ​

Аутентификация и авторизация:

  • JWT стратегия
  • Sign-in/Sign-up endpoints
  • Access Token management (M2M)

Users Module ​

Управление пользователями:

  • CRUD операции с пользователями
  • User profiles
  • User verification

Integrations Module ​

Управление интеграциями:

  • Integrations - основные интеграции
  • Handlers - обработчики событий
  • Secrets - секреты для интеграций (через Secrets Module)
  • Access Tokens - токены доступа к внешним API
  • Audit - логирование изменений

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