10 KiB
# Техническая Архитектура и Функциональная Спецификация:
**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** с механизмом ограничения лимитов.