banatie-strategy/sdd.md

\# Техническая Архитектура и Функциональная Спецификация:

\*\*Banatie AI Asset Generation Platform\*\*



\### 1. Обзор Платформы (Platform Overview)



\*\*Banatie\*\* — это API-first платформа для программной генерации и доставки \*\*готовых к использованию (Production-Ready)\*\* медиа-активов. В отличие от традиционных генераторов, Banatie интегрирует возможности передовой AI-генерации (на базе Google Gemini) с полноценным конвейером продакшен-доставки (CDN, хостинг, трансформации).



Целевая аудитория — разработчики, веб-мастера и создатели SaaS-приложений, которым требуется \*\*комплексное, оптимизированное решение\*\* для автоматизации создания и встраивания контента.



\### 2. Технический Стек (Technology Stack)



| Компонент | Технология | Роль в Архитектуре |

| :--- | :--- | :--- |

| \*\*Основная Модель (Core Synthesizer)\*\* | \*\*Gemini 2.5 Flash Image\*\* | Ядро для высокоскоростного синтеза изображений. |

| \*\*Вспомогательные AI Модели (Agents)\*\* | \*\*Gemini 2.5 Flash\*\* (и другие быстрые модели) | \*\*Prompt Enhancement\*\* (оптимизация промптов) и \*\*Asset Analysis\*\* (извлечение метаданных и фокальной точки). |

| \*\*Backend \& API Gateway\*\* | \*\*Express (Node.js)\*\* | Высокопроизводительный REST API-сервер и логика Flow-Based Generation. |

| \*\*Фронтенд \& UI\*\* | \*\*Next.js\*\* | Разработка основного сайта, документации, демонстрационных UI. |

| \*\*Управление Аккаунтами\*\* | \*\*nextjs/saas-starter (Шаблон)\*\* | Основа для архитектуры авторизации, организаций и проектов. |

| \*\*Хранение Аксетов (Object Storage)\*\* | \*\*MinIO (S3-совместимый)\*\* | Первичное, высокодоступное хранилище сгенерированных и загруженных активов. |

| \*\*Трансформация Изображений\*\* | \*\*Imageflow-Server\*\* | Динамическое преобразование активов (ресайзинг, обрезка, формат) через Query Params. |

| \*\*Доставка Контента (CDN)\*\* | \*\*Cloudflare\*\* | Глобальное кэширование и оптимизированная доставка трансформированных изображений. |

| \*\*База Данных\*\* | \*\*PostgreSQL\*\* | Реляционное хранилище для метаданных генераций, пользователей, проектов и биллинга. |

| \*\*Deployment\*\* | \*\*Docker / VPS\*\* | Контейнеризация и размещение сервиса. |



\### 3. Основной Процесс Генерации и Доставки Аксетов (Core Generation \& Delivery Flow)



Пайплайн разделен на 6 этапов для обеспечения продакшен-готовности ассетов:



1\.  \*\*Ввод Пользователя (User Input):\*\* Получение неструктурированного промпта (на любом языке) и дополнительных параметров (стиль, соотношение сторон).

2\.  \*\*Prompt Enhancement (AI-Агент):\*\* Специализированный агент анализирует, переводит и \*\*оптимизирует промпт\*\* (с учетом выбранного стиля и лучших практик Gemini), создавая детализированный, высокоэффективный запрос.

3\.  \*\*Core Image Synthesis:\*\* Оптимизированный промпт отправляется в Gemini API для генерации изображения.

4\.  \*\*Asset Analysis \& Metadata Extraction:\*\* Второй AI-агент анализирует полученное изображение, выделяя \*\*фокальную точку (Focal Point)\*\* и ключевые метаданные, необходимые для корректной автоматической обрезки/трансформации.

5\.  \*\*Asset Persistence \& Indexing:\*\* Изображение сохраняется в MinIO. Метаданные (промпты, параметры, фокальная точка) индексируются в PostgreSQL.

6\.  \*\*Production URL \& Delivery:\*\* Генерируется \*\*постоянный, кэшируемый URL\*\*. При обращении изображение проходит через \*\*Imageflow-Server\*\* (трансформация) и кэшируется в \*\*Cloudflare CDN\*\*. Ответ API также включает набор ходовых трансформированных ссылок (пресетов) для удобной верстки.



\### 4. Основные Функциональные Особенности (Core Differentiating Features)



| Feature | Описание | B2D-Ценность |

| :--- | :--- | :--- |

| \*\*4.1. Flow-Based Chained Generation\*\* | Программная последовательность генераций, где каждая новая генерация имеет доступ к контексту и результатам предыдущих шагов Flow. | Позволяет создавать сложные, логически связанные наборы ассетов (итерации персонажей, ассеты для игр). |

| \*\*4.2. On-Demand Generation via URL\*\* | Генерация изображения, инициируемая \*\*GET-запросом к URL\*\* с промптом в Query Params. При повторном запросе возвращается закэшированный ассет. | Обеспечивает возможность LLM-агентам генерировать HTML-страницы с готовыми, оптимизированными изображениями. |

| \*\*4.3. Contextual Asset Referencing\*\* | Возможность присваивать ассетам имена (`@logo`) и использовать эти имена \*\*напрямую в текстовом промпте\*\* для передачи референсных изображений в модель. | Упрощает Inpainting/Outpainting и создание контента с привязкой к бренду или существующим элементам. |

| \*\*4.4. Image Transformation Pipeline\*\* | Динамическое преобразование изображения (ресайзинг, изменение `aspect ratio`, обрезка по фокальной точке, форматы) через Query Params в CDN-ссылке. | Устраняет необходимость ручной обработки изображений, гарантируя оптимальную скорость загрузки и качество на всех устройствах. |

| \*\*4.5. Namespaces и Стили\*\* | Виртуальное разделение активов в проектах с возможностью задания общих системных промптов и стилей для обеспечения \*\*визуальной консистентности\*\*. | Идеально для управления брендбуком или стилистикой разных разделов сайта. |



\### 5. Каналы Взаимодействия и Авторизация



\*   \*\*REST API:\*\* Основной канал, обеспечивающий полный доступ ко всем функциям.

\*   \*\*JS/TS SDK:\*\* Высокоуровневая обертка для удобной программной работы с Flow-Based Generation.

\*   \*\*Model Context Protocol (MCP):\*\* \*\*Специализированный API/протокол\*\* для интеграции с LLM и AI-агентами, оптимизированный для контекстуальных и последовательных запросов.

\*   \*\*User Interface (UI):\*\* Веб-интерфейс для тестирования и отладки. Каждая генерация сопровождается \*\*Code Snippets\*\* для API, SDK и MCP.

\*   \*\*Авторизация:\*\* Основана на \*\*API-ключах\*\* (`apikey`). Каждый ключ ассоциирован с парой \*\*Организация/Проект\*\* для контроля доступа и биллинговой изоляции.



\### 6. Релизная Стратегия (MVP Focus)



Для первого публичного релиза необходима полная функциональность в следующих ключевых областях:



1\.  \*\*Ядро Генерации:\*\* Полностью работающий \*\*Prompt Enhancement\*\* и \*\*Asset Persistence\*\*.

2\.  \*\*Доставка:\*\* Рабочий \*\*Image Transformation Pipeline\*\* с CDN, генерирующий \*production-ready\* ссылки.

3\.  \*\*Уникальные Фичи:\*\* \*\*On-Demand Generation via URL\*\* и базовая \*\*Contextual Asset Referencing\*\* (@logo).

4\.  \*\*Авторизация/Биллинг:\*\* Полностью работающая система \*\*API Key\*\* и \*\*Free Tier\*\* с механизмом ограничения лимитов.