Обзор проекта
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, единственный файл, который поднимает все сервисы и регистрирует все маршруты. Порядок запуска имеет значение:
- База данных → Sonic → Qdrant → i18n
- Регистрация обработчиков событий
- Фоновые горутины (WebSocket-хаб, MCP-сервер, планировщик резервного копирования, уведомитель архивации)
- Регистрация маршрутов на трёх слоях роутера:
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.