Forem: Carlos Henrique dos Santos

Construindo a Arquitetura de uma Casa de Apostas Escalável: Um Estudo Prático com Spring Boot e Kafka (1/n)

Carlos Henrique dos Santos — Tue, 02 Dec 2025 16:20:10 +0000

Este artigo é o primeiro de uma série onde quero compartilhar um desafio técnico que enfrentei recentemente e que acabou me motivando a escrever sobre o assunto. Pediram que eu desenhasse a arquitetura de uma plataforma de apostas — um sistema que lida com eventos o tempo todo, escala enorme e a necessidade de tudo funcionar sem parar. Decidi transformar essa experiência em conteúdo não só para registrar um pouco do que sei, mas também para mostrar como penso e como costumo resolver problemas desse porte.

Nesta série, você vai desde a concepção da arquitetura até a implementação do POC, passando também por infraestrutura e deploy usando GitOps, Kubernetes e ArgoCD. É uma forma que encontrei de abrir minha caixa de ferramentas e, ao mesmo tempo, me desafiar a explicar de forma clara aquilo que estou pensando enquanto estou projetando.

Introdução — O Problema Apresentado

O ponto de partida deste projeto foi um desenho simples, mas que representa um cenário extremamente comum no domínio de apostas esportivas: uma aposta acumulada (multi-selection) composta por dois eventos distintos, ambos ainda pendentes.

Nesse exemplo, o usuário realizou uma aposta (BetId 123) composta por:

Seleção 1: Liverpool vs Manchester City
Seleção 2: Real Madrid vs Barcelona

Ambos os jogos estão em andamento e, portanto, cada seleção e a aposta como um todo encontram-se no estado pendente.

Quando os jogos terminam, chega ao sistema a informação do resultado final via WEBHOOK. Após processar cada evento, o sistema deverá ser capaz de:

atualizar as seleções relacionadas;
recalcular o status da aposta como um todo;
disparar notificações;
acionar o fluxo de pagamento em caso de vitória.

O desenho mostrava o estado inicial e o estado final esperado — após ambos os jogos terminarem, a aposta deveria ser marcada como vencida.

Requisitos do sistema

Além do desenho, foram apresentados requisitos de desempenho e resiliência que definem a complexidade do problema.

O banco de dados contém mais de 500 milhões de apostas pendentes, referentes a múltiplos eventos.
O sistema deve ser capaz de processar 500 mil liquidações por minuto (liquidação = resultado recebido para um evento).
Deve ser capaz de enviar 500 mil notificações de pagamento por minuto para o serviço de Pagamentos.
Deve atualizar 500 mil apostas por minuto no banco de dados.
A latência total por aposta deve ser inferior a 1 minuto.
Degradações do serviço devem ser consideradas (degradações só podem aumentar a latência, nunca causar perdas operacionais ou lacunas no processamento).

O Gatilho Inicial — O Webhook de Resultado

No nosso fluxo, o webhook é o gatilho externo que informa que um jogo terminou.
Ele chega ao sistema como uma requisição HTTP enviada automaticamente pelo provedor com:

{
  "matchExternalId": "987654321",
  "homeScore": 2,
  "awayScore": 1,
  "status": "FINISHED",
  "providerEventId": "prov-1"
}

É a partir desse ponto que toda a liquidação começa.

O problema: o provedor envia o webhook apenas uma vez

Durante a entrevista, foi destacado um ponto crítico:

O provedor não reenviará o webhook em caso de falha.

Ou seja, se não garantirmos o armazenamento ou encaminhamento desse dado, o sistema corre o risco de perder o resultado do jogo, gerando apostas não liquidadas e inconsistência financeira.

Como o sistema garante que o evento não seja perdido

A minha estratégia para resolver esse problema consiste em tentar publicar no Kafka matches.result.v1 e, em caso de falha, seja por:

indisponibilidade temporária do broker,
timeout de rede,
erro de serialização,

o serviço entra em modo de retry:

tentamos reenviar N vezes,
com intervalo incremental entre tentativas (exponential backoff).

Isso resolve a maior parte dos problemas momentâneos.

Nesse momento, o entrevistador questionou: Mas e se mesmo assim o sistema continuar falhando?

Se, mesmo após todas as tentativas, o envio não for possível, adicionaremos um circuit breaker, pararemos de tentar enviar ao Kafka por um tempo e ativaremos o mecanismo de fallback. Nesse caso, iremos persistir o evento em uma tabela específica. Essa técnica é conhecida como padrão Outbox — ela garante que, ao gravarmos algo no banco de dados, o evento correspondente também seja registrado de forma atômica, mesmo que o broker de mensagens esteja indisponível. Com isso, protegemos o sistema de si próprio e evitando o volume excessivo de erros.

Fallback: gravamos o webhook em um banco Postgres

Quando o circuit breaker abre, persistimos o evento em uma tabela específica:

o payload completo do webhook;
o timestamp de recebimento.

Isso garante que:

mesmo que o Kafka esteja fora do ar ou inatingível, o evento está preservado e poderá ser reprocessado mais tarde.

A tabela sugerida para armazenar os dados é bem simples.

CREATE TABLE webhook_events_fallback (
  id         UUID PRIMARY KEY,
  payload    JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  status     TEXT NOT NULL DEFAULT 'PENDING'  -- PENDING | RESENT | FAILED
);

Depois, um job/worker pode tentar:

ler os registros PENDING desta tabela,
republicar webhook.events.received.v1,
marcar o evento como RESENT ou FAILED.

Para implementar o worker e tentar reenviar a mensagem, podemos usar o @Scheduled do próprio Spring Boot para realizar esse trabalho.

Basicamente, ele precisará ir até o banco de dados e buscar por eventos com status PENDING. Só que isso pode gerar um problema se não tomarmos cuidado. Como poderemos ter muitas instâncias dessa aplicação rodando simultaneamente, o mesmo worker pode pegar eventos repetidos e acabar enviando o mesmo dado repetidas vezes.

Para resolver isso, podemos basicamente executar a query da seguinte maneira:

select *
from webhook_events_fallback
where status = 'PENDING'
order by created_at asc
limit :limit
for update skip locked

Essa consulta irá:

FOR UPDATE: bloquear os registros selecionados para escrita, impedindo que outro processo selecione as mesmas linhas.
SKIP LOCKED: se outra thread/worker já tiver pegado alguma linha, esta consulta ignora essas linhas bloqueadas e pega as próximas disponíveis.

O objetivo aqui é:

evitar deadlocks,
impedir workers competindo pela mesma linha,
reduzir o risco de processamento duplicado.

O desenho final da solução, até esse momento, ficou dessa forma:

Encerramos aqui a primeira parte da solução. Vou continuar a próxima etapa no próximo post. Nos vemos em breve!

Github do projeto

Como descobri o Pessimistic Locking e por que isso mudou minha forma de pensar sobre concorrência

Carlos Henrique dos Santos — Sun, 20 Apr 2025 23:15:32 +0000

Recentemente participei de uma entrevista técnica do tipo whiteboard, e saí dela com algo muito mais valioso do que um possível “sim” ou “não”: aprendizado real, técnico e profundo.

Foi a partir de uma sugestão do próprio avaliador que entrei em contato com o conceito de Pessimistic Locking, e desde então mergulhei no tema para entender os riscos que sistemas financeiros enfrentam quando se trata de concorrência de dados.

Neste artigo, quero compartilhar esse processo — tanto o desafio apresentado, quanto os conceitos que aprendi depois, e como ter bons avaliadores faz toda a diferença para o crescimento profissional.

O desafio apresentado

Em um determinado momento da entrevista, o avaliador decidiu simular um caso real de construção de produto. A ideia era propor a criação de um POC - Proof of Concept (Prova de Conceito).

O projeto precisava ser simples e direto, pois a equipe estava em fase de validação do produto e procisava de algo funcional para testar o modelo de negócio com usuários o quanto antes.

Dentro desse contexto, me foi solicitado que o projetasse alguns endpoints essenciais para o sistema bancário proposto:

GET /contas/{id}/extrato Para consultar o extrato e saldo de uma conta

POST /transferencias Para permitir que um usuário envie dinheiro da conta A para a conta B.

A arquitetura deveria ser mínima, funcional e segura, e deveria atender a três pilares fundamentais:

Segurança dos dados e operações
Boas práticas REST para API
Consistência transacional, mesmo em um sistema ainda em fase inicial

Minhas escolhas e justificativas:

Usei GET para a leitura do extrato, pois é um verbo seguro e sem efeitos colateriais.
Usei POST para a criação da transferência, pois trata-se de uma operação que modifica o estado do sistema.
Os caminhos foram estruturados de forma RESTful, facilitando a compreensão e escalabilidade da API.

A proposta do avaliador era clara: mesmo sendo uma POC, o ssitema deveria se comportar como algo confiável, pois a ideia era colocar a prova um produto real, ainda que em fase de testes.

Até então, tudo parecia bem. Mas foi nesse momento que veio uma das perguntas mais importantes da entrevista, que elevou o nível do desafio:

“Como você garantiria que duas transferências simultâneas não fariam com que o mesmo saldo fosse usado duas vezes?”

E foi a partir dessa provocação que a entrevista tomou um novo rumo, um que me levou a buscar aprender mais sobre concorrência.

O que é Race Condition?

Uma race condition acontece quando duas ou mais operações acessam o mesmo recurso ao mesmo tempo e o resultado depende da ordem de execução

Por exemplo:

A conta de João possui R$ 100.00
Duas transferências de R$ 100.00 são disparadas ao mesmo tempo
Ambas leem o saldo, consideram suficiente e processam a transação

Nesse caso, João acaba transferindo R$ 200.00 com apenas R$ 100.00 de saldo

→ O sistema foi enganado por falta de controle de concorrência.

Como funcionam os locks no banco de dados?

Para evitar situações como a descrita acima, os bancos de dados implementam mecanismos de locks (bloqueio), que controlam o acesso concorrente a dados sensíveis.

O que é um lock?

Um lock impede que múltiplas transações leiam ou alterem os mesmo dados ao mesmo tempo. Ele pode ser aplicado em diferentes níveis e tipos:

Shared lock (Leitura)

Permite múltiplas leituras simultâneas
Bloqueia a escrita enquanto está ativo.
Ideal para operações de leitura que exigem consistência

Exclusive lock (Escrita)

Exclusivo: impede qualquer leitura ou escrita concorrente

Lock de linha vs Lock de tabela

Linha: bloqueia apenas o registro necessário. Permite maior concorrência
Tabela: bloqueia a tabela inteira. Mais seguro, porém menos eficiente.

Locks e transações

Locks geralmente fazem parte de transações, que seguem as regras ACID:

Atomicidade
Consistência
Isolamento
Durabilidade

Dessa forma, os locks acabam garantindo o isolamento da transação, impedindo que operações concorrentes interfiram nos dados enquanto a transação está em andamento.

O que é Pessimistic Locking?

É uma abordagem onde os dados são bloqueados no momento da leitura, assumindo que há risco real de conflito.

SQL Exemplo:

BEGIN;
SELECT * FROM contas WHERE id = 1 FOR UPDATE;
-- realiza a transferência
COMMIT;

Esse comando bloqueia a linha da conta até que a transação finalize, impedindo que qualquer outra operação use esses dados simultaneamente.

Exemplo prático com Kotlin + Spring Boot

1. Entidade

import jakarta.persistence.Entity
import jakarta.persistence.Id
import java.math.BigDecimal

@Entity
data class Conta(
    @Id val id: Long,
    var saldo: BigDecimal
)

2. Repositório com lock pessimista

import br.com.pessimistic_locking.entity.Conta
import jakarta.persistence.LockModeType
import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.data.jpa.repository.Lock
import org.springframework.data.jpa.repository.Query
import org.springframework.data.repository.query.Param
import org.springframework.stereotype.Repository

@Repository
interface ContaRepository : JpaRepository<Conta, Long> {
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT c FROM Conta c WHERE c.id = :id")
    fun findByIdForUpdate(@Param("id") id: Long): Conta
}

3. Serviço de transferência

import br.com.pessimistic_locking.repository.ContaRepository
import jakarta.transaction.Transactional
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.stereotype.Service
import java.math.BigDecimal

@Service
class ContaService(
    @Autowired private val contaRepository: ContaRepository
) {

    @Transactional
    fun transferir(origemId: Long, destinoId: Long, valor: BigDecimal) {
        val origem = contaRepository.findByIdForUpdate(origemId)
        val destino = contaRepository.findByIdForUpdate(destinoId)

        if (origem.saldo < valor) throw IllegalArgumentException("Saldo insuficiente")

        origem.saldo -= valor
        destino.saldo += valor

        contaRepository.save(origem)
        contaRepository.save(destino)
    }
}

4. Controller

@Controller
@RequestMapping("/contas")
class ContaController(
    private val service: ContaService
) {
    @GetMapping("/{id}/extrato")
    fun get(@PathVariable id: Long): ResponseEntity<Conta> = ResponseEntity.ok(service.extrato(id))
}

@Controller
@RequestMapping("/transferencias")
class TransferenciasController(
    private val service: ContaService
) {
    @PostMapping
    fun post(@RequestBody body: RequestTransferencia): ResponseEntity<Void> {
        service.transferir(
            origemId = body.origemId,
            destinoId = body.destinoId,
            valor = body.valor
        )
        return ResponseEntity.ok().build()
    }
}

data class RequestTransferencia(
    val origemId: Long,
    val destinoId: Long,
    val valor: BigDecimal

)

5. Carga de contas na base de dados

INSERT INTO public.conta
(id, saldo)
VALUES(1, 100);

INSERT INTO public.conta
(id, saldo)
VALUES(2, 100);

5. Consultado extrato

curl --request GET \
  --url http://localhost:8080/contas/1/extrato \
  --header 'User-Agent: insomnia/11.0.0'

6. Executando transferência

#!/bin/bash

echo "Iniciando teste de concorrência com duas transferências simultâneas..."

# Requisição 1 (em background)
curl --request POST \
  --url http://localhost:8080/transferencias \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/11.0.0' \
  --data '{
    "origemId": 1,
    "destinoId": 2,
    "valor": 100
}' &
PID1=$!

# Requisição 2 (em background)
curl --request POST \
  --url http://localhost:8080/transferencias \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/11.0.0' \
  --data '{
    "origemId": 1,
    "destinoId": 2,
    "valor": 100
}' &
PID2=$!

# Aguardar as duas finalizarem
wait $PID1
wait $PID2

echo "Teste finalizado."

Limitações do Pessimistic Locking

Apesar de poderoso essa abordagem possui seus trade-offs:

Desempenho impactado
1. Transações concorrentes esperam o lock ser liberado
2. Isso pode gerar lenditão em horários de pico
Risco de deadlock
1. Quando duas transações travam recursos em ordem diferentes, pode haver impasse.
2. O banco precisa cancelar uma das transações para liberar o sistema.
Acoplamento ao banco
1. Estratégia dependente de como o banco lida com transações
2. Pode dificultar migrações para bancos NoSQL ou cloud-native

Alternativas para sistema maiores

Em sistema com alta demanda, é possível utilizar estratégias diferentes:

Optimistic Locking - usa versionamento e detecta conflitos antes de salvar
Filas com mensageria (Kafka, RabbitMQ) - serializa operações por recurso
Event Sourcing e CQRS - separa leitura e escrita, com controle por eventos.

O que essa experiência me ensinou

Eu não conhecia essa abordagem a fundo antes da entrevista. Mas, graças ao avaliador que soube conduzir com clareza, paciência e provocações construtiva, saí mais preparado tecnicamente do que entrei.

Conclusão

Mais importante do que sair de uma entrvista com um “sim” ou "não”, é sair com uma certeza de que você cresceu como profissional.

Essa experiência me ensinou sobre concorrência, sobre engenharia e também sobre humildade: não saber algo é normal - o que define você é o que você faz depois disso.

Repositório do projeto → aqui 😀