fraudshield/specs/001-fraud-detection-engine/research.md

Research: Motor de Detecção de Fraudes Bancárias

Feature: 001-fraud-detection-engine Date: 2026-05-11 Status: Complete

1. Backend Runtime & Framework

Decision: Python 3.12 + FastAPI

Rationale:

• Python é a linguagem dominante em data science e financial services — facilita contratação e evolução futura para ML.
• FastAPI oferece async nativo, validação automática via Pydantic, OpenAPI auto-generated, e performance comparável a Node.js.
• Ecossistema rico para processamento de dados (pandas, numpy) útil para análise de transações e backtesting de regras.
• Tipagem estática com mypy alinha-se com o princípio de Test-First da constituição.

Alternatives considered:

• Node.js + Express: Bom para I/O, mas ecossistema de data processing inferior. Regras complexas seriam mais verbosas.
• Go: Performance superior, mas ecossistema de dados limitado e curva de aprendizado maior para analistas que contribuem com regras.
• Java + Spring Boot: Maduro para banking, mas verboso e lento para iteração. Overkill para MVP.

2. Frontend Framework

Decision: React 19 + TypeScript + Tailwind CSS

Rationale:

• Dashboard com múltiplos gráficos e filtros se beneficia do modelo de componentes React.
• TypeScript alinha-se com a tipagem do backend (Pydantic → TypeScript types via OpenAPI codegen).
• Tailwind CSS para velocidade de desenvolvimento e consistência visual sem CSS complexo.
• Recharts ou Tremor para gráficos de dashboard (nativos React, bem mantidos).

Alternatives considered:

• HTMX + templates Jinja2: Mais simples, mas dashboard interativo com filtros dinâmicos e real-time updates seria complexo.
• Vue 3 + Nuxt: Excelente framework, mas React tem ecossistema maior de componentes de dashboard.
• Svelte: Performance superior, mas ecossistema de componentes para dashboard ainda imaturo comparado a React.

3. Database

Decision: PostgreSQL 16

Rationale:

• Audit log imutável: PostgreSQL com triggers ou particionamento por mês atende sem complexidade adicional.
• JSONB para payload flexível das transações e regras.
• Full-text search nativo para busca em explicações.
• Window functions para cálculos de médias móveis (baseline do cliente).
• pgAudit extension para camada extra de auditoria a nível de banco.
• Row-Level Security como defesa em profundidade.

Alternatives considered:

• MongoDB: Schema flexível para transações, mas audit log imutável é mais natural em relacional. Transações ACID são essenciais para dados financeiros.
• SQLite: Ótimo para dev/local, insuficiente para concorrência em produção.
• TimescaleDB (extensão PostgreSQL): Considerar para hypertables de transações se volume crescer além de 100k/dia. Não necessário para MVP.

4. Cache & Real-Time

Decision: Redis 7

Rationale:

• Contadores em tempo real do dashboard (transações/minuto, alertas/24h) via Redis INCR + TTL.
• Cache de médias do cliente (gasto médio, localização habitual) para o motor de regras (evita JOIN pesado a cada transação).
• Rate limiting da API de ingestão.
• Pub/Sub para notificações de novos alertas no dashboard (SSE ou WebSocket).

Alternatives considered:

• Sem cache (query direta no PostgreSQL): Viável para MVP com <10k transações/dia, mas dashboard near real-time sofreria.
• Memcached: Mais simples, mas sem Pub/Sub e estruturas de dados avançadas.

5. Message Queue (Picos de Volume)

Decision: Redis Streams (MVP) → RabbitMQ (scale)

Rationale:

• Para MVP, Redis Streams oferece consumer groups, acknowledgments, e já está na stack.
• Se volume crescer, migrar para RabbitMQ que oferece dead letter queues, retry policies, e routing complexo.
• Padrão: API de ingestão → Redis Streams → Workers de processamento → PostgreSQL.
• Desacopla ingestão do processamento, essencial para os picos de 5x mencionados na spec.

Alternatives considered:

• Kafka: Overkill para MVP. Operação complexa.
• Processamento síncrono: Violaria SC-001 (2s p95) durante picos.

6. Rule Engine Architecture

Decision: Python rules engine built on Pydantic models + expression evaluator

Rationale:

• Regras são condições booleanas com peso. Exemplo: transaction.amount > customer.avg_amount * 3 → score 30.
• Pydantic models definem o schema da regra, validação automática.
• simpleeval ou lark-parser para avaliar expressões de forma segura (sem eval() nativo).
• Cada regra é uma classe Python que implementa evaluate(transaction, context) -> RuleResult.
• Conjunto de regras é carregado do PostgreSQL no boot e cacheado em memória. Reload via endpoint admin.
• Snapshot versionado: cada transação registra qual versão do ruleset foi usada (rastreabilidade → FR-005).

Alternatives considered:

• Drools (Java): Maduro mas exige JVM, complexidade desnecessária.
• Django Rules: Acoplado ao Django ORM, não adequado para FastAPI.
• JSONLogic: Bom para regras simples, limitado para expressões aritméticas complexas.

7. Testing Strategy

Decision: pytest + pytest-asyncio (backend), Vitest + React Testing Library (frontend)

Rationale:

• TDD mandatório por constituição.
• Testes de regra: dataset de transações com fraudes conhecidas → assert score, assert explicação, assert alerta.
• Testes de contrato: OpenAPI schema validation, garantir que API não quebra entre versões.
• Testes de integração: pipeline completo (API → rules → alerta → decisão).
• Testes E2E: Playwright para fluxos do analista (login → fila → avalia alerta → decide).

8. Authentication & Authorization

Decision: JWT + OAuth2/OIDC via external IdP (Keycloak ou Auth0)

Rationale:

• Spec assume identity provider externo. FastAPI tem suporte nativo a OAuth2 + JWT.
• Perfis (analista, admin, sênior) mapeados para claims no token.
• Middleware de autorização por rota verifica claims.
• Sem senhas armazenadas no FraudShield — compliance LGPD simplificada.

9. Deployment

Decision: Docker Compose (dev/local) → Kubernetes ou cloud PaaS (produção)

Rationale:

• Docker Compose para ambiente dev: PostgreSQL + Redis + API + Frontend em containers.
• Simplicidade para MVP: um docker compose up resolve.
• Produção depende de onde hospedar (AWS ECS, GCP Cloud Run, Railway, etc.). Fora do escopo do MVP decidir.