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.