Motor de transferências financeiras com partidas dobradas, desenvolvido em Node.js e TypeScript com Fastify, PostgreSQL, Redis e RabbitMQ. Cada transferência gera um débito e um crédito. Os valores são armazenados como números inteiros em centavos e retornados como strings no JSON.
Os três prints acompanham a mesma transferência de US$ 10,00 entre contas fictícias.
A API retorna HTTP 201. A conta de origem perde 1.000 centavos e a conta de destino recebe o mesmo valor.
Ao repetir a requisição com a mesma Idempotency-Key, a API devolve o ID original com Idempotent-Replay: true. Os saldos permanecem iguais e o PostgreSQL registra exatamente um débito e um crédito para a transferência.
Após o commit, o worker publica o evento da outbox no RabbitMQ. O consumidor registra a confirmação do webhook simulado com o ID da mesma transferência.
- Concorrência. As duas contas são bloqueadas com
SELECT FOR UPDATEem ordem fixa. A transferência verifica saldo, moeda e estado das contas antes de gravar os lançamentos. - Consistência financeira. A transferência, os lançamentos, a resposta idempotente e o evento da outbox são persistidos na mesma transação PostgreSQL. Triggers atualizam os saldos e validam o par de lançamentos no commit.
- Idempotência. O Redis coordena as requisições duplicadas e guarda respostas em cache. O PostgreSQL mantém a resposta original. Reutilizar a chave com dados diferentes retorna
409. - Limite de requisições. O Redis aplica um limite padrão de 100 requisições por minuto por IP. As rotas protegidas retornam
503se o controle de limite estiver indisponível. - Mensageria. O worker publica eventos com confirmação do RabbitMQ. A entrega pode ocorrer mais de uma vez. Um consumidor real pode usar o ID do evento para deduplicar mensagens.
| Caminho | Responsabilidade |
|---|---|
src/domain/transfers/ |
Erros do domínio de transferências |
src/application/transfers/ |
Caso de uso e transação financeira |
src/infrastructure/ |
Integrações com PostgreSQL, Redis e RabbitMQ |
src/interfaces/http/ |
Rotas da API Fastify |
database/schema.sql |
Tabelas, índices e triggers |
tests/ |
Testes unitários e de integração |
k6/ |
Cenário de carga |
scripts/demo-transfer.ps1 |
Demonstração no PowerShell |
docs/images/ |
Capturas da demonstração |
Com o Docker em execução, rode na raiz do projeto:
docker compose up --build -dA API está em localhost:3001. Confira o estado em localhost:3001/ready e aguarde o retorno {"status":"ready"}. O painel RabbitMQ fica em localhost:15672.
As portas locais de PostgreSQL, Redis e AMQP são 5433, 6379 e 5672. As credenciais do Compose são de desenvolvimento. O schema é aplicado na primeira inicialização do volume do PostgreSQL.
Em um banco local novo, carregue duas contas fictícias e execute o script a partir da raiz do projeto:
@'
INSERT INTO accounts (account_number, currency, balance_cents)
VALUES
('DEMO-README-SRC', 'USD', 1000000),
('DEMO-README-DST', 'USD', 0)
ON CONFLICT (account_number) DO NOTHING;
'@ | docker compose exec -T postgres psql -X -v ON_ERROR_STOP=1 -U ledger -d ledger
.\scripts\demo-transfer.ps1O SQL preserva as contas já existentes. O script busca uma conta de origem USD ativa com saldo suficiente e uma conta de destino USD ativa. A cada execução, gera uma chave nova, transfere US$ 10,00 e repete a requisição com a mesma chave para conferir a idempotência. O terminal mostra os saldos, os lançamentos e o log do webhook simulado.
Com as contas preparadas, também é possível rodar a demo pelo VS Code. Abra a paleta com Ctrl+Shift+P, escolha Tasks: Run Task e selecione Demonstração de transferência USD (3 blocos).
| Método e rota | Função |
|---|---|
GET /health |
Verifica se a aplicação responde |
GET /ready |
Verifica acesso ao PostgreSQL e ao Redis |
POST /v1/accounts |
Cria uma conta com saldo zero. Exemplo de corpo: {"currency":"USD"} |
GET /v1/accounts/:accountId |
Consulta a conta e o saldo |
POST /v1/transfers |
Registra uma transferência e exige o header Idempotency-Key com um UUID |
Exemplo de corpo para POST /v1/transfers. Substitua os IDs pelos das contas:
{
"sourceAccountId": "UUID-da-conta-de-origem",
"destinationAccountId": "UUID-da-conta-de-destino",
"amountCents": "1000",
"currency": "USD"
}As contas criadas pela API começam com saldo zero. O saldo inicial depende de um processo controlado de abertura ou importação. O SQL da demonstração prepara somente contas fictícias no banco de desenvolvimento.
Com Node.js 22 ou superior, instale as dependências e rode:
npm ci
npm test
npm run build
npm run test:integrationOs testes de integração exigem os serviços do Compose em execução e usam um schema PostgreSQL temporário integration_*. Para usar outros endereços, configure TEST_DATABASE_URL, TEST_REDIS_URL e TEST_RABBITMQ_URL.
Com o k6 instalado, informe os IDs de duas contas USD de teste. A origem precisa ter saldo suficiente para o volume de transferências.
$env:SOURCE_ACCOUNT_ID = "UUID-da-conta-com-fundos"
$env:DESTINATION_ACCOUNT_ID = "UUID-da-conta-destino"
npm run load:k6Use SOURCE_ACCOUNT_IDS e DESTINATION_ACCOUNT_IDS para distribuir a carga entre vários pares, com IDs separados por vírgula. O cenário também aceita BASE_URL, AMOUNT_CENTS, VUS e DURATION.
O limite padrão de 100 requisições por minuto pode gerar respostas 429 durante a carga. Para medir o volume de transferências processadas, ajuste RATE_LIMIT_MAX no ambiente local antes de recriar o serviço app e registre separadamente as transferências aceitas e as respostas 429.
Também é possível executar o k6 pelo Docker com os IDs definidos acima:
Get-Content .\k6\transfers.js -Raw | docker run --rm -i `
-e BASE_URL=http://host.docker.internal:3001 `
-e SOURCE_ACCOUNT_ID=$env:SOURCE_ACCOUNT_ID `
-e DESTINATION_ACCOUNT_ID=$env:DESTINATION_ACCOUNT_ID `
-e SOURCE_ACCOUNT_IDS=$env:SOURCE_ACCOUNT_IDS `
-e DESTINATION_ACCOUNT_IDS=$env:DESTINATION_ACCOUNT_IDS `
grafana/k6:latest run -

