Backend · Projeto demonstrativo
Transactional Wallet
Backend de carteira transacional com NestJS e PostgreSQL: precisão monetária, idempotência e processamento assíncrono com Inbox e Transactional Outbox.
Desenvolvido por Nicolay Padalko como desafio técnico e projeto de portfólio. Um estudo de consistência de dados e recuperação de falhas, sem operação comercial em produção.
- Categoria
- Sistemas, sites e aplicativos
- Tipo
- Backend · Projeto demonstrativo
- Autoria
- Nicolay Padalko
- Status
- Protótipo em refinamento
O projeto em detalhes
Contexto
Como manter saldo, histórico e eventos coerentes quando uma solicitação se repete, duas operações disputam a mesma carteira, a fila fica indisponível ou um estorno chega antes da operação original?
Solução
O projeto combina regras de domínio, transações PostgreSQL e mensageria assíncrona. Saldo, lançamentos e eventos da Outbox são persistidos na mesma transação; a publicação ocorre após o commit. Idempotência e Inbox controlam repetições, enquanto reversões preservam a referência à movimentação original.
Funcionalidades
- Débitos, créditos e histórico de lançamentos (Ledger).
- Valores monetários com Decimal.js e duas casas decimais.
- Idempotência persistente por provedor e chave, com verificação do payload.
- Bloqueio por carteira com SELECT FOR UPDATE para serializar alterações.
- Inbox e Transactional Outbox para processamento assíncrono e novas tentativas.
- Estornos, compensações e tratamento de referências pendentes.
- Reconciliação para detectar divergências entre saldo e histórico.
Tecnologias utilizadas
- TypeScript
- NestJS
- Bun
- MikroORM
- PostgreSQL
- Amazon SQS
- LocalStack
- Decimal.js
Decisões de engenharia
Consistência antes da publicação
A Outbox mantém o evento pendente se a fila falhar. A entrega é pelo menos uma vez: reenvios continuam exigindo deduplicação no consumidor.
Concorrência com custo explícito
O bloqueio de linha serializa alterações na mesma carteira. Essa escolha protege o saldo, mas pode gerar contenção em carteiras muito disputadas.
Reversões rastreáveis
Movimentos compensatórios mantêm a referência à operação original. A reconciliação aponta divergências sem alterar o saldo silenciosamente.
Validação e estágio do projeto
A documentação registra nove cenários de integração aprovados em 21/10/2026, incluindo mensagem duplicada, fila indisponível e reversões. A reprodução integral da suíte em ambiente limpo permanece pendente. São resultados históricos, não uma nova execução; os testes com LocalStack não substituem validação na AWS.
