feat: add tech arch
This commit is contained in:
parent
8f5bb4857f
commit
bfa5572e1b
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"cSpell.words": [
|
||||
"Ekaterina",
|
||||
"Kirill",
|
||||
"Samui"
|
||||
]
|
||||
}
|
||||
20
INDEX.md
20
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
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
122
sdd.md
122
sdd.md
|
|
@ -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\*\* с механизмом ограничения лимитов.
|
||||
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue