AGONTS

Архитектура

Под капотом: Nx monorepo, Next.js + ElysiaJS, Drizzle, BullMQ, Qdrant. Для разработчиков и интеграторов.

Раздел для разработчиков и интеграторов. Если вы бизнес-пользователь — можно пропустить.

TL;DR

Runtime

Bun + ElysiaJS + PostgreSQL + Redis + Qdrant

Frontend

Next.js 16 App Router, FSD, Eden Treaty

Schemas

Zod 4 в @agonts/contracts — общие backend + frontend

Workers

BullMQ — индексация, flow-exec, voice, chat-completion

Структура monorepo

contracts — Zod схемы, DTO, типы
db — Drizzle schema, repo-слои
eden — Eden Treaty wrapper
queue — BullMQ утилиты
events — pub-sub поверх Redis
navigation — метаданные маршрутов
utils — общие хелперы

Backend

Паттерн модуля

Каждый модуль в apps/api/src/modules/<feature>/ — controller / service / model:

index.ts — controller (Elysia plugin)
service.ts — бизнес-логика
model.ts — реэкспорт Zod-схем из @agonts/contracts

Пример:

export const agents = new Elysia({ prefix: '/agents' })
  .use(requireWorkspace)
  .get('/', async ({ workspaceId }) => ({
    items: await AgentsService.list(workspaceId),
  }), {
    response: AgentsModel.list,
  })
  .post('/', ({ workspaceId, body }) => AgentsService.create(workspaceId, body), {
    body: AgentsModel.create,
    response: AgentsModel.item,
  });

Все эндпоинты workspace-scoped через плагин requireWorkspace, читающий X-Workspace-Id.

Модули

Prop

Type

Frontend

Feature-Sliced Design

app — providers, global config
views — страницы (композиции widgets + features)
widgets — самодостаточные UI-блоки
features — пользовательские действия
entities — бизнес-сущности (api + model)
shared — api клиент, ui-кит, i18n, lib

Правило зависимостей: только вниз (views → widgets → features → entities → shared).

Eden Treaty — типобезопасный клиент

// packages/eden/src/index.ts
import type { App } from '@agonts/api';
export function createApiClient(baseUrl: string) {
  return treaty<App>(baseUrl);
}
// использование в UI
const { items } = unwrap(await api.agents.get(), 'agents.list');

Добавили endpoint в Elysia → типы сразу в UI. Ни кодогенерации, ни guard-манёвров.

База данных

Prop

Type

Все workspace-scoped таблицы имеют tenant_id uuid references tenants(id) on delete cascade. Индексы tenant_id + <sort> для быстрых page-query.

Миграции

Drizzle миграции в packages/db/drizzle/NNNN_<name>.sql. Кастомный runner packages/db/src/run-migrate.ts (обходит баг Drizzle #5316 с out-of-order timestamps).

Фоновые воркеры

Prop

Type

Голосовой runtime

  1. Клиент → WS /voice/ws?key=<API-ключ>.
  2. modules/voice/index.ts аутентифицирует ключ.
  3. Открывается VoiceSessionState.
  4. Runtime берёт default STT и default TTS из voice_providers.
  5. modules/voice/stt.ts создаёт SttStream.
  6. PCM → STT → conversation-handler → flow → LLM.
  7. Ответ → modules/voice/tts.ts → чанки клиенту.
  8. closeVoiceSession → voice_minute в usage_events.
  1. Клиент → ваш SIP-номер → АТС.
  2. АТС форкает μ-law 8 кГц на /telephony/sip-stream/ws.
  3. μ-law → PCM16 через codecs/mulaw.ts.
  4. Дальше как «Входящий веб».
  1. Flow или API → POST /telephony/dial.
  2. Runtime → default telephony провайдера.
  3. POST {baseUrl}/calls с pstn-rest-api драйвером.
  4. Оператор дозванивается → status-callback.
  5. Подняли трубку → медиа форкается в SIP-мост.

Контракты (Zod 4)

Все схемы в packages/contracts/src/schemas/. Только Zod 4 — новые API:

z.email()       // не z.string().email()
z.uuid()        // не z.string().uuid()
z.url()
z.object({ ... }).passthrough()

Zod схемы идут прямо в Elysia body/params/query/response — Elysia поддерживает Standard Schema. Типы инферятся автоматически.

События (pub-sub)

packages/events — лёгкий pub-sub поверх Redis:

  • live-обновления очереди операторов (SSE);
  • инвалидация кешей при мутациях;
  • flow-триггеры по событию.

Деплой

docker-compose.prod.yml в корне. Поднимает Postgres, Redis, Qdrant, MinIO, API, Web, Docs.

  • API — горизонтально за балансировщиком (stateless; активные WS-сессии per-instance, Redis — источник правды для общих счётчиков).
  • Postgres — managed (RDS / Yandex Cloud) с репликой.
  • Redis — managed, persistence включён.
  • Qdrant — отдельный узел с persistence.
  • Object storage — любой S3-совместимый.

Тестирование

Prop

Type

Где что искать

Prop

Type

Ссылки

Zod 4

Схемы и валидация.

ElysiaJS

API-фреймворк на Bun.

Eden Treaty

Type-safe клиент.

Drizzle

ORM для Postgres.

Nx

Monorepo-инструментарий.

MCP

Model Context Protocol.

FSD

Feature-Sliced Design.

Гид по настройкам

Экскурсия по всем 9 разделам меню «Настройки» — что где искать и настраивать.

On this page

TL;DRСтруктура monorepoBackendПаттерн модуляМодулиFrontendFeature-Sliced DesignEden Treaty — типобезопасный клиентБаза данныхМиграцииФоновые воркерыГолосовой runtimeКонтракты (Zod 4)События (pub-sub)ДеплойТестированиеГде что искатьСсылки