ARCHITECTURE.md

# 🤖 AKIRA BOT V21 — ARQUITETURA OOP

## Visão Geral

**Akira Bot V21** foi completamente refatorado com uma **arquitetura Orientada a Objetos (OOP)** moderna, modular e escalável. O código foi dividido em **6+ classes especializadas**, cada uma com responsabilidade única, totalizando mais de **3000 linhas de código bem organizado**.

## Estrutura de Diretórios

```
/index/
├── index.js                    # Arquivo principal (orquestrador)
├── index.js.old               # Backup da versão anterior
├── package.json               # Dependências
└── modules/                   # Pasta com todas as classes
    ├── ConfigManager.js       # Gerenciamento de configurações
    ├── APIClient.js           # Cliente HTTP com retry (api.py)
    ├── AudioProcessor.js      # STT, TTS, efeitos de áudio
    ├── MediaProcessor.js      # Imagens, vídeos, stickers, YouTube
    ├── MessageProcessor.js    # Análise de mensagens e contexto
    ├── ModerationSystem.js    # Moderação: mute, ban, anti-link
    └── BotCore.js             # Núcleo: Baileys wrapper, event loop
```

## Classes Principais

### 1. **ConfigManager** (Singleton)
**Arquivo:** `modules/ConfigManager.js`

Gerencia todas as configurações globais do bot.

**Responsabilidades:**
- Leitura de variáveis de ambiente
- Constantes de configuração
- Validação de configurações críticas
- Permissões de dono

**Exemplo de uso:**
```javascript
const config = ConfigManager.getInstance();
console.log(config.BOT_NUMERO_REAL);
console.log(config.isDono('244937035662', 'Isaac Quarenta'));
```

**Configurações disponíveis:**
```javascript
PORT, API_URL, API_TIMEOUT, API_RETRY_ATTEMPTS
BOT_NUMERO_REAL, BOT_NAME, BOT_VERSION, PREFIXO
TEMP_FOLDER, AUTH_FOLDER, DATABASE_FOLDER, LOGS_FOLDER
DEEPGRAM_API_KEY, DEEPGRAM_MODEL, STT_LANGUAGE
TTS_LANGUAGE, TTS_SLOW
RATE_LIMIT_WINDOW, RATE_LIMIT_MAX_CALLS
MUTE_DEFAULT_MINUTES, AUTO_BAN_AFTER_MUTES
YT_MAX_SIZE_MB, YT_QUALITY
FEATURE_STT_ENABLED, FEATURE_TTS_ENABLED, etc.
```

---

### 2. **APIClient**
**Arquivo:** `modules/APIClient.js`

Cliente HTTP para comunicação com api.py com retry automático.

**Responsabilidades:**
- Formatar payloads conforme esperado por api.py
- Requisições HTTP com retry exponencial
- Integração com vision/OCR
- Health checks

**Payload Padrão:**
```javascript
{
  usuario: 'Isaac',
  numero: '244937035662',
  mensagem: 'Oi, tudo bem?',
  tipo_conversa: 'pv',  // ou 'grupo'
  tipo_mensagem: 'texto', // ou 'audio', 'image', 'video'
  mensagem_citada: '',
  reply_metadata: {
    is_reply: false,
    reply_to_bot: false,
    quoted_author_name: '',
    context_hint: ''
  },
  historico: [],
  forcar_busca: false,
  imagem: {
    dados: 'base64...',
    mime_type: 'image/jpeg',
    descricao: 'Análise de visão'
  }
}
```

**Exemplo de uso:**
```javascript
const apiClient = new APIClient(logger);
const payload = apiClient.buildPayload({
  usuario: 'Isaac',
  numero: '244937035662',
  mensagem: 'Olá'
});
const resultado = await apiClient.processMessage(payload);
```

---

### 3. **AudioProcessor**
**Arquivo:** `modules/AudioProcessor.js`

Processa áudio: STT (Deepgram), TTS (Google), efeitos.

**Responsabilidades:**
- Speech-to-Text via Deepgram API
- Text-to-Speech via Google TTS
- Aplicação de efeitos (nightcore, slow, bass, etc.)
- Cache de TTS para performance
- Detecção de tipo de áudio

**Métodos principais:**
```javascript
speechToText(audioBuffer, language = 'pt')  // STT
textToSpeech(text, language = 'pt')         // TTS
applyAudioEffect(buffer, effect)            // Efeitos: nightcore, slow, bass, treble, echo
detectAudioType(buffer)                     // Detecta tipo (ogg, mp3, wav, etc)
```

**Exemplo:**
```javascript
const audioProc = new AudioProcessor(logger);

// STT
const transcricao = await audioProc.speechToText(audioBuffer);
console.log(transcricao.texto); // "Olá, como você está?"

// TTS
const tts = await audioProc.textToSpeech('Oi! Tudo bem?');
await sock.sendMessage(jid, { audio: tts.buffer, ptt: true });

// Efeito
const nightcore = await audioProc.applyAudioEffect(buffer, 'nightcore');
```

---

### 4. **MediaProcessor**
**Arquivo:** `modules/MediaProcessor.js`

Processa mídia: imagens, vídeos, stickers, YouTube.

**Responsabilidades:**
- Download de mídia via Baileys
- Criação de stickers (estáticos e animados)
- Conversão sticker ↔ imagem
- Download de áudio do YouTube
- Busca de músicas

**Métodos principais:**
```javascript
downloadMedia(message, mimeType)           // Download de mídia
bufferToBase64(buffer)                     // Conversão
createStickerFromImage(imageBuffer)        // Sticker de imagem
createAnimatedStickerFromVideo(videoBuffer) // Sticker animado
convertStickerToImage(stickerBuffer)       // Converte sticker para PNG
downloadYouTubeAudio(url)                  // Download de áudio YT
searchYouTube(query, limit)                // Busca no YouTube
```

**Exemplo:**
```javascript
const mediaProc = new MediaProcessor(logger);

// Download e criar sticker
const imageBuffer = await mediaProc.downloadMedia(message.imageMessage, 'image');
const sticker = await mediaProc.createStickerFromImage(imageBuffer);
await sock.sendMessage(jid, { sticker: sticker.buffer });

// YouTube
const resultado = await mediaProc.downloadYouTubeAudio('https://youtube.com/watch?v=...');
if (resultado.sucesso) {
  await sock.sendMessage(jid, { audio: resultado.buffer });
}
```

---

### 5. **MessageProcessor**
**Arquivo:** `modules/MessageProcessor.js`

Análise inteligente de mensagens e contexto.

**Responsabilidades:**
- Extração de texto, número, tipo de conversação
- Detecção de reply e contexto
- Análise de comandos
- Rate limiting
- Sanitização de texto

**Métodos principais:**
```javascript
extractUserNumber(message)                 // Número do usuário
extractText(message)                       // Extrai texto
getConversationType(message)               // 'pv' ou 'grupo'
extractReplyInfo(message)                  // Info de reply
isCommand(text)                            // É comando?
parseCommand(text)                         // Parse de comando
isBotMentioned(message)                    // Bot mencionado?
checkRateLimit(userId)                     // Verifica rate limit
```

**Exemplo:**
```javascript
const msgProc = new MessageProcessor(logger);

const numero = msgProc.extractUserNumber(message);
const texto = msgProc.extractText(message);
const tipo = msgProc.getConversationType(message); // 'pv' ou 'grupo'

const replyInfo = msgProc.extractReplyInfo(message);
if (replyInfo) {
  console.log(replyInfo.textoMensagemCitada);
  console.log(replyInfo.ehRespostaAoBot);
}

// Rate limiting
if (!msgProc.checkRateLimit(numero)) {
  console.log('Rate limit excedido!');
}
```

---

### 6. **ModerationSystem**
**Arquivo:** `modules/ModerationSystem.js`

Sistema avançado de moderação.

**Responsabilidades:**
- Mute com escalação (duplica tempo a cada mute)
- Ban permanente ou temporário
- Anti-link automático
- Anti-spam
- Contadores diários

**Métodos principais:**
```javascript
muteUser(groupId, userId, minutes)         // Muta com escalação
unmuteUser(groupId, userId)                // Remove mute
isUserMuted(groupId, userId)               // Verifica mute
banUser(userId, reason, expiresIn)         // Bane usuário
unbanUser(userId)                          // Remove ban
isBanned(userId)                           // Verifica ban
toggleAntiLink(groupId, enable)            // Ativa/desativa anti-link
isAntiLinkActive(groupId)                  // Verifica status
containsLink(text)                         // Detecta link
checkSpam(userId)                          // Verifica spam
```

**Exemplo:**
```javascript
const moderation = new ModerationSystem(logger);

// Mute
const muteResult = moderation.muteUser(groupId, userId, 5);
console.log(`Mutado por ${muteResult.minutes} minutos`);

// Anti-link
moderation.toggleAntiLink(groupId, true);
if (moderation.containsLink(texto)) {
  // Remove usuário
}

// Ban
moderation.banUser(userId, 'Spam', 24*60*60*1000); // 24h
```

---

### 7. **BotCore**
**Arquivo:** `modules/BotCore.js`

Núcleo do bot: orquestração, event loop, Baileys wrapper.

**Responsabilidades:**
- Inicialização e conexão com WhatsApp
- Main loop de processamento de mensagens
- Orquestração de todas as classes
- Gestão de estado e QR Code
- Event handling

**Métodos principais:**
```javascript
initialize()                               // Inicializa bot
connect()                                  // Conecta ao WhatsApp
getStatus()                                // Status atual
getStats()                                 // Estatísticas
getQRCode()                                // QR Code atual
```

**Fluxo de processamento:**
```
Mensagem recebida
    ↓
Deduplicação (últimos 30s)
    ↓
Verificação de ban/spam
    ↓
Verificação de mute (grupos)
    ↓
Processamento (áudio/texto)
    ↓
Extração de contexto e reply
    ↓
Verificação de rate limit
    ↓
Chamada à API (api.py)
    ↓
STT/TTS se necessário
    ↓
Envio da resposta
```

---

## Fluxo de Mensagem Detalhado

### 1. **Mensagem de Texto Recebida**
```
handleMessagesUpsert() [BotCore]
  ↓
processMessage() [BotCore]
  ├─ extractUserNumber() [MessageProcessor]
  ├─ extractText() [MessageProcessor]
  ├─ extractReplyInfo() [MessageProcessor]
  ├─ checkRateLimit() [MessageProcessor]
  ├─ buildPayload() [APIClient]
  ├─ processMessage() [APIClient] → POST /akira (api.py)
  └─ sendMessage() [BotCore]
```

### 2. **Mensagem de Áudio Recebida**
```
handleMessagesUpsert() [BotCore]
  ↓
handleAudioMessage() [BotCore]
  ├─ downloadMedia() [MediaProcessor]
  ├─ speechToText() [AudioProcessor] → Deepgram API
  ├─ [Processa como texto...]
  └─ textToSpeech() [AudioProcessor] → Google TTS
      └─ sendMessage() com áudio [BotCore]
```

### 3. **Comandos (prefixo #)**
```
Exemplo: #sticker
  ↓
isCommand() verifica prefixo
  ↓
parseCommand() extrai comando e args
  ↓
CommandHandler executa lógica
  └─ (Futuramente: classe CommandHandler)
```

---

## Conformidade com api.py

O `APIClient` formata mensagens exatamente como api.py espera:

### Exemplo: Reply em grupo
```javascript
// Usuário responde a bot em grupo
const payload = {
  usuario: 'Isaac',
  numero: '244937035662',
  mensagem: 'O que é isso?',           // Mensagem ATUAL
  tipo_conversa: 'grupo',
  tipo_mensagem: 'texto',
  mensagem_citada: 'Como posso ajudar?', // Mensagem citada COMPLETA
  reply_metadata: {
    is_reply: true,
    reply_to_bot: true,               // Flag BOT_ID
    quoted_author_name: 'Akira',
    quoted_author_numero: '244937035662',
    quoted_type: 'texto',
    context_hint: '(Usuário respondendo à mensagem do bot)'
  },
  grupo_id: '...',
  contexto_grupo: 'Meu Grupo'
}

// api.py recebe:
// - Mensagem atual para responder
// - Mensagem citada para contexto
// - Flag de reply ao bot para lógica especial
```

---

## Variáveis de Ambiente

```bash
# Servidor
PORT=3000

# WhatsApp/API
API_URL=http://localhost:8000/api/akira
BOT_NUMERO=244937035662
BOT_NAME=Akira

# STT (Deepgram)
DEEPGRAM_API_KEY=seu_token_aqui
DEEPGRAM_MODEL=nova-2
STT_LANGUAGE=pt

# TTS
TTS_LANGUAGE=pt
TTS_SLOW=false

# YouTube
YT_MAX_SIZE_MB=25
YT_QUALITY=highestaudio

# Moderação
MUTE_DEFAULT_MINUTES=5
AUTO_BAN_AFTER_MUTES=3

# Features
FEATURE_STT=true
FEATURE_TTS=true
FEATURE_YT=true
FEATURE_STICKERS=true
FEATURE_MODERATION=true
FEATURE_VISION=true
```

---

## Endpoints HTTP

### GET `/`
Página de status do bot

### GET `/qr`
QR Code para conectar

### GET `/health`
Health check

### GET `/stats`
Estatísticas detalhadas

### POST `/reset-cache`
Limpa todos os caches

### POST `/moderation/toggle-antilink`
```json
{
  "groupId": "120363...",
  "enable": true
}
```

---

## Padrões de Design Utilizados

1. **Singleton** (ConfigManager)
   - Uma única instância globalmente acessível
   
2. **Factory** (APIClient, AudioProcessor)
   - Cria instâncias com injeção de logger
   
3. **Observer** (BotCore com events)
   - Event-driven para Baileys
   
4. **Strategy** (AudioProcessor com efeitos)
   - Diferentes estratégias para processamento de áudio
   
5. **Cache** (TTLCache em APIClient)
   - Cache com expiração automática

---

## Performance e Otimizações

### Cache
- **STT Cache**: Evita re-transcrever mesmo áudio
- **TTS Cache**: Reutiliza áudios gerados
- **Media Cache**: Evita re-download

### Deduplicação
- Mensagens duplicadas ignoradas (30s)
- Impede processamento duplo em case de retry

### Rate Limiting
- Máximo 6 requisições por 8 segundos
- Proteção contra spam de comandos

### Conexão com api.py
- Retry automático (até 3 tentativas)
- Backoff exponencial (1s, 2s, 4s)
- Timeout de 120s

### Limpeza de Memória
- Maps de mute/ban auto-limpam expirados
- Cache de mensagens com limite máximo
- Spam cache com limite de 1000 entradas

---

## Exemplos de Uso

### Iniciar o bot
```bash
cd /home/elliot_pro/Programação/akira/index
node index.js
```

### Acessar status
```bash
curl http://localhost:3000/health | jq
```

### Resetar caches
```bash
curl -X POST http://localhost:3000/reset-cache
```

### Ativar anti-link em grupo
```bash
curl -X POST http://localhost:3000/moderation/toggle-antilink \
  -H "Content-Type: application/json" \
  -d '{"groupId": "120363...", "enable": true}'
```

---

## Escalabilidade Futura

### Classe CommandHandler (planejada)
```javascript
class CommandHandler {
  registerCommand(name, handler, options = {})
  executeCommand(comando, args, message)
  // Centralize todos os comandos (#sticker, #play, etc)
}
```

### Classe DatabaseManager (planejada)
```javascript
class DatabaseManager {
  saveUserData(userId, data)
  getUserData(userId)
  // Persistência de dados de usuários
}
```

### Classe LevelingSystem (planejada)
```javascript
class LevelingSystem {
  addXP(userId, amount)
  checkLevelUp(userId)
  // Sistema de leveling e patentes
}
```

---

## Dependências Principais

```json
{
  "@whiskeysockets/baileys": "^6.0.0",
  "express": "^4.18.0",
  "axios": "^1.6.0",
  "pino": "^8.0.0",
  "qrcode": "^1.5.0",
  "ffmpeg-fluent": "^2.1.2",
  "google-tts-api": "^2.0.2",
  "@distube/ytdl-core": "^4.11.5",
  "yt-search": "^2.10.0"
}
```

---

## Próximos Passos

1. ✅ Arquitetura OOP completa
2. ✅ Integração com api.py
3. ✅ STT/TTS funcional
4. ⏳ CommandHandler centralizado
5. ⏳ DatabaseManager para persistência
6. ⏳ LevelingSystem (XP, patentes)
7. ⏳ Dashboard web

---

**Versão:** 21.02.2025  
**Arquitetura:** OOP com 6+ classes especializadas  
**Status:** Pronto para produção  
**Linha de código:** ~3000+ linhas bem organizadas