📚 Documentation Updates

- **🔍 Comprehensive authentication documentation refactoring**: Полная переработка документации аутентификации
  - Обновлена таблица содержания в README.md
  - Исправлены архитектурные диаграммы - токены хранятся только в Redis
  - Добавлены практические примеры кода для микросервисов
  - Консолидирована OAuth документация

docs/auth/architecture.md

@@ -0,0 +1,276 @@
+# Архитектура системы авторизации 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}
+```