quoter/docs/how-it-works.md

# 🚀 Как работает Quoter

Quoter - это высокопроизводительный файловый сервис с автоматическим ресайзингом изображений, системой квот и многоуровневой защитой.

## 📋 Архитектура системы

### 1. 🔐 Аутентификация и безопасность
- **JWT валидация**: Проверка токенов с валидацией формата, длины и подписи
- **Rate limiting**: Ограничение запросов по IP с Redis-хранением
- **Request validation**: Проверка размера, заголовков и подозрительных паттернов
- **Session management**: Получение данных пользователя из Redis сессий

### 2. 📤 Процесс загрузки файлов
```
Клиент → [Auth] → [Quota Check] → [Upload] → [Thumbnail Generation] → [S3 Storage]
```

**Этапы обработки:**
1. **Валидация токена**: JWT проверка + извлечение user_id
2. **Проверка квот**: Текущая квота пользователя (лимит 12 ГБ)
3. **Стриминг загрузка**: Чтение файла по частям с проверкой лимитов
4. **MIME детекция**: Автоматическое определение типа файла
5. **Генерация UUID**: Уникальное имя файла
6. **Загрузка в Storj**: Основное хранилище
7. **Асинхронная генерация миниатюр**: Для изображений

### 3. 🖼️ Система миниатюр
**Предопределенные размеры:**
- `10px` - микро-превью
- `40px` - аватары
- `110px` - маленькие превью  
- `300px` - средние изображения
- `600px` - стандартные изображения
- `800px` - большие изображения
- `1400px` - максимальный размер

**Lazy Generation:**
- Миниатюры создаются по первому запросу
- Оригинал возвращается пока генерируется миниатюра
- Асинхронная обработка в фоне
- Кэширование в S3

### 4. 📂 Система файлов (Multi-Cloud)
```
┌─ Storj S3 (primary) ─┐    ┌─ AWS S3 (fallback) ─┐
│ • Новые файлы        │    │ • Legacy файлы       │
│ • Миниатюры          │    │ • Backup             │
│ • Основное хранилище │    │ • Migration source   │
└─────────────────────┘    └──────────────────────┘
```

**Логика обслуживания:**
1. Проверка в Storj (основное хранилище)
2. Fallback на AWS S3 (legacy файлы)
3. Автоматическая миграция AWS → Storj при запросе
4. Поддержка различных путей (`production/image/`, etc.)

### 5. 🔍 Обслуживание файлов (GET)
```
Request → [Security] → [Cache Check] → [File Lookup] → [Resize] → [Response]
```

**Процесс:**
1. **Security проверки**: Rate limits, подозрительные пути
2. **ETag кэширование**: HTTP 304 для неизмененных файлов
3. **Path parsing**: Извлечение имени файла и размера
4. **File lookup**: Поиск в базе путей или по паттерну
5. **Resize logic**: Выбор ближайшего размера или генерация
6. **Cached response**: Оптимизированные заголовки

### 6. 💾 Управление квотами
**Redis структуры:**
```redis
quota:user:{user_id}           # Текущая квота (bytes)
files:user:{user_id}           # Список файлов пользователя
file_info:{filename}           # MIME-type и метаданные
rate_limit:{type}:{ip}         # Счетчики rate limiting
```

**Проверки:**
- Превентивная проверка перед загрузкой
- Streaming проверка по частям
- Atomic обновление после успешной загрузки
- Лимит: 12 ГБ на пользователя

### 7. 🛡️ Система безопасности
**Уровни защиты:**
1. **Network**: Security headers, CORS, payload limits
2. **Application**: Rate limiting, request validation  
3. **Authentication**: JWT validation, session management
4. **Monitoring**: Логирование атак, метрики

**Rate Limits:**
- Общие запросы: 100/мин (блокировка 5 мин)
- Загрузка файлов: 10/5мин (блокировка 10 мин)
- Аутентификация: 20/15мин (блокировка 30 мин)

## 🔄 Поток данных

### Загрузка файла
```mermaid
sequenceDiagram
    Client->>+Quoter: POST / (multipart)
    Quoter->>+Redis: Validate session
    Redis-->>-Quoter: User data
    Quoter->>+Redis: Check quota
    Redis-->>-Quoter: Current usage
    Quoter->>+Storj: Upload file
    Storj-->>-Quoter: Success
    Quoter->>+Background: Generate thumbnails
    Quoter->>+Redis: Update quota
    Quoter-->>-Client: File URL
```

### Получение файла
```mermaid
sequenceDiagram
    Client->>+Quoter: GET /file_300.jpg
    Quoter->>+Cache: Check ETag
    Cache-->>-Quoter: 304 or miss
    Quoter->>+Storj: Get thumbnail
    alt Thumbnail exists
        Storj-->>Quoter: File data
    else Thumbnail missing
        Storj-->>Quoter: Original file
        Quoter->>Background: Generate thumbnail
    end
    Quoter-->>-Client: Image + headers
```

## 📊 Производительность

### Оптимизации
- **HTTP кэширование**: ETag, immutable cache headers
- **Lazy thumbnail generation**: Генерация по требованию
- **Асинхронная обработка**: Неблокирующие операции
- **Local + Redis cache**: Многоуровневое кэширование
- **Streaming uploads**: Обработка больших файлов по частям

### Мониторинг
- Время обработки запросов
- Статистика генерации миниатюр  
- Метрики rate limiting
- Использование квот по пользователям
- Ошибки и security события