Conceitos Fundamentais

Esta seção documenta os conceitos e decisões arquiteturais mais importantes do CSGOFlip. Entender esses conceitos é essencial para qualquer desenvolvedor que vá trabalhar no projeto.

Por que Esta Seção é Importante?

O CSGOFlip é um sistema de gambling que lida com:

• 💰 Dinheiro real dos usuários
• 🎲 Resultados de jogos que precisam ser justos
• ⚡ Operações concorrentes de milhares de usuários
• 📊 Auditoria de todas as transações

Decisões erradas nesses aspectos podem causar:

• Perda financeira (para o site ou usuários)
• Processos judiciais
• Perda de confiança dos jogadores
• Vulnerabilidades de segurança

Conceitos Cobertos

Clean Architecture

Como o código é organizado em camadas independentes, permitindo:

• Trocar banco de dados sem alterar lógica de negócio
• Testar use cases sem HTTP ou banco
• Manter o código organizado mesmo com 95+ use cases

Source of Truth

CRÍTICO: De onde vem o saldo real do usuário?

Regra de Ouro

O saldo SEMPRE vem do TransactionRepository.getUserBalance(), NUNCA de user.balanceCents.

Double-Entry Bookkeeping

Como garantimos integridade financeira usando contabilidade de partida dupla:

• Toda transação tem DÉBITO e CRÉDITO
• Impossível criar dinheiro do nada
• Auditoria completa

Provably Fair

Como garantimos que os resultados não são manipulados:

• Algoritmo HMAC-SHA256
• Seeds do servidor e do cliente
• Verificação após o jogo

Snowflake IDs

Por que usamos Snowflake IDs ao invés de UUID:

• Performance de índice
• Ordenação por tempo
• Geração distribuída

Sessions vs JWT

Por que escolhemos Sessions Redis ao invés de JWT:

• Revogação instantânea
• Controle de múltiplos dispositivos
• Melhor para gambling

Diagrama de Relacionamento

┌─────────────────────────────────────────────────────────────────┐
│                        FUNDAÇÕES                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐         ┌─────────────────┐                │
│  │ Clean           │         │ Sessions        │                │
│  │ Architecture    │◄───────►│ (não JWT)       │                │
│  │                 │         │                 │                │
│  └────────┬────────┘         └────────┬────────┘                │
│           │                           │                          │
│           │      ┌────────────────────┘                          │
│           │      │                                               │
│           ▼      ▼                                               │
│  ┌─────────────────┐         ┌─────────────────┐                │
│  │ Source of       │         │ Snowflake       │                │
│  │ Truth           │◄───────►│ IDs             │                │
│  │ (Transações)    │         │                 │                │
│  └────────┬────────┘         └─────────────────┘                │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         ┌─────────────────┐                │
│  │ Double-Entry    │         │ Provably        │                │
│  │ Bookkeeping     │◄───────►│ Fair            │                │
│  │                 │         │                 │                │
│  └─────────────────┘         └─────────────────┘                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SISTEMAS DERIVADOS                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │ Depósitos│  │ Saques   │  │ Batalhas │  │ Abertura de      │ │
│  │          │  │          │  │          │  │ Caixas           │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Checklist de Entendimento

Antes de contribuir com código, certifique-se de entender:

• [ ] Por que o saldo vem de transações e não da tabela User
• [ ] Como funciona double-entry e por que toda transação precisa de par
• [ ] Como o Provably Fair garante resultados justos
• [ ] Por que usamos Sessions e não JWT
• [ ] Como Clean Architecture separa as camadas
• [ ] Por que Snowflake IDs são melhores que UUID para este caso

Regras Imutáveis

NUNCA faça isso

1. NUNCA leia saldo de user.balanceCents para operações financeiras
2. NUNCA crie uma transação sem o par (débito/crédito)
3. NUNCA gere resultado de jogo sem Provably Fair
4. NUNCA permita saque sem verificar 2FA (quando habilitado)
5. NUNCA altere logs de auditoria

SEMPRE faça isso

1. SEMPRE use TransactionRepository.getUserBalance() para saldo real
2. SEMPRE use distributed locks para operações de saldo
3. SEMPRE salve seeds do Provably Fair ANTES do jogo
4. SEMPRE valide sessão em toda requisição autenticada
5. SEMPRE log ações sensíveis no audit trail

Próximos Passos

Comece pela leitura do Source of Truth - é o conceito mais crítico e mais frequentemente mal interpretado.