Solução em C# / .NET 10 para registro de lançamentos (débitos e créditos) e consolidado diário, com arquitetura de microsserviços orientada a eventos, alta disponibilidade no caminho de escrita e metas de performance documentadas para leitura de relatórios.

Um comerciante precisa:

1. Registrar lançamentos diários (débito/crédito) de forma confiável.
2. Consultar o saldo consolidado do dia, com gráficos e exportação.

flowchart LR
    User[Usuario] --> Web[CashFlow.Web]
    Web --> Auth[Auth API]
    Web --> Tx[Transactions API]
    Web --> Rpt[Reporting API]
    Tx --> ES[(EventStoreDB)]
    ES --> Relay[Transactions Relay]
    Relay --> SNS[SNS]
    SNS --> SQS[SQS]
    SQS --> Worker[Reporting Worker]
    Worker --> SQL[(reporting-db)]
    Worker --> Redis[(Redis cache)]
    Rpt --> SQL
    Rpt --> Redis

Isolamento crítico (NFR): o serviço de lançamentos não depende do consolidado. A gravação confirma após append no EventStore; a projeção para relatórios é assíncrona (SNS → SQS → Worker).

Diagramas C4 detalhados: docs/c4/.

Não é necessário criar .env, user-secrets ou editar appsettings para dev local. O fluxo padrão:

dotnet restore Aspire.CashFlow.slnx   # primeira vez — baixa pacotes NuGet
.\scripts\run-full-local.ps1

Arquivos gerados em runtime (não versionados): infra/**/generated/ — Cognito pool/client, filas SNS/SQS, etc.

Use esta tabela quando algo falhar ou precisar de ajuste fino.

Conflito de porta: o caso mais comum é 1433 já ocupada por outro SQL Server. Pare o serviço conflitante ou altere o mapeamento em infra/transactions-stack/docker-compose.yml e a connection string no AppHost.

Portas Aspire: as APIs usam portas fixas via launchSettings.json. Se o Dashboard mostrar outra porta, ajuste as variáveis CASHFLOW_*_URL nos scripts de carga.

Na raiz do repositório:

.\scripts\run-full-local.ps1

Opções úteis:

# Prometheus/Grafana com scrape HTTPS (porta 7093)
.\scripts\run-full-local.ps1 -ObservabilityHttps

# Sem stack de observabilidade
.\scripts\run-full-local.ps1 -SkipObservability

Parar tudo:

.\scripts\stop-full-local.ps1

As portas exatas aparecem no Aspire Dashboard após o AppHost subir.

1. Acesse a Web e faça login.
2. Registre um crédito e um débito na tela de fluxo de caixa.
3. Abra Relatórios e selecione a data dos lançamentos.
4. (Opcional) Exporte CSV/PDF e confira totais iguais ao dashboard.

dotnet test Aspire.CashFlow.slnx

Testes de integração usam WebApplicationFactory e, quando disponível, Docker (LocalStack / SQL).

O teste ReportingAvailabilityIsolationTests prova que a Transactions API grava lançamentos sem serviços de reporting no pipeline HTTP.

Validação manual (stack rodando):

1. Pare reporting-api e reporting-worker no Aspire Dashboard.
2. POST /api/transactions com JWT — deve retornar 200.
3. Suba reporting novamente — backlog SQS deve ser projetado.

Com a stack local em execução (run-full-local.ps1 deve permanecer ativo — não pressione Ctrl+C antes):

# Em outro terminal (stack rodando no primeiro)
.\scripts\run-reporting-load-test.ps1

Se acabou de subir a stack, aguarde endpoints:

.\scripts\run-reporting-load-test.ps1 -WaitTimeoutSeconds 120

Ou diretamente (com stack já em execução — use --no-build para não recompilar e derrubar a reporting-api):

dotnet build tests/CashFlow.Reporting.Benchmarks -p:BuildProjectReferences=false
dotnet run --project tests/CashFlow.Reporting.Benchmarks --no-build -- load `
  --url https://localhost:7090 `
  --auth-url https://localhost:7204 `
  --rate 50 `
  --duration 30

Metas em docs/reporting-slo.md e gates em ReportingLoadTestSloGates.cs: 50 RPS, ≤ 5% falhas, média < 200 ms (leituras com cache).

Com a stack ativa, em outro terminal:

.\scripts\run-transactions-load-test.ps1

URLs padrão: Auth https://localhost:7204, Transactions https://localhost:7093. Sobrescreva se necessário:

$env:CASHFLOW_AUTH_URL = "https://localhost:7204"
$env:CASHFLOW_TRANSACTIONS_URL = "https://localhost:7093"
.\scripts\run-transactions-load-test.ps1

Use .\scripts\run-*-load-test.ps1 ou dotnet run --no-build — nunca dotnet run sem --no-build com a stack rodando (recompila a API e derruba o processo no Aspire).

.\scripts\lint.ps1        # CSharpier + analisadores (build)
.\scripts\lint.ps1 -Fix   # analisadores + formatação CSharpier
.\scripts\security-audit.ps1   # vulnerabilidades em pacotes + SAST no código

Relatórios de execução: tests/CashFlow.Reporting.Benchmarks/reports/.

CashFlow/
├── Aspire.CashFlow.slnx
├── src/
│   ├── Aspire.CashFlow.AppHost/          # Orquestração .NET Aspire
│   ├── Aspire.CashFlow.ServiceDefaults/  # Auth, observabilidade, segurança compartilhada
│   ├── CashFlow.Auth.Api/
│   ├── CashFlow.Transactions.Api/
│   ├── CashFlow.Transactions.Relay/
│   ├── CashFlow.Reporting.Api/
│   ├── CashFlow.Reporting.Worker/
│   └── CashFlow.Web/
├── tests/                       # Unitários, integração, contrato, benchmarks
├── docs/                        # ADRs, SLOs, C4, roadmap, constituição
├── specs/                       # Especificações por feature (`spec.md`, contratos)
├── infra/                       # Docker Compose (LocalStack, Cognito local, observabilidade)
└── scripts/                     # run-full-local.ps1, lint.ps1, testes de carga

Repositório: github.com/adrdot/CashFlow

Pipeline GitHub Actions: .github/workflows/ci.yml — dotnet build + dotnet test em cada push/PR.

Resumo — detalhes em docs/roadmap.md:

• Deploy em Kubernetes com HPA para API/Worker e load balancer HTTP.
• Cognito Admin para gestão real de usuários.
• Federação AD/SAML/OIDC.
• Reavaliação de DynamoDB para idempotência de projeção em escala extrema (ADR 002, seção modelo de leitura).
• Secrets e JWT de produção via AWS Secrets Manager (sem chaves dev em appsettings).

Não, para dev local padrão. Docker + .NET 10 + PowerShell bastam. O run-full-local.ps1 provisiona LocalStack, Cognito, filas, secrets e injeta variáveis de ambiente no AppHost. Arquivos em infra/**/generated/ são criados automaticamente.

1. Confirme que o Docker Desktop está rodando.
2. Verifique conflitos na tabela de portas (seção Onde configurar) — especialmente 1433 (SQL Server).
3. Pare restos de execuções anteriores: .\scripts\stop-full-local.ps1
4. Se alterou portas no docker-compose.yml, atualize ConnectionStrings:reporting-db e demais endpoints no AppHost.

• Aguarde Cognito Local ready no terminal do run-full-local.ps1.
• Pool e client IDs não vêm do appsettings estático — são gerados em infra/cognito-local/generated/cognito.env e injetados pelo script.
• Credenciais demo: admin@cashflow.docker / Pass@word1 / MFA 123456.
• Se rodar o AppHost sem run-full-local.ps1, defina CASHFLOW_COGNITO_ENABLED=true e carregue o cognito.env, ou use CASHFLOW_AUTO_LOAD_COGNITO_LOCAL=true.

1. O run-full-local.ps1 deve continuar rodando no primeiro terminal (não pressione Ctrl+C).
2. Aguarde Distributed application started no Aspire Dashboard.
3. Use -WaitTimeoutSeconds 120 no script de reporting.
4. Confirme URLs no Dashboard; se diferentes, exporte CASHFLOW_AUTH_URL e CASHFLOW_REPORTING_URL.
5. Compile benchmarks antes ou deixe o script fazer: dotnet build tests/CashFlow.Reporting.Benchmarks -p:BuildProjectReferences=false.

Causa típica: dotnet run --project tests/CashFlow.Reporting.Benchmarks sem --no-build recompila CashFlow.Reporting.Api (referência do projeto) e encerra o processo em execução.

Solução: use .\scripts\run-reporting-load-test.ps1 ou dotnet run --no-build.

Rate limiting está ativo. Em dev o AppHost define Security__RateLimitingEnabled=false. Reinicie a stack via run-full-local.ps1 ou confira Security:RateLimitingEnabled em appsettings.Development.json da Reporting API.

• Prometheus: http://localhost:9090 → Status → Targets.
• Transactions HTTPS: :7093/metrics; Reporting: :7090/metrics.
• Com -ObservabilityHttps, use scrape HTTPS (cert dev ignorado no Prometheus).
• Detalhes: docs/transactions-slo.md e docs/messaging-pipeline-observability.md.

O gate de reporting usa data fixa 2026-06-12 por padrão. Funciona com cache vazio (zero state). Para dados reais, registre lançamentos na Web e passe --report-date com a data usada.

Reduza réplicas antes de subir a stack:

$env:CASHFLOW_RELAY_REPLICAS = "1"
$env:CASHFLOW_REPORTING_WORKER_REPLICAS = "1"
.\scripts\run-full-local.ps1 -SkipObservability

Scripts são PowerShell — instale PowerShell 7+. Docker Desktop deve expor host.docker.internal (observabilidade). Caminhos usam \; execute a partir da raiz do repo com pwsh ./scripts/run-full-local.ps1.

Testes de integração SQL/Redis pulam automaticamente se Docker não estiver disponível. Para executá-los, suba a stack (run-full-local.ps1) ou apenas os containers necessários (SQL + Redis + LocalStack).

Projeto de demonstração arquitetural — ajuste conforme necessário antes de uso em produção.