uploader-bot/docs/MY_ARCHITECTURE.md

# MY Network Architecture Specification

## Архитектурный Обзор

MY Network представляет собой многоуровневую архитектуру overlay протокола, интегрированную с существующей системой my-uploader-bot без нарушения её функциональности.

## Overlay Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                        MY Network Layer                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ P2P Manager │  │   Consensus │  │ Replication │             │
│  │             │  │   Engine    │  │  Manager    │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
├─────────────────────────────────────────────────────────────────┤
│                    Integration Layer                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ Content API │  │ Storage API │  │   Auth API  │             │
│  │  (Existing) │  │ (Existing)  │  │ (Existing)  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
├─────────────────────────────────────────────────────────────────┤
│                      Core Data Layer                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │StoredContent│  │EncryptionKey│  │ UserContent │             │
│  │   Model     │  │   Model     │  │   Model     │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
```

## Интеграция с Существующей StoredContent Моделью

### Расширение StoredContent для MY Network

```python
# Новые поля для MY Network (добавляются через миграцию)
class StoredContentExtension:
    # MY Network specific fields
    my_network_enabled = Column(Boolean, default=False)
    replica_count = Column(Integer, default=0)
    replication_status = Column(String(32), default="none")
    consensus_achieved = Column(Boolean, default=False)
    
    # Peer information
    replicated_on_peers = Column(ARRAY(String), default=list)
    last_sync_timestamp = Column(DateTime, nullable=True)
    
    # Network metadata
    network_metadata = Column(JSONB, default=dict)
```

### Состояния Контента и Их Связи

#### 1. Encrypted Content State
```python
# Зашифрованный контент в MY Network
encrypted_content = StoredContent(
    hash="sha256:abc123...",
    encrypted=True,
    encryption_key_id="uuid-key-id",
    content_type="audio",
    my_network_enabled=True
)
```

#### 2. Decrypted Content State (через decrypted_content_id)
```python
# Расшифрованная версия связана через специальное поле
decrypted_content = StoredContent(
    hash="sha256:def456...",
    encrypted=False,
    original_encrypted_id=encrypted_content.id,  # Обратная связь
    content_type="audio",
    my_network_enabled=True
)

# В encrypted_content добавляется:
encrypted_content.decrypted_content_id = decrypted_content.id
```

#### 3. Preview Content State
```python
# Превью версия для публичного доступа
preview_content = StoredContent(
    hash="sha256:ghi789...",
    encrypted=False,
    content_type="audio",
    file_size=small_size,  # Урезанная версия
    tags=["preview"],
    parent_content_id=encrypted_content.id,  # Связь с оригиналом
    my_network_enabled=True
)
```

### Content State Relationship Model

```sql
-- Новая таблица для управления связями контента
CREATE TABLE content_relationships (
    id UUID PRIMARY KEY,
    parent_content_id UUID REFERENCES stored_content(id),
    child_content_id UUID REFERENCES stored_content(id),
    relationship_type VARCHAR(32) NOT NULL,  -- 'encrypted', 'decrypted', 'preview'
    created_at TIMESTAMP DEFAULT NOW(),
    
    UNIQUE(parent_content_id, child_content_id, relationship_type)
);

-- Индексы для производительности
CREATE INDEX idx_content_rel_parent ON content_relationships(parent_content_id);
CREATE INDEX idx_content_rel_child ON content_relationships(child_content_id);
CREATE INDEX idx_content_rel_type ON content_relationships(relationship_type);
```

## Алгоритмы Репликации Всех Состояний

### 1. Multi-State Replication Algorithm

```python
class ContentStateReplicator:
    async def replicate_content_group(self, content_group: ContentGroup):
        """
        Реплицирует группу связанных состояний контента
        """
        # Шаг 1: Определить все связанные состояния
        states = await self.discover_content_states(content_group.root_id)
        
        # Шаг 2: Проверить целостность связей
        await self.verify_state_relationships(states)
        
        # Шаг 3: Создать план репликации
        replication_plan = await self.create_replication_plan(states)
        
        # Шаг 4: Выполнить репликацию по плану
        for batch in replication_plan.batches:
            await self.replicate_batch(batch)
            await self.verify_batch_integrity(batch)
        
        # Шаг 5: Обновить метаданные о репликации  
        await self.update_replication_metadata(content_group, states)
```

### 2. State Discovery Algorithm

```python
async def discover_content_states(root_content_id: str) -> List[ContentState]:
    """
    Обнаруживает все связанные состояния контента
    """
    states = []
    visited = set()
    
    # BFS поиск всех связанных состояний
    queue = [root_content_id]
    
    while queue:
        content_id = queue.pop(0)
        if content_id in visited:
            continue
            
        visited.add(content_id)
        content = await StoredContent.get_by_id(content_id)
        
        if not content:
            continue
            
        states.append(ContentState(
            content=content,
            relationships=await self.get_relationships(content_id)
        ))
        
        # Добавить связанные состояния в очередь
        relationships = await self.get_relationships(content_id)
        for rel in relationships:
            if rel.child_content_id not in visited:
                queue.append(rel.child_content_id)
    
    return states
```

### 3. Atomic State Replication

```python
class AtomicStateReplication:
    async def replicate_state_group(self, states: List[ContentState], 
                                   target_peers: List[PeerNode]):
        """
        Атомарная репликация группы состояний
        """
        transaction_id = str(uuid4())
        
        try:
            # Phase 1: Prepare - подготовка к репликации
            await self.prepare_replication(transaction_id, states, target_peers)
            
            # Phase 2: Transfer - передача данных
            for state in states:
                await self.transfer_state(state, target_peers, transaction_id)
            
            # Phase 3: Verify - проверка целостности
            verification_results = await self.verify_replicated_states(
                states, target_peers, transaction_id
            )
            
            # Phase 4: Commit or Abort
            if all(verification_results):
                await self.commit_replication(transaction_id, target_peers)
            else:
                await self.abort_replication(transaction_id, target_peers)
                raise ReplicationError("State verification failed")
                
        except Exception as e:
            await self.cleanup_failed_replication(transaction_id, target_peers)
            raise e
```

## MY Network Service Layer

### Service Component Architecture

```python
# MY Network Service Manager
class MYNetworkService:
    def __init__(self):
        self.p2p_manager = P2PManager()
        self.consensus_engine = ConsensusEngine()
        self.replication_manager = ReplicationManager()
        self.sync_coordinator = SyncCoordinator()
        self.content_discovery = ContentDiscoveryService()
        
    async def start_service(self):
        """Запуск MY Network сервиса"""
        await self.p2p_manager.initialize()
        await self.consensus_engine.start()
        await self.replication_manager.start()
        await self.sync_coordinator.start()
        
        # Регистрация в сети
        await self.register_node()
        
    async def register_node(self):
        """Регистрация ноды в MY Network"""
        node_info = {
            "node_id": self.get_node_id(),
            "address": self.get_public_address(),
            "capabilities": self.get_node_capabilities(),
            "content_stats": await self.get_content_statistics()
        }
        
        await self.p2p_manager.announce_node(node_info)
```

### P2P Communication Layer

```python
class P2PManager:
    def __init__(self):
        self.peers = {}
        self.message_handlers = {}
        self.connection_pool = ConnectionPool()
        
    async def handle_peer_message(self, peer_id: str, message: dict):
        """Обработка сообщений от пиров"""
        msg_type = message.get("type")
        handler = self.message_handlers.get(msg_type)
        
        if handler:
            await handler(peer_id, message)
        else:
            logger.warning(f"Unknown message type: {msg_type}")
    
    async def broadcast_content_announcement(self, content: StoredContent):
        """Анонс нового контента в сети"""
        announcement = {
            "type": "content_announcement",
            "content_hash": content.hash,
            "content_type": content.content_type,
            "encrypted": content.encrypted,
            "file_size": content.file_size,
            "timestamp": datetime.utcnow().isoformat()
        }
        
        # Отправка всем активным пирам
        for peer_id in self.get_active_peers():
            await self.send_message(peer_id, announcement)
```

### Consensus Engine Implementation

```python
class ConsensusEngine:
    def __init__(self, min_quorum: int = 3):
        self.min_quorum = min_quorum
        self.pending_votes = {}
        self.consensus_results = {}
        
    async def propose_content(self, content_hash: str) -> bool:
        """Предложение контента для консенсуса"""
        proposal_id = str(uuid4())
        
        proposal = {
            "id": proposal_id,
            "content_hash": content_hash,
            "proposer": self.node_id,
            "timestamp": datetime.utcnow(),
            "votes": {},
            "status": "pending"
        }
        
        self.pending_votes[proposal_id] = proposal
        
        # Отправка предложения пирам
        await self.broadcast_proposal(proposal)
        
        # Ожидание консенсуса с таймаутом
        result = await self.wait_for_consensus(proposal_id, timeout=30)
        return result
    
    async def vote_on_proposal(self, proposal_id: str, vote: bool):
        """Голосование по предложению"""
        if proposal_id not in self.pending_votes:
            return False
            
        proposal = self.pending_votes[proposal_id]
        proposal["votes"][self.node_id] = {
            "vote": vote,
            "timestamp": datetime.utcnow(),
            "signature": await self.sign_vote(proposal_id, vote)
        }
        
        # Проверка достижения консенсуса
        await self.check_consensus(proposal_id)
```

## Content Discovery & Routing

### Distributed Hash Table (DHT) для Content Discovery

```python
class ContentDHT:
    def __init__(self, node_id: str):
        self.node_id = node_id
        self.routing_table = {}
        self. content_index = {}
        
    async def announce_content(self, content_hash: str, content_info: dict):
        """Анонс контента в DHT"""
        key_hash = self.hash_key(content_hash)
        responsible_nodes = await self.find_responsible_nodes(key_hash)
        
        for node in responsible_nodes:
            await self.store_content_info(node, content_hash, content_info)
    
    async def find_content(self, content_hash: str) -> List[PeerInfo]:
        """Поиск нод с контентом"""
        key_hash = self.hash_key(content_hash)
        responsible_nodes = await self.find_responsible_nodes(key_hash)
        
        peers_with_content = []
        for node in responsible_nodes:
            content_info = await self.get_content_info(node, content_hash)
            if content_info:
                peers_with_content.extend(content_info.get("peers", []))
        
        return peers_with_content
```

### Smart Content Routing

```python
class ContentRouter:
    def __init__(self):
        self.peer_metrics = {}
        self.content_popularity = {}
        
    async def find_optimal_peers(self, content_hash: str, 
                               count: int = 3) -> List[PeerInfo]:
        """Поиск оптимальных пиров для загрузки"""
        available_peers = await self.content_dht.find_content(content_hash)
        
        # Сортировка по метрикам производительности
        scored_peers = []
        for peer in available_peers:
            score = await self.calculate_peer_score(peer, content_hash)
            scored_peers.append((peer, score))
        
        # Возврат топ пиров
        scored_peers.sort(key=lambda x: x[1], reverse=True)
        return [peer for peer, score in scored_peers[:count]]
    
    async def calculate_peer_score(self, peer: PeerInfo, 
                                 content_hash: str) -> float:
        """Вычисление оценки пира"""
        metrics = self.peer_metrics.get(peer.node_id, {})
        
        # Факторы оценки
        latency_score = 1.0 / max(metrics.get("avg_latency", 1), 0.01)
        bandwidth_score = metrics.get("bandwidth", 1.0)
        reliability_score = metrics.get("uptime", 0.5)
        reputation_score = peer.reputation_score
        
        # Взвешенная оценка
        total_score = (
            latency_score * 0.3 +
            bandwidth_score * 0.3 +
            reliability_score * 0.2 +
            reputation_score * 0.2
        )
        
        return total_score
```

## Monitoring & Health System

### Node Health Monitoring

```python
class NodeHealthMonitor:
    def __init__(self):
        self.health_metrics = {}
        self.alert_thresholds = {
            "cpu_usage": 80.0,
            "memory_usage": 85.0,
            "disk_usage": 90.0,
            "network_latency": 1000.0,  # ms
            "peer_count": 3  # minimum
        }
    
    async def collect_health_metrics(self) -> dict:
        """Сбор метрик здоровья ноды"""
        return {
            "cpu_usage": await self.get_cpu_usage(),
            "memory_usage": await self.get_memory_usage(),
            "disk_usage": await self.get_disk_usage(),
            "network_latency": await self.measure_network_latency(),
            "peer_count": len(await self.get_active_peers()),
            "sync_status": await self.get_sync_status(),
            "timestamp": datetime.utcnow().isoformat()
        }
    
    async def check_health_alerts(self, metrics: dict):
        """Проверка критических состояний"""
        alerts = []
        
        for metric, value in metrics.items():
            threshold = self.alert_thresholds.get(metric)
            if threshold and value > threshold:
                alerts.append({
                    "metric": metric,
                    "value": value,
                    "threshold": threshold,
                    "severity": "critical" if value > threshold * 1.2 else "warning"
                })
        
        if alerts:
            await self.send_health_alerts(alerts)
```

### Performance Analytics

```python
class PerformanceAnalyzer:
    def __init__(self):
        self.metrics_storage = MetricsStorage()
        
    async def analyze_replication_performance(self) -> dict:
        """Анализ производительности репликации"""
        recent_replications = await self.get_recent_replications(hours=24)
        
        analysis = {
            "total_replications": len(recent_replications),
            "success_rate": self.calculate_success_rate(recent_replications),
            "average_time": self.calculate_average_time(recent_replications),
            "throughput": self.calculate_throughput(recent_replications),
            "failed_replications": self.get_failed_replications(recent_replications)
        }
        
        return analysis
    
    async def generate_performance_report(self) -> dict:
        """Генерация отчета о производительности"""
        return {
            "network_performance": await self.analyze_network_performance(),
            "replication_performance": await self.analyze_replication_performance(),
            "consensus_performance": await self.analyze_consensus_performance(),
            "content_distribution": await self.analyze_content_distribution(),
            "peer_performance": await self.analyze_peer_performance()
        }
```

## Security Architecture

### Multi-Layer Security Model

```
┌─────────────────────────────────────────┐
│           Application Security          │  <- Existing auth & validation
├─────────────────────────────────────────┤
│           Network Security              │  <- MY Network specific
├─────────────────────────────────────────┤
│          Transport Security             │  <- TLS/mTLS
├─────────────────────────────────────────┤
│          Content Security               │  <- Encryption & integrity
└─────────────────────────────────────────┘
```

### Network Security Implementation

```python
class NetworkSecurity:
    def __init__(self):
        self.node_keypair = self.load_or_generate_keypair()
        self.trusted_nodes = set()
        self.blacklisted_nodes = set()
        
    async def verify_peer_identity(self, peer_id: str, 
                                 signature: str, message: bytes) -> bool:
        """Проверка подлинности пира"""
        public_key = await self.get_peer_public_key(peer_id)
        if not public_key:
            return False
            
        return await self.verify_signature(public_key, signature, message)
    
    async def encrypt_message(self, message: bytes, 
                            recipient_public_key: bytes) -> bytes:
        """Шифрование сообщения для получателя"""
        # Используем ECIES для асимметричного шифрования
        encrypted = await self.ecies_encrypt(message, recipient_public_key)
        return encrypted
    
    async def validate_content_integrity(self, content_hash: str, 
                                       content_data: bytes) -> bool:
        """Проверка целостности контента"""
        calculated_hash = hashlib.sha256(content_data).hexdigest()
        return calculated_hash == content_hash
```

## Scalability Considerations

### Horizontal Scaling Strategies

1. **Sharding по Content Hash**
   - Контент распределяется по нодам на основе хеша
   - Consistent hashing для равномерного распределения
   - Автоматическое перебалансирование при изменении топологии

2. **Hierarchical Network Structure**
   - Bootstrap ноды как суперноды
   - Региональные кластеры
   - Edge ноды для локального кеширования

3. **Adaptive Replication**
   - Динамическое изменение количества реплик
   - Репликация популярного контента на больше нод
   - Удаление неиспользуемого контента

### Resource Management

```python
class ResourceManager:
    def __init__(self):
        self.storage_limits = {}
        self.bandwidth_limits = {}
        self.connection_limits = {}
        
    async def allocate_resources(self, operation_type: str, 
                               resource_requirements: dict) -> bool:
        """Выделение ресурсов для операции"""
        if not await self.check_available_resources(resource_requirements):
            return False
            
        await self.reserve_resources(operation_type, resource_requirements)
        return True
    
    async def optimize_resource_usage(self):
        """Оптимизация использования ресурсов"""
        # Анализ текущего использования
        usage_stats = await self.get_resource_usage_stats()
        
        # Определение возможностей для оптимизации
        optimizations = await self.identify_optimizations(usage_stats)
        
        # Применение оптимизаций
        for optimization in optimizations:
            await self.apply_optimization(optimization)
```

## Disaster Recovery & Fault Tolerance

### Multi-Level Fault Tolerance

```python
class FaultToleranceManager:
    async def handle_node_failure(self, failed_node_id: str):
        """Обработка отказа ноды"""
        # 1. Обновление routing table
        await self.remove_failed_node(failed_node_id)
        
        # 2. Перенаправление трафика
        await self.reroute_traffic_from_failed_node(failed_node_id)
        
        # 3. Восстановление реплик
        lost_content = await self.identify_lost_content(failed_node_id)
        await self.restore_content_replicas(lost_content)
        
        # 4. Уведомление сети об отказе
        await self.broadcast_node_failure(failed_node_id)
    
    async def restore_content_replicas(self, lost_content: List[str]):
        """Восстановление потерянных реплик контента"""
        for content_hash in lost_content:
            # Поиск существующих реплик
            available_replicas = await self.find_content_replicas(content_hash)
            
            if len(available_replicas) < self.min_replica_count:
                # Создание дополнительных реплик
                target_nodes = await self.select_replication_targets(content_hash)
                await self.replicate_content(content_hash, target_nodes)
```

Эта архитектура обеспечивает надежную, масштабируемую и безопасную распределенную систему для репликации всех состояний контента с сохранением существующей функциональности системы.