# Архитектура 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 и зависимости

```python
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** — фундамент без внешних зависимостей