Обзор проекта

Cuento разделён на три независимых репозитория. Эта статья описывает весь стек — что делает каждая часть, как они связаны и где что находится.

Репозитории

Репозиторий Язык Роль
cuento-backend Go 1.26 REST API, MCP-сервер, вся бизнес-логика
cuento-frontend TypeScript / Angular 22 SPA, раздаётся как статические файлы
cuento-cli Go Интерактивный инструмент деплоя и управления VPS

Фронтенд проксирует все API-запросы на localhost:8080 во время разработки. В продакшене Caddy управляет маршрутизацией: /api/* идёт в Go-бэкенд, всё остальное отдаётся из Angular-сборки.

Бэкенд — Go + Gin

Точка входа — main.go, единственный файл, который поднимает все сервисы и регистрирует все маршруты. Порядок запуска имеет значение:

  1. База данных → Sonic → Qdrant → i18n
  2. Регистрация обработчиков событий
  3. Фоновые горутины (WebSocket-хаб, MCP-сервер, планировщик резервного копирования, уведомитель архивации)
  4. Регистрация маршрутов на трёх слоях роутера: publicRouter, optionalAuthRouter, protectedRouter

Пакеты в src/:

Пакет Роль
Controllers/ HTTP-хендлеры — один файл на домен, без бизнес-логики
Services/ Вся бизнес-логика и обёртки внешних клиентов
Entities/ Типы-структуры, отражающие таблицы БД
Middlewares/ Аутентификация, права доступа, rate limiting, обработка ошибок
Events/ + EventHandlers/ Внутрипроцессная шина pub/sub — хендлеры запускаются в горутинах, не блокируют запросы
MCP/ MCP-сервер на :8081
Features/ Опциональные модули: ИИ-агент, дайджест игры, валюта, рейтинг постов
Install/ permissions.csv и local_migration.go

База данных — MariaDB

Схемой управляет src/Install/local_migration.go, который вычисляет разницу между Go-структурами сущностей и живой базой данных. Запуск генерирует SQL миграции — изменения никогда не применяются автоматически. Все операции, затрагивающие несколько таблиц, используют транзакции.

Полнотекстовый поиск — Sonic

Sonic — лёгкий поисковый бэкенд для быстрых полнотекстовых запросов. Посты, персонажи и лор индексируются через обработчики событий, срабатывающие после каждой записи. Go-клиент: expectedsh/go-sonic.

Семантический поиск — Qdrant

Qdrant — векторная база данных для семантического поиска: поиск постов и лора по смыслу, а не только по точным ключевым словам. Текст эмбеддируется и сохраняется в Qdrant через ту же пайплайн обработчиков событий. Go-клиент: qdrant/go-client.

Оба поисковых бэкенда запрашиваются совместно: Sonic — для точных совпадений, Qdrant — для «найди похожие сцены».

ИИ — MCP + настраиваемый провайдер

ИИ-слой состоит из двух частей:

MCP-сервер запускается на :8081 с использованием библиотеки mcp-go. Он предоставляет инструменты для работы с лором и поиска, которые может вызывать любой MCP-совместимый ИИ-клиент. ИИ-чат в фронтенде Cuento подключается к этому серверу.

Пул моделей настраивается во время работы без перезапуска. Поддерживается два источника:

  • OpenRouter — загружает актуальный каталог моделей из OpenRouter, фильтрует по поддержке инструментов и контекстному окну, всегда использует OpenAI-совместимый клиент независимо от провайдера модели.
  • DB-пул — таблица ai_models, по одной строке на модель. Поля: api_address, api_key, machine_name, size (1–4), protocol_type (1 = OpenAI-compat, 2 = Anthropic, 3 = Gemini), is_active. Работает с любым OpenAI-совместимым эндпоинтом, включая Groq, а также нативно с Anthropic и Gemini.

Активный пул — глобальный интерфейс ModelPool, атомарно заменяемый через SwitchPool(). Каждая задача запрашивает модель по минимальному размеру; пул возвращает самую дешёвую подходящую. При ошибке rate limit автоматически выбирается следующая доступная модель через ClientExcluding.

Фронтенд — Angular 22

Фронтенд построен на основе сигналов. Состояние управляется с помощью signal(), computed() и effect() — не смешивайте сигналы с BehaviorSubject для одного и того же состояния.

Все маршруты загружаются лениво через loadComponent. Файл маршрутов: src/app/app.routes.ts. Сервисы для работы с бэкендом находятся в src/app/services/. Общие компоненты — в src/app/components/.

Известная особенность: в компонентах, активно использующих сигналы, привязки обычных массивов и объектов пропускаются при ре-рендерах, нацеленных на сигналы. Оборачивайте значения в signal() или computed(), если они должны реагировать на изменения.

Real-time — WebSockets

Хаб на основе Gorilla WebSocket (src/Websockets/hub.go) обеспечивает доставку уведомлений, обновлений активности пользователей и изменений постов в реальном времени. Аутентификация WebSocket-соединений выполняется отдельным middleware.

Шина событий

Events.Publish(db, EventType, data) диспетчеризует асинхронно — каждый обработчик запускается в собственной горутине и никогда не блокирует HTTP-запрос, который его вызвал. Все типы событий и структуры payload объявлены в src/Events/event_bus.go. Обработчики подключаются один раз при запуске через EventHandlers.RegisterEventHandlers().

Именно так индексирование в Sonic, создание эмбеддингов в Qdrant, push-уведомления и WebSocket-трансляции остаются независимыми от контроллеров, которые их инициируют.

Деплой — Cuento CLI

CLI проводит через 21-шаговый мастер: форкает репозитории на ваш GitHub-аккаунт, настраивает GitHub Actions для CI/CD, подготавливает VPS и устанавливает полный продакшен-стек: Caddy в качестве обратного прокси, MariaDB и Go-бэкенд как systemd-сервис. После первоначальной настройки деплои запускаются пушем в ветку release — SSH в продакшен не требуется.

Лицензия

Cuento распространяется под лицензией Apache License 2.0. Вы можете свободно использовать, изменять и распространять его — в том числе в коммерческих целях — при условии сохранения оригинального уведомления об авторских правах и текста лицензии. Лицензия не предоставляет права на использование названия и товарных знаков Cuento. Полный текст: apache.org/licenses/LICENSE-2.0.