diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..4b6d906 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,7 @@ +{ + "cSpell.words": [ + "Ekaterina", + "Kirill", + "Samui" + ] +} \ No newline at end of file diff --git a/INDEX.md b/INDEX.md index 832dc43..43495a9 100644 --- a/INDEX.md +++ b/INDEX.md @@ -1,8 +1,8 @@ # Banatie Strategy Documentation Index -**Last Updated:** 2024-10-30 -**Total Documents:** 12 (numbered) + discussions (date-based) -**Next Available Number:** 11 (or 15 if keeping 11-14 reserved) +**Last Updated:** 2025-11-01 +**Total Documents:** 13 (numbered) + discussions (date-based) +**Next Available Number:** 12 (or 15 if keeping 12-14 reserved) **Project Stage:** Pre-launch / ICP Validation --- @@ -24,13 +24,14 @@ - 08 - Validation Plan - 09 - MVP Scope - 10 - Pricing Strategy -- 11-14 - Reserved for technical appendices +- 11 - Technical Architecture +- 12-14 - Reserved for future strategic docs **Released from numbering:** - ~~04~~ - Moved to discussions/ with date-based naming - ~~05~~ - Never created, number freed -**Next to assign:** 11 (or 15 if keeping 11-14 reserved) +**Next to assign:** 12 (or 15 if keeping 12-14 reserved) --- @@ -67,10 +68,11 @@ Critical: Solo founder, family of 5, $6K/month sole income, 15-20 hrs/week avail Confidence: HIGH (80%) - founder IS the ICP Target: Developers using Claude Code/Cursor who build web projects regularly -**[Technical Spec](strategy/sdd.md)** -*Platform architecture, tech stack, MVP features* -Status: ⏳ Needs English translation -Stack: Express, Next.js, Gemini 2.5 Flash Image, MinIO, PostgreSQL, Cloudflare +**[11 - Technical Architecture](strategy/11-technical-architecture.md)** (v1.0, Nov 1) +*Platform architecture, tech stack, 6-stage pipeline, MVP release strategy* +Status: ✅ Validated +Stack: Express, Next.js, Gemini 2.5 Flash Image, MinIO, PostgreSQL, Cloudflare, Imageflow +Key differentiators: Flow-based generation, on-demand URL generation, @name references, transformation pipeline --- diff --git a/sdd.md b/sdd.md deleted file mode 100644 index b6596e1..0000000 --- a/sdd.md +++ /dev/null @@ -1,122 +0,0 @@ -\# Техническая Архитектура и Функциональная Спецификация: - -\*\*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\*\* с механизмом ограничения лимитов. - diff --git a/strategy/11-technical-architecture.md b/strategy/11-technical-architecture.md new file mode 100644 index 0000000..0669eff --- /dev/null +++ b/strategy/11-technical-architecture.md @@ -0,0 +1,110 @@ +# Technical Architecture and Functional Specification + +**Date:** 2025-11-01 +**Version:** 1.0 +**Status:** ✅ Validated (current technical architecture) +**Related docs:** `strategy/07-validated-icp-ai-developers.md`, `execution/09-mvp-scope.md` + +--- + +## Platform Overview + +**Banatie** is an API-first platform for programmatic generation and delivery of **production-ready** media assets. Unlike traditional generators, Banatie integrates cutting-edge AI generation capabilities (powered by Google Gemini) with a complete production delivery pipeline (CDN, hosting, transformations). + +Target audience: Need to be investigated. The working hypothesis: Developers, webmasters, and SaaS creators who need a **comprehensive, optimized solution** for automating content creation and embedding. + +--- + +## Technology Stack + +| Component | Technology | Role in Architecture | +|:---|:---|:---| +| **Core Synthesizer** | **Gemini 2.5 Flash Image** | High-speed image synthesis engine | +| **AI Agent Models** | **Gemini 2.5 Flash** (and other fast models) | **Prompt Enhancement** (prompt optimization) and **Asset Analysis** (metadata extraction and focal point detection) | +| **Backend & API Gateway** | **Express (Node.js)** | High-performance REST API server and Flow-Based Generation logic | +| **Frontend & UI** | **Next.js** | Main website, documentation, demo UIs | +| **Account Management** | **nextjs/saas-starter (Template)** | Foundation for auth architecture, organizations, and projects | +| **Object Storage** | **MinIO (S3-compatible)** | Primary, highly-available storage for generated and uploaded assets | +| **Image Transformation** | **Imageflow-Server** | Dynamic asset transformation (resize, crop, format) via Query Params | +| **Content Delivery (CDN)** | **Cloudflare** | Global caching and optimized delivery of transformed images | +| **Database** | **PostgreSQL** | Relational storage for generation metadata, users, projects, and billing | +| **Deployment** | **Docker / VPS** | Containerization and service hosting | + +--- + +## Core Generation & Delivery Flow + +The pipeline is divided into **6 stages** to ensure production-ready assets: + +### Stage 1: User Input +Receive unstructured prompt (in any language) and additional parameters (style, aspect ratio). + +### Stage 2: Prompt Enhancement (AI Agent) +Specialized agent analyzes, translates, and **optimizes the prompt** (considering selected style and Gemini best practices), creating a detailed, highly-effective request. + +### Stage 3: Core Image Synthesis +Optimized prompt is sent to Gemini API for image generation. + +### Stage 4: Asset Analysis & Metadata Extraction +Second AI agent analyzes the generated image, identifying the **focal point** and key metadata needed for proper automatic cropping/transformation. + +### Stage 5: Asset Persistence & Indexing +Image is saved to MinIO. Metadata (prompts, parameters, focal point) is indexed in PostgreSQL. + +### Stage 6: Production URL & Delivery +A **permanent, cacheable URL** is generated. On request, the image passes through **Imageflow-Server** (transformation) and is cached in **Cloudflare CDN**. The API response also includes a set of common transformation presets for convenient layout integration. + +--- + +## Core Differentiating Features + +| Feature | Description | Developer Value | +|:---|:---|:---| +| **Flow-Based Chained Generation** | Programmatic sequence of generations where each new generation has access to context and results from previous Flow steps | Enables creation of complex, logically connected asset sets (character iterations, game assets) | +| **On-Demand Generation via URL** | Image generation triggered by **GET request to URL** with prompt in Query Params. Repeated requests return cached asset | Allows LLM agents to generate HTML pages with ready-made, optimized images | +| **Contextual Asset Referencing** | Ability to assign names to assets (`@logo`) and use these names **directly in text prompts** to pass reference images to the model | Simplifies Inpainting/Outpainting and content creation tied to brand or existing elements | +| **Image Transformation Pipeline** | Dynamic image transformation (resize, aspect ratio change, focal point cropping, formats) via Query Params in CDN link | Eliminates manual image processing, ensuring optimal load speed and quality across all devices | +| **Namespaces & Styles** | Virtual asset separation in projects with ability to set common system prompts and styles for **visual consistency** | Ideal for managing brand guidelines or styling different website sections | + +--- + +## Integration Channels + +### REST API +Primary channel providing full access to all features. + +### JS/TS SDK +High-level wrapper for convenient programmatic work with Flow-Based Generation. + +### Model Context Protocol (MCP) +**Specialized API/protocol** for integration with LLMs and AI agents, optimized for contextual and sequential requests. + +### User Interface (UI) +Web interface for testing and debugging. Every generation includes **Code Snippets** for API, SDK, and MCP. + +### Authorization +Based on **API keys** (`apikey`). Each key is associated with an **Organization/Project** pair for access control and billing isolation. + +--- + +## MVP Release Strategy + +For the first public release, full functionality is required in the following key areas: + +### 1. Core Generation +Fully functional **Prompt Enhancement** and **Asset Persistence**. + +### 2. Delivery Pipeline +Working **Image Transformation Pipeline** with CDN, generating production-ready links. + +### 3. Unique Features +**On-Demand Generation via URL** and basic **Contextual Asset Referencing** (@logo). + +### 4. Authorization & Billing +Fully functional **API Key** system and **Free Tier** with usage limit enforcement. + +--- + +**Document owner:** Oleg (technical lead) +**Last updated:** 2025-11-01 +**Next review:** After ICP validation \ No newline at end of file