O LedgerFlow é um sistema de gestão financeira projetado para registrar lançamentos de débito e crédito e gerar consolidações diárias de saldo. A solução adota uma arquitetura moderna baseada em DDD (Domain-Driven Design), com foco em escalabilidade, resiliência e separação de responsabilidades, promovendo uma base sólida para evolução contínua e confiável.
A arquitetura contempla dois principais serviços e uma aplicação front-end que integra as funcionalidades em uma experiência unificada:
- Aplicação Web (LedgerFlow Web): interface web, onde o comerciante interage com o sistema para lançar movimentações, consultar saldos e visualizar o consolidado. Ela se comunica com as APIs autenticadas via Keycloak, garantindo segurança e uma experiência fluida de uso.
- Serviço de Lançamentos (Transactions API): responsável pelos débitos e créditos do fluxo de caixa.
- Serviço de Consolidação (LedgerSummaries API): gera o saldo consolidado com base nas transações registradas.
A estrutura do projeto foi pensada para conduzir o leitor pela lógica da solução: inicia nas Funcionalidades, que contextualizam o domínio e os objetivos do sistema; segue para a Arquitetura e o Design, onde se detalham as decisões técnicas; continua com o Setup, que orienta a execução do ambiente; e finaliza com os Testes, responsáveis por garantir qualidade e conformidade.
As funcionalidades descritas a seguir representam o coração do sistema LedgerFlow e foram expressas em formato Gherkin, facilitando o entendimento comum entre negócio, desenvolvimento e qualidade. Esse formato torna explícito o comportamento esperado do sistema, conectando histórias de usuário à implementação de forma verificável.
O momento de definir essas funcionalidades é também um ponto crucial de alinhamento entre especialistas de domínio e de modelagem, quando se traduz o conhecimento do negócio em linguagem técnica.
É nesse estágio que o EventStorming pode desempenhar papel fundamental para a modelagem de sistemas complexos, promovendo uma visão compartilhada do fluxo de eventos, identificando comandos, agregados e fronteiras de contexto que darão forma à arquitetura do sistema.
Cenário 1: Criar uma transação de crédito com valores válidos
Dado que o usuário informa um valor maior que zero
Quando o sistema cria uma transação de crédito
Então a transação deve ser registrada com sucesso
E o tipo deve ser "Credit"
E a data de criação deve ser registrada automaticamente Cenário 2: Criar uma transação de débito com valores válidos
Dado que o usuário informa um valor maior que zero
Quando o sistema cria uma transação de débito
Então a transação deve ser registrada com sucesso
E o tipo deve ser "Debit"
E a data de criação deve ser registrada automaticamente Cenário 3: Consolidação de Saldos (saldo, créditos e débitos)
Dado que existe uma lista de transações válidas (créditos e débitos)
Quando o usuário solicitar a consolidação dos saldos
Então o sistema deve calcular e salvar o total de créditos, débitos e saldo. Cenário 4: Obter Saldos Consolidados de uma data específica
Dado que o usuário informa uma data de referência válida
E existam Saldos Consolidados para essa data
Quando o sistema processa a requisição de consulta
Então o sistema retornar todos os Saldos Consoliados com seus respectivos saldos, totais de créditos e débitos e data e horaA arquitetura do LedgerFlow foi concebida com base em princípios de Domain-Driven Design (DDD) e Clean Architecture, priorizando modularidade, separação de responsabilidades e evolução incremental.
O sistema adota um monólito modular com múltiplos artefatos de implantação, onde cada módulo — como Transactions e LedgerSummaries — é isolado logicamente e organizado por domínio, mas compartilha uma base comum de aplicação, infraestrutura e dados. Essa abordagem garante alta coesão interna, baixo acoplamento entre módulos e simplicidade operacional, mantendo a capacidade de escalar e versionar APIs de forma independente quando necessário.
Essa estrutura modular serve como base sólida para uma migração gradual para uma arquitetura distribuída, permitindo que o sistema evolua organicamente conforme a complexidade e o volume de operações aumentem.
As principais decisões arquiteturais foram formalizadas em ADRs (Architectural Decision Records), que registram o racional técnico de cada escolha. Essas decisões podem ser consultadas em detalhes no arquivo:
📘 ADRs.md
O diagrama abaixo apresenta a visão C4 de Nível 2 (App/Container) do sistema LedgerFlow, ilustrando os principais componentes, suas responsabilidades e interações dentro do ecossistema.
As WebApis e o Keycloak estão preparadas para execução em Kubernetes (K8s), promovendo escalabilidade, isolamento de responsabilidades e resiliência.
🔗 Explorar o diagrama no IcePanel
Explore para navegar interativamente pelo diagrama, visualizar as conexões entre os componentes e até subir para o Nível 1 (System Context Diagram)
A solução foi desenhada seguindo princípios de Domain-Driven Design (DDD) e Clean Architecture, com clara separação entre camadas:
- LedgerFlow — projeto de domínio, contém entidades, agregados, eventos de domínio e regras de negócio.
- LedgerFlow.Infrastructure — abstrações de persistência, mapeamentos e contexto EF Core.
- LedgerFlow.Application — implementa os casos de uso da aplicação, comandos, consultas e orquestração das regras de negócio.
- LedgerFlow.Transactions.WebApi — expõe os endpoints responsáveis pelo registro e consulta de transações (créditos e débitos).
- LedgerFlow.LedgerSummaries.WebApi — expõe os endpoints responsáveis pela consolidação e consulta dos saldos diários.
- Domain-Driven Design: Tackling Complexity in the Heart of Software, Eric Evans, 2003
- Projetar um microsserviço orientado a DDD, Learn Microsoft
- Clean Archicteture Template, Milan Jovanovic
Você pode subir o sistema de duas formas:
- Usando o Aspire .NET 10
- Usando o Docker Compose
| Serviço / Aplicação | Porta Externa (host) | Observação |
|---|---|---|
| Keycloak | 2000 | Ambiente de identidade |
| SQL Server | 2001 | Banco de dados principal |
| Transactions API | 2002 | API de transações |
| Ledger Summaries API | 2003 | API de saldos consolidados |
| Redis | 2004 | Cache |
| LedgerFlow Web | 2005 | Aplicação Web |
Certifique-se de ter Docker e .NET 10 SDK instalados.
No diretório raiz do projeto, execute:
dotnet run ledgerflow-aspire.csExplore o dashboard para monitorar recursos, logs, métricas e traces
Certifique-se de ter Docker e Docker Compose instalados.
No diretório raiz do projeto, execute:
docker-compose up -dEsse comando inicializa todos os containers necessários e aplica as migrations na base ao inicializar a transaction-api:
O sistema utiliza o Keycloak como provedor de identidade.
- Acesse a interface administrativa do Keycloak Master Admin Console com usuário admin e senha admin
- Vá até Manage realms → Create Realm → Browse Resource file.
- Faça upload do arquivo
ledgerflow-realm-export.json(fornecido com o projeto) e crie o Ledgerflow Realm - Entre no Ledgerflow Admin Console com usuário admin e senha admin para testar ou configurar algo a mais.
- Entre em clients e confirme a criação do client público (legderflow).
Os testes unitários cobrem a lógica de domínio e regras de negócio.
Para executá-los:
dotnet test LedgerFlow.Tests.UnitA aplicação web LedgerFlow Web oferece uma interface amigável para interagir com as funcionalidades do sistema, permitindo a criação de transações e consulta de saldos consolidados.
- Acesse a aplicação web em http://localhost:2005
- Faça login com o usuário admin e senha admin ou seu usuário Google.
- Explore as funcionalidades
As coleções do Postman permitem validar o comportamento funcional das APIs do LedgerFlow, simulando chamadas reais aos endpoints de transações e consolidados.
- Abra o Postman e clique em Import.
- Selecione a coleção:
ledgerflow-api.postman_collection.json - Após a importação, abra qualquer requisição e vá até a aba Authorization.
- Clique em Get New Access Token — as configurações de OAuth2 já estarão preenchidas.
- Clique em Use Token para aplicá-lo automaticamente nas requisições.
- Entre na coleção e depois em Run Collection.
- Execute as requisições para validar os endpoints das APIs.
Para medir o desempenho das APIs, utilize o script configurado em k6.js na raiz do projeto.:
- Abra o arquivo k6.js
- Selecione o endpoint que deseja testar setando na variável url do objeto request.
- Busque o token usando a aba Authorization de qualquer coleção importada pelo postman.
- Adicione o token na variável token no script k6.js
- Execute:
cd LedgerFlow
k6 run k6.jsOs testes de performance locais mostraram que o sistema manteve estabilidade e baixa latência mesmo sob carga constante. Ambos os endpoints responderam 100% das requisições com sucesso, apresentando boa vazão e tempos de resposta consistentes, adequados para uso em produção.
O endpoint de consulta de saldos consolidados com cache apresentou um desempenho excelente, com 5.999 requisições processadas com sucesso e tempo médio de resposta de apenas 3,78 ms, indicando alta eficiência em operações de consulta.
O endpoint de criação de transações de crédito manteve estabilidade sob carga, processando 1.001 requisições com sucesso e tempo médio de resposta de 43,5 ms, com picos ocasionais esperados para operações de gravação.
