core/docs/auth/architecture.md

# Архитектура системы авторизации Discours Core

## 🎯 Обзор архитектуры

Модульная система авторизации с разделением ответственности между компонентами. 

**Хранение данных:**
- **Токены** → Redis (сессии, OAuth, verification)
- **Пользователи** → PostgreSQL (основные данные + OAuth в JSON поле)

## 📊 Схема потоков данных

```mermaid
graph TB
    subgraph "Frontend"
        FE[Web Frontend]
        MOB[Mobile App]
        API[API Clients]
    end

    subgraph "Auth Layer"
        MW[AuthMiddleware]
        DEC[GraphQL Decorators]
        UTILS[Auth Utils]
    end

    subgraph "Token Managers"
        STM[SessionTokenManager]
        VTM[VerificationTokenManager]
        OTM[OAuthTokenManager]
        BTM[BatchTokenOperations]
        MON[TokenMonitoring]
    end

    subgraph "Storage"
        REDIS[(Redis)]
        DB[(PostgreSQL)]
    end

    subgraph "External OAuth"
        GOOGLE[Google]
        GITHUB[GitHub]
        FACEBOOK[Facebook]
        VK[VK]
        YANDEX[Yandex]
    end

    FE --> MW
    MOB --> MW
    API --> MW
    
    MW --> STM
    MW --> UTILS
    
    DEC --> STM
    UTILS --> STM
    
    STM --> REDIS
    VTM --> REDIS
    OTM --> REDIS
    BTM --> REDIS
    MON --> REDIS
    
    STM --> DB
    
    OTM --> GOOGLE
    OTM --> GITHUB
    OTM --> FACEBOOK
    OTM --> VK
    OTM --> YANDEX
```

## 🏗️ Диаграмма компонентов

**Примечание:** Токены хранятся только в Redis, PostgreSQL используется только для пользовательских данных и OAuth связей.

```mermaid
graph TB
    subgraph "HTTP Layer"
        REQ[HTTP Request]
        RESP[HTTP Response]
    end

    subgraph "Middleware Layer"
        AUTH_MW[AuthMiddleware]
        UTILS[Auth Utils]
    end

    subgraph "Token Management"
        STM[SessionTokenManager]
        VTM[VerificationTokenManager]
        OTM[OAuthTokenManager]
        BTM[BatchTokenOperations]
        MON[TokenMonitoring]
    end

    subgraph "Storage"
        REDIS[(Redis)]
        DB[(PostgreSQL)]
    end

    subgraph "External"
        OAUTH_PROV[OAuth Providers]
    end

    REQ --> AUTH_MW
    AUTH_MW --> UTILS
    UTILS --> STM
    
    STM --> REDIS
    VTM --> REDIS
    OTM --> REDIS
    BTM --> REDIS
    MON --> REDIS
    
    STM --> DB
    OTM --> OAUTH_PROV
    
    STM --> RESP
    VTM --> RESP
    OTM --> RESP
```

## 🔐 OAuth Flow

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as Auth Service
    participant R as Redis
    participant P as OAuth Provider

    U->>F: Click "Login with Provider"
    F->>A: GET /oauth/{provider}?state={csrf}
    A->>R: Store OAuth state (TTL: 10 min)
    A->>P: Redirect to Provider
    P->>U: Show authorization page
    U->>P: Grant permission
    P->>A: GET /oauth/{provider}/callback?code={code}&state={state}
    A->>R: Verify state
    A->>P: Exchange code for token
    P->>A: Return access token + user data
    A->>R: Store OAuth tokens
    A->>A: Generate JWT session token
    A->>R: Store session in Redis
    A->>F: Redirect with JWT token
    F->>U: User logged in
```

## 🔄 Session Management

```mermaid
stateDiagram-v2
    [*] --> Anonymous
    Anonymous --> Authenticating: Login attempt
    Authenticating --> Authenticated: Valid JWT + Redis session
    Authenticating --> Anonymous: Invalid credentials
    Authenticated --> Refreshing: Token near expiry
    Refreshing --> Authenticated: Successful refresh
    Refreshing --> Anonymous: Refresh failed
    Authenticated --> Anonymous: Logout/Revoke
    Authenticated --> Anonymous: Token expired
```

## 🗄️ Redis структура данных

```bash
# JWT Sessions
session:{user_id}:{token}     # Hash: {user_id, username, device_info, last_activity}
user_sessions:{user_id}       # Set: {token1, token2, ...}

# Verification Tokens  
verification_token:{token}    # JSON: {user_id, type, data, created_at}

# OAuth Tokens
oauth_access:{user_id}:{provider}   # JSON: {token, expires_in, scope}
oauth_refresh:{user_id}:{provider}  # JSON: {token, provider_data}
oauth_state:{state}                 # JSON: {provider, redirect_uri, code_verifier}

# Legacy (для совместимости)
{user_id}-{username}-{token}  # Hash: legacy format
```

### Примеры Redis команд

```bash
# Поиск сессий пользователя
redis-cli --scan --pattern "session:123:*"

# Получение данных сессии
redis-cli HGETALL "session:123:your_token_here"

# Проверка TTL
redis-cli TTL "session:123:your_token_here"

# Поиск OAuth токенов
redis-cli --scan --pattern "oauth_access:123:*"
```

## 🔒 Security Components

```mermaid
graph TD
    subgraph "Input Validation"
        EMAIL[Email Format]
        PASS[Password Strength]
        TOKEN[JWT Validation]
    end

    subgraph "Authentication"
        BCRYPT[bcrypt + SHA256]
        JWT_SIGN[JWT Signing]
        OAUTH_VERIFY[OAuth Verification]
    end

    subgraph "Authorization"
        RBAC[RBAC System]
        PERM[Permission Checks]
        RESOURCE[Resource Access]
    end

    subgraph "Session Security"
        TTL[Redis TTL]
        REVOKE[Token Revocation]
        REFRESH[Secure Refresh]
    end

    EMAIL --> BCRYPT
    PASS --> BCRYPT
    TOKEN --> JWT_SIGN

    BCRYPT --> RBAC
    JWT_SIGN --> RBAC
    OAUTH_VERIFY --> RBAC

    RBAC --> PERM
    PERM --> RESOURCE

    RESOURCE --> TTL
    RESOURCE --> REVOKE
    RESOURCE --> REFRESH
```

## ⚡ Performance & Scaling

### Горизонтальное масштабирование
- **Stateless JWT** токены
- **Redis Cluster** для высокой доступности
- **Load Balancer** aware session management

### Оптимизации
- **Connection pooling** для Redis
- **Batch operations** для массовых операций (100-1000 токенов)
- **Pipeline использование** для атомарности
- **SCAN** вместо KEYS для безопасности

### Мониторинг производительности
```python
from auth.tokens.monitoring import TokenMonitoring

monitoring = TokenMonitoring()

# Статистика токенов
stats = await monitoring.get_token_statistics()
# {
#   "session_tokens": 150,
#   "verification_tokens": 5,
#   "oauth_access_tokens": 25,
#   "memory_usage": 1048576
# }

# Health check
health = await monitoring.health_check()
# {"status": "healthy", "redis_connected": True}
```