docs/ARCHITECTURE.md

Architecture Documentation

System Architecture

High-Level Overview

┌─────────────────────────────────────────────────────────────┐
│                    Client Layer                              │
│  (Web Apps, Mobile Apps, Other Services)                    │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ HTTP/REST API
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                  API Gateway Layer                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  FastAPI Application                                  │  │
│  │  - Request Validation                                 │  │
│  │  - Authentication (optional)                          │  │
│  │  - Rate Limiting                                      │  │
│  └──────────────────────────────────────────────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              Application Layer                                │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Monitoring Middleware                                │  │
│  │  - Prediction Logging                                 │  │
│  │  - Data Drift Detection                              │  │
│  │  - Performance Tracking                               │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Inference Engine                                     │  │
│  │  - Async Processing                                   │  │
│  │  - Batch Handling                                     │  │
│  │  - Error Handling                                     │  │
│  └──────────────────────────────────────────────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ Model Calls
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              Model Layer                                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Transformer Models                                   │  │
│  │  - Russian BERT                                      │  │
│  │  - RoBERTa                                           │  │
│  │  - DistilBERT                                        │  │
│  │  - Ensemble Models                                   │  │
│  └──────────────────────────────────────────────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              Data Layer                                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Tokenization                                         │  │
│  │  - HuggingFace Tokenizers                             │  │
│  │  - Subword Tokenization                               │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Model Architecture Details

Transformer Model Flow

Input Text: "Путин объявил о новых мерах поддержки экономики"
    │
    ├─► Text Preprocessing
    │   └─► Normalize: "путин объявил о новых мерах поддержки экономики"
    │
    ├─► Tokenization (HuggingFace)
    │   └─► Tokens: ["[CLS]", "путин", "объявил", "о", "новых", "мерах", ...]
    │   └─► Token IDs: [101, 1234, 5678, ...]
    │
    ├─► Embedding Layer
    │   └─► [batch, seq_len, 768]
    │
    ├─► BERT Encoder (12 layers)
    │   ├─► Multi-Head Self-Attention (12 heads)
    │   ├─► Feed-Forward Network
    │   ├─► Layer Normalization
    │   └─► Residual Connections
    │   └─► Output: [batch, seq_len, 768]
    │
    ├─► Pooling
    │   └─► [CLS] token or Attention Pooling
    │   └─► [batch, 768]
    │
    ├─► Classification Head
    │   ├─► Dropout(0.3)
    │   ├─► Linear(768 → 768) + ReLU
    │   ├─► Dropout(0.3)
    │   └─► Linear(768 → num_labels)
    │   └─► Output: [batch, num_labels]
    │
    ├─► Sigmoid Activation
    │   └─► Probabilities: [batch, num_labels]
    │
    └─► Threshold Filtering (0.5)
        └─► Final Tags: ["политика", "экономика"]

Ensemble Architecture

Input: Title + Snippet
    │
    ├─► Model 1 (Russian BERT)
    │   └─► Predictions: [0.9, 0.7, 0.3, ...]
    │
    ├─► Model 2 (RoBERTa)
    │   └─► Predictions: [0.85, 0.75, 0.4, ...]
    │
    ├─► Model 3 (DistilBERT)
    │   └─► Predictions: [0.88, 0.72, 0.35, ...]
    │
    └─► Ensemble Combination
        ├─► Weighted Average (weights: [0.4, 0.3, 0.3])
        └─► Final Predictions: [0.88, 0.73, 0.35, ...]

Data Flow

Training Data Flow

Raw TSV Files
    │
    ├─► Load Data (pandas)
    │   └─► Filter nulls
    │
    ├─► Text Preprocessing
    │   ├─► Normalize text
    │   ├─► Lowercase
    │   └─► Remove special chars
    │
    ├─► Tag Processing
    │   ├─► Split tags
    │   ├─► Filter by frequency
    │   └─► Create label mapping
    │
    ├─► Data Splitting
    │   ├─► Train (dates < 2018-10-01)
    │   ├─► Validation (2018-10-01 to 2018-12-01)
    │   └─► Test (dates >= 2018-12-01)
    │
    ├─► Dataset Creation
    │   ├─► Tokenization
    │   ├─► Padding/Truncation
    │   └─► Multi-hot encoding
    │
    └─► DataLoader
        └─► Batches for training

Inference Data Flow

API Request
    │
    ├─► Request Validation (Pydantic)
    │   └─► Validate title, snippet, threshold
    │
    ├─► Text Preprocessing
    │   └─► Normalize and clean
    │
    ├─► Tokenization
    │   └─► Convert to token IDs
    │
    ├─► Model Inference
    │   └─► Forward pass through BERT
    │
    ├─► Post-processing
    │   ├─► Sigmoid activation
    │   ├─► Threshold filtering
    │   └─► Top-K selection
    │
    ├─► Monitoring
    │   ├─► Log prediction
    │   ├─► Record for drift detection
    │   └─► Track performance
    │
    └─► Response
        └─► JSON with predictions

Component Interactions

Training Pipeline

Config (Hydra)
    │
    ├─► Data Loading
    │   └─► Dataset Creation
    │
    ├─► Model Initialization
    │   └─► Load Pre-trained BERT
    │
    ├─► Training Loop
    │   ├─► Forward Pass
    │   ├─► Loss Calculation
    │   ├─► Backward Pass
    │   └─► Optimizer Step
    │
    ├─► Validation
    │   └─► Metrics Calculation
    │
    ├─► Experiment Tracking
    │   ├─► WandB Logging
    │   ├─► MLflow Tracking
    │   └─► DVC Versioning
    │
    └─► Model Checkpointing
        └─► Save Best Model

API Request Flow

HTTP Request
    │
    ├─► CORS Middleware
    │
    ├─► Monitoring Middleware
    │   └─► Start timer
    │
    ├─► Request Validation
    │   └─► Pydantic validation
    │
    ├─► Inference
    │   ├─► Text preprocessing
    │   ├─► Tokenization
    │   ├─► Model forward pass
    │   └─► Post-processing
    │
    ├─► Monitoring
    │   ├─► Log prediction
    │   ├─► Check drift
    │   └─► Update metrics
    │
    └─► HTTP Response
        └─► JSON with predictions

Technology Stack

Core ML

• PyTorch: Deep learning framework
• PyTorch Lightning: Training framework
• Transformers: HuggingFace transformers library
• Russian BERT: DeepPavlov/rubert-base-cased

API & Web

• FastAPI: Modern Python web framework
• Uvicorn: ASGI server
• Pydantic: Data validation

MLOps

• WandB: Experiment tracking
• MLflow: Model registry
• DVC: Data versioning
• Optuna: Hyperparameter tuning
• Hydra: Configuration management

Infrastructure

• Docker: Containerization
• GitHub Actions: CI/CD
• Nginx: Reverse proxy (optional)

Monitoring

• Custom Monitoring: Performance, drift, logging
• Prometheus (optional): Metrics collection
• Grafana (optional): Visualization

Scalability Considerations

Horizontal Scaling

• Stateless API design
• Load balancer support
• Multiple worker processes
• Container orchestration (Kubernetes)

Performance Optimization

• Async inference
• Batch processing
• Model quantization (future)
• GPU acceleration
• Caching (future)

High Availability

• Health checks
• Graceful degradation
• Circuit breakers (future)
• Retry mechanisms