Архитектура (обзор для разработчиков и ИИ)¶

TL;DR¶

Geni AI — это связка Telegram → n8n → Supabase → WebApps (Cloudflare Pages) → обратно в Telegram.
Вход всех событий — Telegram-бот. Вся маршрутизация и бизнес-логика — в n8n. Данные пользователей, баланс/кошелёк и задачи — в Supabase. Веб-страницы на Cloudflare Pages служат мини-приложениями и передают параметры обратно в n8n. Вызовы моделей идут из n8n, результаты возвращаются в Telegram.

1) Слои (C4-контекст, укрупнённо)¶

Пользователь / Telegram — команды, сообщения, фото, запуск WebApp.
n8n (Hub + Tool workflows) — центральный маршрутизатор:
Hub (входной воркфлоу, имя начинается с Geni_AI…) принимает апдейты, проверяет баланс, выбирает Tool и запускает сценарий.
Tool workflows — сценарии под конкретные режимы/модели (например, seedream).
Supabase — таблицы users, wallet_tx, tasks и пр.; RPC-функции get_tool_price_credits, wallet_debit, ensure_user и др.
WebApps (Cloudflare Pages) — мини-страницы (например, tgmenu) для выбора настроек; возвращают параметры в n8n.

Полезные разделы: - Каталог воркфлоу n8n: /workflows/ - Обзор БД (таблицы/функции): /data/generated/overview/ - Каталог WebApps: /webapps/

2) Контракты данных (ключевые поля)¶

Из Telegram: chatId, message_id, file_id (photo/document), caption/text.
Внутри n8n (унифицированный объект):
chatId, tool, prompt, files[] (из file_id или dataUrl), price, balance, reply_to_message_id, settings_seedream (quality, ratio, dims_t2i, long_edge_i2i).
RPC Supabase (смысл):
get_tool_price_credits(tool, feature) → цена в кредитах;
wallet_debit(user_id, amount) → списание средств;
ensure_user(tg_user_id, ...) → создание/поиск пользователя и базовых настроек.
WebApps → n8n: режим t2i/i2i, настройки качества/соотношения, привязка к chatId, иногда ссылки/данные изображения.

3) Типовые последовательности¶

Text-to-Image (t2i):
Telegram: пользователь отправляет текст;
n8n Hub: определяет tool, спрашивает get_tool_price_credits, делает wallet_debit;
Tool workflow: формирует запрос к провайдеру модели, получает URL изображения;
Telegram: отсылает результат пользователю.
Image-to-Image (i2i):
Пользователь присылает фото (может накапливаться в «корзине»), затем текст;
n8n: нормализует вход (массива images), выбирает целевую «длинную сторону» (long_edge_i2i);
Вызов модели и возврат результата в Telegram.
Недостаточно кредитов:
После оценки цены Hub видит, что balance < price;
Отправляет в Telegram подсказку пополнить счёт и не запускает генерацию.

4) Глоссарий (единые термины)¶

Hub (входной воркфлоу): главный роутер n8n, имя начинается с Geni_AI….
Tool workflow: воркфлоу под конкретный режим/модель (например, seedream).
Photo bucket (seedream): временное хранение фото в staticData (состояния STORED/GENERATE/CLEARED/REMIND).
Task: запись в БД о запуске операции; статусы created → running → success/failed.
Wallet: кредиты, которые списываются перед вызовом модели и возвращаются при ошибке.

5) Карта зависимостей (куда кто ходит)¶

n8n → Supabase: get_tool_price_credits, wallet_debit, ensure_user, обновление статусов задач.
n8n → Модели: HTTP-вызовы провайдера (пример: Comet API, модель seedream).
WebApps → n8n: формы/кнопки передают настройки генерации (режим, размеры, качество, и т.д.).

6) Расширение системы (правильный путь)¶

Добавьте новый Tool workflow в n8n: объявите входные поля и ожидаемый формат ответа.
Опишите цену через get_tool_price_credits и проводите списание через wallet_debit до вызова модели.
Если нужен UI — добавьте страницу в WebApps, возвращающую параметры в том же контракте.
Логируйте task и обновляйте статус; при ошибке обеспечьте refund и понятное сообщение в Telegram.
Используйте существующие имена полей/таблиц; не вводите новые без необходимости.

7) Ограничения и безопасность¶

Токены внешних провайдеров хранятся в n8n Credentials (ограниченный доступ).
В БД сохраняется минимум персональных данных, фото/файлы не логируются в открытые журналы.
Ветка ошибок должна возвращать пользователю понятные причины и не раскрывать чувствительные детали.