# aws-event-driven-finops-platform Malha de eventos bancária na AWS onde custo entra como requisito de arquitetura - URL: https://fernando.moretes.com/open-source/aws-event-driven-finops-platform - Markdown: https://fernando.moretes.com/open-source/aws-event-driven-finops-platform/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/app-aws-event-driven-finops-platform - Homepage: https://finops.moretes.com - Language: HTML - Topics: ai, aws, banking, devsecops, event-driven-architecture, eventbridge, finops, kinesis, moretes, msk, portfolio, solution-architecture, sqs, vercel - Stars: 1 - Forks: 0 - Updated: 2026-09-29T16:21:55Z --- Este repositório é uma arquitetura de referência para uma plataforma bancária orientada a eventos na AWS. Ela coloca EventBridge, SQS, Kinesis e MSK lado a lado e diz qual usar, para qual evento e a que custo. ## Por que ele existe Em arquitetura orientada a eventos, a pergunta mais comum é "qual serviço de mensageria eu uso?". A pergunta que importa é outra: **qual garantia esse evento precisa e quanto custa mantê-la por anos?** Um `PixPaymentRequested` precisa de ordem e idempotência. Um `StatementGenerated` tolera atraso e só precisa ser entregue. Tratar os dois com o mesmo serviço é pagar a garantia mais cara para todo evento, ou dar a garantia mais fraca para o evento que não pode falhar. Trabalhando com plataformas financeiras, vi muita escolha de serviço feita por familiaridade da equipe e não pelo contrato do evento. O resultado aparece meses depois: um cluster Kafka ligado 24 horas por dia para um volume que caberia numa fila, ou uma fila sem ordem carregando transações que dependem de sequência. O repositório existe para deixar essa decisão explícita e testável. Ele modela um cenário bancário fictício, documenta os contratos de evento e os ADRs, e implementa a lógica de seleção de serviço em Python, com testes. FinOps aqui não é planilha depois do deploy, é critério de decisão desde o primeiro desenho. ## O que tem dentro - **Cenário bancário:** cinco eventos de domínio, `AccountOpened`, `PixPaymentRequested`, `TransactionAuthorized`, `FraudRiskScored` e `StatementGenerated`. - **Seleção de serviço com trade-off:** EventBridge, SQS, Kinesis Data Streams e MSK comparados pelo que cada um garante e pelo que custa. - **Lógica de decisão testada:** pacote Python com testes em `pytest`, para a regra não depender de quem lembra dela. - **Contratos de evento e ADRs** documentados em `docs/`. - **Frontend estático** em `frontend/`, com poucas dependências, publicado na Vercel em finops.moretes.com. - **Esteira de segurança:** CodeQL, Trivy, Gitleaks, dependency review e auditoria de pacotes. ## Como a malha de eventos e o repositório se encaixam À esquerda, a arquitetura de referência que o repositório descreve. À direita, o que de fato está no código: a lógica de decisão, o frontend e a esteira. ### 🟧 AWS: Roteamento e transporte - EventBridge roteamento por regra (messaging) - SQS buffer e desacoplamento (messaging) - Kinesis Data Streams ordem por partition key (messaging) - MSK Kafka para alto volume (messaging) ### 🟧 AWS: Processamento e estado - Lambda consumidores (compute) - Step Functions fluxos com várias etapas (compute) - DynamoDB idempotência e estado (data) - CloudWatch + X-Ray métricas e traces (security) ### 🔧 Repositório: o que está no código - Pacote Python lógica de seleção + pytest (compute) - docs/ contratos e ADRs (storage) - CI CodeQL, Trivy, Gitleaks (ci) - ▲ Vercel frontend estático (frontend) ### Fluxos - producer -> eb: evento de domínio - eb -> sqs: entrega desacoplada - producer -> kds: stream ordenado - producer -> msk: alto volume, compatível com Kafka - sqs -> lambda: consome - kds -> lambda: consome por shard - eb -> sfn: inicia fluxo - lambda -> ddb: grava chave de idempotência - lambda -> obs: telemetria - py -> eb: decide o serviço por evento - docs -> py: contratos orientam a regra - ci -> py: testa e varre - ci -> fe: lint e build ## Como funciona: o evento escolhe o serviço Cada serviço do repositório tem um papel e não aparece por decoração. **EventBridge:** roteamento de eventos de domínio por regra. É a porta de entrada quando vários consumidores precisam reagir ao mesmo evento sem que o produtor saiba quem são. **SQS:** buffer e desacoplamento. Quando o consumidor é mais lento que o produtor, ou fica fora do ar, a fila absorve o pico. A entrega é pelo menos uma vez, então o consumidor precisa ser idempotente. **Kinesis Data Streams:** streaming ordenado. A ordem vale dentro da mesma partition key, o que importa para eventos de uma mesma conta que dependem de sequência. **MSK:** Kafka gerenciado para volume alto e para quem já tem ecossistema Kafka. É também o item com maior custo fixo da lista, porque os brokers ficam ligados com ou sem tráfego. **Lambda e Step Functions:** processamento serverless. Step Functions entra quando o fluxo tem várias etapas e precisa de retry e compensação explícitos. **DynamoDB:** idempotência e estado do evento. Com entrega pelo menos uma vez, processar duas vezes o mesmo `TransactionAuthorized` é defeito financeiro, não detalhe técnico. **CloudWatch e X-Ray:** observabilidade. Num fluxo assíncrono, sem trace você não sabe onde o evento parou. > **O custo que pesa é o fixo:** Na conta de mensageria, o que costuma pesar não é o preço por mensagem, é a capacidade provisionada que fica ligada de madrugada sem tráfego. Por isso a seleção pergunta primeiro se o evento precisa mesmo de ordem e de retenção, antes de aceitar um cluster. ## Instalar e rodar 1. **Clone o repositório**: `git clone https://github.com/fernando-moretes/app-aws-event-driven-finops-platform.git` e entre na pasta. 2. **Instale o pacote Python em modo editável**: `python -m pip install -e . pytest`. Use um virtualenv para não misturar com o Python do sistema. 3. **Rode os testes da lógica de decisão**: `pytest -q`. É aqui que a regra de seleção de serviço é verificada; mudou a regra, o teste precisa mudar junto. 4. **Construa o frontend**: Em `frontend/`, rode `npm ci`, `npm run lint` e `npm run build`. O resultado é estático e pode ir para a Vercel sem servidor. 5. **Leia a documentação antes de adaptar**: `docs/architecture.md` traz o desenho e `OPERATIONS.md` descreve GitFlow, segredos da Vercel e a esteira de segurança. _Quickstart completo, backend e frontend_ ```bash git clone https://github.com/fernando-moretes/app-aws-event-driven-finops-platform.git cd app-aws-event-driven-finops-platform # decision logic + tests python -m pip install -e . pytest pytest -q # static frontend cd frontend npm ci npm run lint npm run build ``` ## Segurança e esteira Um repositório de referência para banco que não passa por varredura ensina o hábito errado. A esteira automatiza cinco verificações: - **CodeQL:** análise estática do código. - **Trivy:** varredura de vulnerabilidades. - **Gitleaks:** detecção de segredo commitado, o defeito mais caro de corrigir depois que o histórico foi publicado. - **Dependency review e auditoria de pacotes:** dependência vulnerável não entra por pull request sem alguém ver. O frontend é estático e leve de propósito. Cada dependência a menos é uma linha a menos no relatório do Trivy e uma atualização a menos para manter. Para uma demo de portfólio, servidor nenhum é a superfície de ataque certa. A contribuição segue GitFlow, descrito em `OPERATIONS.md`, junto com os segredos que a Vercel precisa. > **Referência, não produção:** O cenário é fictício e o repositório não traz infraestrutura como código pronta para subir numa conta. Use os contratos, os ADRs e a lógica de decisão como ponto de partida; limites, retenção e custo precisam ser medidos no seu volume real. ## Perguntas frequentes ### Preciso de conta AWS para rodar? Não. Os testes em `pytest` e o build do frontend rodam localmente, sem credencial. ### Por que MSK e Kinesis no mesmo desenho? Porque resolvem o mesmo problema com custo e operação diferentes. Kinesis quando você quer streaming ordenado gerenciado; MSK quando o volume é alto ou a equipe já opera ecossistema Kafka e aceita o custo fixo dos brokers. ### Onde fica a idempotência? No DynamoDB, como estado do evento. Com SQS e Kinesis entregando pelo menos uma vez, o consumidor precisa registrar o que já processou. ## Referências - [GitHub: fernando-moretes/app-aws-event-driven-finops-platform](https://github.com/fernando-moretes/app-aws-event-driven-finops-platform) - [Live demo: finops.moretes.com](https://finops.moretes.com) - [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) - [Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html) - [Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html) - [Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/what-is-msk.html) ## Para quem serve Use este repositório quando você está desenhando mensageria para um domínio financeiro e precisa justificar, evento por evento, por que escolheu EventBridge, SQS, Kinesis ou MSK, com custo na mesma tabela que garantia. Ele serve bem como material de revisão de arquitetura e como base para ADRs. Não use como template de deploy: ele não traz IaC, e o cenário bancário é fictício. Se o seu problema é volume e ordem medidos em produção, comece pelos contratos de evento daqui e meça o resto na sua conta. ## Links - [GitHub repository](https://github.com/fernando-moretes/app-aws-event-driven-finops-platform) - [Homepage](https://finops.moretes.com)