voidea/docs/architecture.md

Архитектура VoIdeaAI

Слои

┌──────────────────────────────────────────────────┐
│                   API (FastAPI)                   │
│  HTTP роуты / Pydantic / OpenAPI / StaticFiles    │
│  → Services                                       │
├──────────────────────────────────────────────────┤
│                   Services                        │
│  Бизнес-логика: auth, idea, user, agent, sync     │
│  → Integrations, Data                             │
├──────────────────────────────────────────────────┤
│                 Integrations                      │
│  AI Fallback Chain (YandexGPT → GigaChat)         │
│  → Data                                           │
├──────────────────────────────────────────────────┤
│                   Tasks (Celery)                  │
│  Асинхронный анализ идей, прямой вызов при        │
│  отсутствии Celery                                │
│  → Services, Integrations                         │
├──────────────────────────────────────────────────┤
│                   Agents                          │
│  11 системных агентов (Doc → Supervisor)          │
│  → Services, Integrations                         │
├──────────────────────────────────────────────────┤
│                   Data (SQLAlchemy)               │
│  Модели: User, Idea, AgentConfig, BacklogTask,    │
│  LogEntry, AgentReport, AgentMetrics              │
│  → Core                                           │
├──────────────────────────────────────────────────┤
│                   Core                            │
│  Config, base, exceptions, security, dependencies │
│  Фундамент, не зависит ни от чего                 │
└──────────────────────────────────────────────────┘

Ключевые решения

Решение	Выбор	Причина
БД	PostgreSQL (asyncpg)	Единая БД на всех этапах. VPS Ubuntu.
Фронтенд	FastAPI StaticFiles	Без Nginx, без Docker. One process
Фоновые задачи	Celery / прямой вызов	Graceful degradation при отсутствии Redis
AI провайдеры	FallbackChain: YandexGPT → GigaChat	2 retry, таймауты
Аутентификация	JWT (access + refresh)	Stateless, без сессий
Версионирование агентов	A.B.C + SHA256 checksum	Независимое версионирование
Деплой	systemd + venv	Напрямую на VPS, без контейнеризации

DI и зависимости

async def get_db() -> AsyncSession:
    async with async_session_maker() as session:
        yield session

class IdeaService:
    def __init__(self, db: AsyncSession): ...

class AuthService:
    def __init__(self, db: AsyncSession, settings: Settings): ...

Правила слоёв

1. API не знает про БД — использует Depends(get_db) и сервисы
2. Services не импортируют HTTP — работают с бизнес-данными
3. Integrations оборачивают внешние API с таймаутами и ретраями
4. Data — SQLAlchemy модели без бизнес-логики
5. Core — фундамент без внешних зависимостей