Skip to content

About

Motor de transações financeiras com partidas dobradas, controle de concorrência e transferências idempotentes. Desenvolvido com Node.js, TypeScript, Fastify, PostgreSQL, Redis e RabbitMQ.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Ledger Core

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.

Demonstração

Os três prints acompanham a mesma transferência de US$ 10,00 entre contas fictícias.

1. Transferência e saldos

A API retorna HTTP 201. A conta de origem perde 1.000 centavos e a conta de destino recebe o mesmo valor.

Transferência de US$ 10,00 e saldos antes e depois

2. Idempotência e partidas dobradas

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.

Reenvio idempotente com o mesmo ID e dois lançamentos no PostgreSQL

3. Confirmação assíncrona

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.

Log do worker com a confirmação simulada

Como funciona

  • Concorrência. As duas contas são bloqueadas com SELECT FOR UPDATE em 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 503 se 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.

Estrutura

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

Execução local

Com o Docker em execução, rode na raiz do projeto:

docker compose up --build -d

A 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.

Reproduzir a demonstração no PowerShell

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.ps1

O 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).

API

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.

Testes

Com Node.js 22 ou superior, instale as dependências e rode:

npm ci
npm test
npm run build
npm run test:integration

Os 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.

Teste de carga com k6

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:k6

Use 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 -

About

Motor de transações financeiras com partidas dobradas, controle de concorrência e transferências idempotentes. Desenvolvido com Node.js, TypeScript, Fastify, PostgreSQL, Redis e RabbitMQ.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages