docs/architecture.md

# 🏗️ Arquitetura do Sistema

## Visão Geral

O Sistema de Análise Financeira com IA é construído com uma arquitetura modular e escalável que separa responsabilidades e permite fácil manutenção e extensão. O sistema segue princípios de design limpo e padrões de arquitetura bem estabelecidos.

## Diagrama de Arquitetura

```
┌─────────────────────────────────────────────────────────────────┐
│                 SISTEMA DE ANÁLISE FINANCEIRA COM IA            │
├─────────────────────────────────────────────────────────────────┤
│                     📱 PRESENTATION LAYER                       │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Gradio UI     │  │   REST API      │  │   WebSocket     │ │
│  │ (ui/gradio_*)   │  │   (future)      │  │   (future)      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                      🧠 BUSINESS LOGIC LAYER                    │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Ensemble AI     │  │ Market Analysis │  │ Sentiment       │ │
│  │ System          │  │ Engine          │  │ Analysis        │ │
│  │ (ai/ensemble_*) │  │ (analysis/*)    │  │ (analysis/*)    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Advanced Market │  │ Performance     │  │ Request Logger  │ │
│  │ Processing      │  │ Monitor         │  │ (utils/*)       │ │
│  │ (core/*)        │  │ (integrations/) │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                       🔧 INFRASTRUCTURE LAYER                   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Configuration   │  │ Utilities       │  │ Logging         │ │
│  │ (config/)       │  │ (utils/)        │  │ (built-in)      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ AI Models       │  │ File System     │  │ Threading       │ │
│  │ (transformers)  │  │ (pathlib)       │  │ (asyncio)       │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Estrutura de Diretórios

```
📁 Projeto/
├── 📄 app.py                           # Aplicação principal
├── 📄 requirements.txt                 # Dependências
├── 📄 README.md                        # Documentação principal
├── 📄 CHANGELOG.md                     # Histórico de mudanças
│
├── 📁 src/                             # Código fonte organizado
│   ├── 📁 ai/                          # Modelos de IA e ensemble
│   │   ├── 📄 __init__.py
│   │   ├── 📄 ensemble_ai.py           # Sistema ensemble principal
│   │   └── 📄 model_manager.py         # Gerenciamento de modelos
│   │
│   ├── 📁 analysis/                    # Análises especializadas
│   │   ├── 📄 __init__.py
│   │   ├── 📄 market_analysis.py       # Análise de mercado
│   │   └── 📄 sentiment_analysis.py    # Análise de sentimento
│   │
│   ├── 📁 core/                        # Funcionalidades centrais
│   │   ├── 📄 __init__.py
│   │   ├── 📄 advanced_market_processing.py  # Processamento avançado
│   │   └── 📄 data_processor.py        # Processamento de dados
│   │
│   ├── 📁 integrations/                # Integrações externas
│   │   ├── 📄 __init__.py
│   │   ├── 📄 performance_monitor.py   # Monitor de performance
│   │   └── 📄 real_time_integration.py # Integração tempo real
│   │
│   ├── 📁 ui/                          # Interface do usuário
│   │   ├── 📄 __init__.py
│   │   └── 📄 gradio_interface.py      # Interface Gradio
│   │
│   └── 📁 utils/                       # Utilitários
│       ├── 📄 __init__.py
│       ├── 📄 helpers.py               # Funções auxiliares
│       └── 📄 request_logger.py        # Logger de requisições
│
├── 📁 config/                          # Configurações
│   ├── 📄 __init__.py
│   └── 📄 config.py                    # Configurações principais
│
├── 📁 docs/                            # Documentação
│   ├── 📄 api-reference.md             # Referência da API
│   ├── 📄 architecture.md              # Arquitetura do sistema
│   ├── 📄 developer-guide.md           # Guia do desenvolvedor
│   ├── 📄 installation.md              # Guia de instalação
│   └── 📄 troubleshooting.md           # Solução de problemas
│
├── 📁 tests/                           # Testes automatizados
│   ├── 📄 __init__.py
│   ├── 📄 conftest.py                  # Configurações de teste
│   ├── 📄 test_ensemble_ai.py          # Testes do ensemble
│   ├── 📄 test_market_analysis.py      # Testes de análise
│   └── 📄 test_sentiment_analysis.py   # Testes de sentimento
│
├── 📁 logs/                            # Arquivos de log
├── 📁 models/                          # Modelos salvos
├── 📁 cache/                           # Cache de dados
└── 📁 __pycache__/                     # Cache Python
```

## Componentes Principais

### 1. 📱 Camada de Apresentação

#### Interface Gradio (`src/ui/gradio_interface.py`)
- **Responsabilidade**: Interface web interativa
- **Tecnologia**: Gradio 5.44.0
- **Funcionalidades**:
  - Interface de análise de sentimento
  - Visualização de resultados
  - Controles de configuração
  - Monitoramento em tempo real

### 2. 🧠 Camada de Lógica de Negócio

#### Sistema Ensemble de IA (`src/ai/ensemble_ai.py`)
- **Responsabilidade**: Coordenação de múltiplos modelos de IA
- **Modelos Suportados**:
  - FinBERT (ProsusAI/finbert)
  - RoBERTa (cardiffnlp/twitter-roberta-base-sentiment-latest)
  - Modelos customizados
- **Funcionalidades**:
  - Votação inteligente entre modelos
  - Otimização automática de pesos
  - Ensemble adaptativo

#### Análise de Mercado (`src/analysis/market_analysis.py`)
- **Responsabilidade**: Análise técnica e fundamental
- **Funcionalidades**:
  - Indicadores técnicos
  - Análise de tendências
  - Detecção de padrões
  - Cálculos de Fibonacci

#### Processamento Avançado (`src/core/advanced_market_processing.py`)
- **Responsabilidade**: Análise avançada de estrutura de mercado
- **Funcionalidades**:
  - Detecção de swing points
  - Análise de zonas de confluência
  - Reconhecimento de padrões harmônicos
  - Análise de estrutura de mercado

#### Análise de Sentimento (`src/analysis/sentiment_analysis.py`)
- **Responsabilidade**: Processamento de texto financeiro
- **Funcionalidades**:
  - Classificação de sentimento (Bullish/Bearish/Neutral)
  - Scores de confiança
  - Análise contextual financeira

### 3. 🔧 Camada de Infraestrutura

#### Sistema de Configuração (`config/config.py`)
- **Responsabilidade**: Gerenciamento centralizado de configurações
- **Funcionalidades**:
  - Configurações de modelos
  - Parâmetros de análise
  - Configurações de logging
  - Variáveis de ambiente

#### Logger de Requisições (`src/utils/request_logger.py`)
- **Responsabilidade**: Rastreamento detalhado de operações
- **Funcionalidades**:
  - Log de requisições HTTP
  - Métricas de performance
  - Debugging estruturado
  - Análise de uso

#### Monitor de Performance (`src/integrations/performance_monitor.py`)
- **Responsabilidade**: Monitoramento de sistema
- **Funcionalidades**:
  - Métricas de CPU/RAM
  - Tempo de resposta
  - Throughput de modelos
  - Alertas de performance

## Fluxo de Dados

### 1. Análise de Sentimento
```
Texto de Entrada → Pré-processamento → Ensemble AI → Votação → Resultado Final
                                    ↓
                    [FinBERT] [RoBERTa] [Custom]
                         ↓       ↓       ↓
                    [Score1] [Score2] [Score3]
                         ↓       ↓       ↓
                    Sistema de Votação Inteligente
                              ↓
                    Resultado Consolidado + Confiança
```

### 2. Análise de Mercado
```
Dados de Mercado → Processamento → Análise Técnica → Padrões → Insights
                       ↓              ↓             ↓
                 Swing Points → Confluências → Harmônicos
                       ↓              ↓             ↓
                 Níveis Chave → Zonas Críticas → Projeções
```

### 3. Sistema de Logging
```
Requisição → Request Logger → Processamento → Response Logger → Métricas
     ↓             ↓              ↓              ↓             ↓
  Timestamp → Parâmetros → Tempo Execução → Resultado → Dashboard
```

## Padrões de Design Utilizados

### 1. **Strategy Pattern**
- Implementado no sistema ensemble para diferentes estratégias de votação
- Permite trocar algoritmos de consenso dinamicamente

### 2. **Factory Pattern**
- Usado para criação de diferentes tipos de analisadores
- Facilita extensão com novos modelos

### 3. **Observer Pattern**
- Sistema de logging observa operações do sistema
- Permite monitoramento não-intrusivo

### 4. **Singleton Pattern**
- Configurações globais do sistema
- Gerenciamento de recursos compartilhados

## Escalabilidade e Performance

### Otimizações Implementadas
1. **Cache de Modelos**: Modelos carregados uma vez e reutilizados
2. **Processamento Assíncrono**: Operações não-bloqueantes
3. **Batch Processing**: Processamento em lotes para eficiência
4. **Memory Management**: Limpeza automática de recursos

### Métricas de Performance
- **Tempo de Resposta**: < 2s para análise de sentimento
- **Throughput**: > 100 análises/minuto
- **Uso de Memória**: < 2GB RAM em operação normal
- **Precisão**: > 85% em datasets de teste

## Segurança

### Medidas Implementadas
1. **Validação de Entrada**: Sanitização de todos os inputs
2. **Rate Limiting**: Prevenção de abuso da API
3. **Logging Seguro**: Não exposição de dados sensíveis
4. **Error Handling**: Tratamento seguro de exceções

## Extensibilidade

### Pontos de Extensão
1. **Novos Modelos**: Interface padronizada para adicionar modelos
2. **Novos Indicadores**: Sistema plugável de indicadores técnicos
3. **Novas Integrações**: Framework para conectar APIs externas
4. **Novos Formatos**: Suporte extensível a diferentes tipos de dados

## Monitoramento e Observabilidade

### Logs Estruturados
```json
{
  "timestamp": "2024-01-27T10:30:00Z",
  "level": "INFO",
  "component": "ensemble_ai",
  "operation": "sentiment_analysis",
  "duration_ms": 1250,
  "input_length": 150,
  "model_scores": {
    "finbert": 0.85,
    "roberta": 0.78,
    "custom": 0.82
  },
  "final_result": "bullish",
  "confidence": 0.82
}
```

### Métricas Coletadas
- Latência por componente
- Taxa de erro por modelo
- Distribuição de sentimentos
- Uso de recursos do sistema
- Padrões de uso da aplicação

## Considerações de Deployment

### Ambientes Suportados
- **Desenvolvimento**: Local com hot-reload
- **Staging**: Ambiente de testes
- **Produção**: Hugging Face Spaces

### Configurações por Ambiente
```python
# config/config.py
ENVIRONMENTS = {
    'development': {
        'debug': True,
        'model_cache': False,
        'logging_level': 'DEBUG'
    },
    'production': {
        'debug': False,
        'model_cache': True,
        'logging_level': 'INFO'
    }
}
```

Esta arquitetura garante um sistema robusto, escalável e de fácil manutenção, seguindo as melhores práticas de desenvolvimento de software.