quoter/docs/architecture.md

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

## Обзор системы

Quoter - это микросервис для управления файлами с поддержкой квот, миниатюр и интеграции с S3 хранилищами.

## Компоненты системы

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Client    │    │   Mobile App    │    │   API Client    │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      Quoter Service       │
                    │    (Actix Web Server)     │
                    └─────────────┬─────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
    ┌─────▼─────┐         ┌───────▼──────┐         ┌─────▼─────┐
    │   Redis   │         │  Core API    │         │   S3/Storj│
    │ (Quotas & │         │(Auth & Shout)│         │ (Storage) │
    │  Cache)   │         │              │         │           │
    └───────────┘         └──────────────┘         └───────────┘
```

## Основные модули

### 1. AppState (`src/app_state.rs`)
Центральное состояние приложения, содержащее:
- Подключения к Redis, Storj S3, AWS S3
- Методы для работы с квотами
- Кэширование списка файлов

### 2. Handlers (`src/handlers/`)
Обработчики HTTP запросов:
- `upload.rs` - загрузка файлов
- `proxy.rs` - получение файлов и генерация миниатюр
- `quota.rs` - управление квотами
- `serve_file.rs` - обслуживание файлов

### 3. Auth (`src/auth.rs`)
Аутентификация через GraphQL API ядра:
- Валидация JWT токенов
- Управление файлами пользователей в Redis

### 4. Core (`src/core.rs`)
Интеграция с API ядра:
- Получение данных shout для оверлеев

### 5. Thumbnail (`src/thumbnail.rs`)
Обработка изображений:
- Создание миниатюр различных размеров
- Поддержка различных форматов

### 6. S3 Utils (`src/s3_utils.rs`)
Утилиты для работы с S3:
- Загрузка/скачивание файлов
- Определение MIME типов
- Генерация ключей

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

### Загрузка файла

```mermaid
sequenceDiagram
    participant Client
    participant Quoter
    participant Core API
    participant Redis
    participant S3

    Client->>Quoter: POST / (file + token)
    Quoter->>Core API: Validate token
    Core API-->>Quoter: Author ID
    Quoter->>Redis: Check quota
    Redis-->>Quoter: Current quota
    Quoter->>S3: Upload file
    S3-->>Quoter: Success
    Quoter->>Redis: Update quota
    Quoter->>Redis: Save file info
    Quoter-->>Client: Filename
```

### Получение файла

```mermaid
sequenceDiagram
    participant Client
    participant Quoter
    participant Redis
    participant S3

    Client->>Quoter: GET /filename
    Quoter->>Redis: Get file path
    Redis-->>Quoter: File path
    Quoter->>S3: Check file exists
    S3-->>Quoter: File exists
    Quoter->>S3: Download file
    S3-->>Quoter: File data
    Quoter-->>Client: File content
```

## Структура данных

### Redis схемы

#### Квоты пользователей
```
Key: quota:{user_id}
Type: String
Value: bytes_used (u64)
TTL: None (permanent)
```

#### Файлы пользователей
```
Key: {user_id}
Type: Set
Value: [filename1, filename2, ...]
TTL: None (permanent)
```

#### Маппинг путей файлов
```
Key: filepath_mapping
Type: Hash
Field: filename
Value: filepath
TTL: None (permanent)
```

#### Информация о файлах
```
Key: files:{filename}
Type: String
Value: mime_type
TTL: None (permanent)
```

### S3 структура

```
bucket/
├── original_files/
│   ├── image1.jpg
│   ├── image2.png
│   └── document.pdf
├── thumbnails/
│   ├── image1_10.jpg
│   ├── image1_40.jpg
│   ├── image1_110.jpg
│   ├── image1_300.jpg
│   ├── image1_600.jpg
│   ├── image1_800.jpg
│   └── image1_1400.jpg
└── webp_thumbnails/
    ├── image1_10.jpg/webp
    ├── image1_40.jpg/webp
    └── ...
```

## Безопасность

### Аутентификация
- JWT токены через GraphQL API ядра
- Валидация токенов для всех операций записи

### Авторизация
- Проверка квот перед загрузкой
- Изоляция файлов по пользователям

### CORS
- Настроен для кросс-доменных запросов
- Поддержка credentials

## Масштабирование

### Горизонтальное масштабирование
- Stateless архитектура
- Redis как общее хранилище состояния
- S3 как общее файловое хранилище

### Производительность
- Асинхронная обработка запросов
- Кэширование списка файлов
- Ленивая генерация миниатюр

### Мониторинг
- Структурированное логирование
- Метрики использования квот
- Отслеживание ошибок