<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Anderson Marques on Medium]]></title>
        <description><![CDATA[Stories by Anderson Marques on Medium]]></description>
        <link>https://medium.com/@andersonmarques.ci?source=rss-b76040a1bdfa------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*L0cnYSVfHj4JJ_zJn1y6Uw.jpeg</url>
            <title>Stories by Anderson Marques on Medium</title>
            <link>https://medium.com/@andersonmarques.ci?source=rss-b76040a1bdfa------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 12:28:12 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@andersonmarques.ci/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Do Zero ao Backstage: Automatizando CI/CD com Minikube, ArgoCD e GitHub Actions]]></title>
            <link>https://medium.com/@andersonmarques.ci/do-zero-ao-backstage-automatizando-ci-cd-com-minikube-argocd-e-github-actions-eca2533e8865?source=rss-b76040a1bdfa------2</link>
            <guid isPermaLink="false">https://medium.com/p/eca2533e8865</guid>
            <dc:creator><![CDATA[Anderson Marques]]></dc:creator>
            <pubDate>Fri, 17 Oct 2025 16:45:55 GMT</pubDate>
            <atom:updated>2025-10-17T17:22:12.793Z</atom:updated>
            <content:encoded><![CDATA[<p>Nos últimos meses, explorei uma stack para <strong>centralizar desenvolvimento e DevEx</strong> usando <strong>Backstage</strong>, <strong>Minikube</strong>, <strong>GitHub Actions Runners</strong> e <strong>ArgoCD</strong>.<br>A proposta é simples: oferecer um ambiente onde os times possam criar serviços rapidamente, já com <strong>pipeline, build e deploy automatizados</strong>, sem reinventar a roda.</p><p>Neste artigo, compartilho um passo a passo (e alguns aprendizados) que pode servir de base para quem deseja experimentar ou implantar algo parecido.</p><p>Para isso, utilizei uma stack com:</p><ul><li><strong>Minikube</strong> para simular um cluster local</li><li><strong>ArgoCD</strong> para gerenciar o ciclo de deploy</li><li><strong>GitHub Actions Runner Controller</strong> para rodar pipelines dentro do Kubernetes</li><li><strong>Backstage</strong> como portal do desenvolvedor</li></ul><h3>Mas o que é o Backstage?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PLLWH-UA5SlW1c1oPyWgng.png" /></figure><p>Criado pelo Spotify, o Backstage é uma <strong>plataforma de Developer Experience (DevEx)</strong> que organiza serviços, documentações, templates e integrações em um <strong>Developer Portal</strong>.<br>Ele permite que novos times criem aplicações padronizadas em poucos cliques, integrando nativamente com pipelines, repositórios e ferramentas já usadas pela empresa. <a href="https://backstage.io/">https://backstage.io/</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/972/1*NRWJUfC2sKhXmwRzJValHw.png" /></figure><h3>Preparando o ambiente</h3><p>Comecei pelo <strong>Minikube</strong> para simular o Kubernetes local.<br>O cluster é iniciado com um comando simples, mas tive que lidar com o problema recorrente do túnel que fica “preso” de execuções anteriores.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xA5BHwn2gDOYPNTzY7O8Mw.png" /></figure><p>Depois de subir o Minikube, configurei o <strong>Ingress como LoadBalancer</strong>. Isso foi essencial para expor o Backstage e o ArgoCD usando URLs amigáveis (.localtest.me).</p><h3>Instalando o ArgoCD</h3><p>O próximo passo foi instalar o <strong>ArgoCD via Helm</strong>. Use o arquivo values-argo.yaml que criei, nele tem o necessário para configura ingress, etc.</p><pre>helm repo add argo https://argoproj.github.io/argo-helm<br>helm repo update<br>helm upgrade --install argocd argo/argo-cd \<br>  -n argocd --create-namespace \<br>  -f values-argo.yaml \<br>  --wait</pre><pre># Concluída a instalação, o ArgoCD já disponibiliza uma senha inicial armazenada em secret no cluster.<br>kubectl get secrets -n argocd argocd-initial-admin-secret -o yamlba<br>echo &quot;&lt;ARGOCD_SECRET_BASE64&gt;&quot; | base64 -d</pre><p>Após o login (argocd login), já conseguimos ver a interface e validar o primeiro acesso. Lembre-se que nesse caso, como estamos usando o minikube é preciso manter o tunnel em execução para acessar o argocd, entre outras aplicações em execução no cluster.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0p2gkXdODAw_nU1ifs1WMQ.png" /></figure><p>Crie o namespace devops (vamos precisar lá na frente)</p><pre>kubectl create namespace devops || true</pre><h3>GitHub Actions Runner Controller (ARC)</h3><p>Com o ambiente configurado, o próximo desafio foi integrar o <strong>GitHub Actions</strong> com o Kubernetes via <strong>ARC (</strong>Actions Runner Controller) <a href="https://github.com/actions/actions-runner-controller">https://github.com/actions/actions-runner-controller</a>.</p><p><strong>Pré-requisitos rápidos:</strong></p><p>Token do GitHub: para usar PAT (Personal Access Token) ele precisa ter.</p><ul><li>Classic PAT: repo, admin:org (para runners na organização) e read:org.</li><li>OU Fine-grained PAT: habilitar “Self-hosted runners: Read/Write” para a organização (e permitir acesso aos repositórios alvos).</li></ul><p>Em Settings → Runners → Runner groups da organização, confirme:</p><ul><li>Default Allow public repositories = ON</li></ul><p><strong>Primeiro, instalei o </strong><strong>cert-manager (pré-requisito):</strong></p><pre>kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.18.2/cert-manager.yaml</pre><p><strong>Depois, fiz deploy do controller:</strong></p><pre>helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller</pre><p>Por fim, configurei o <strong>RunnerDeployment</strong> que conecta o Kubernetes à minha organização no GitHub.</p><pre>helm upgrade --install actions-runner-controller \                                                             <br>actions-runner-controller/actions-runner-controller \<br>-n actions-runner-system \<br>--set=authSecret.create=true \<br>--set=authSecret.github_token=&quot;&lt;GITHUB_PAT&gt;&quot; \<br>--wait</pre><pre>kubectl -n actions-runner-system get pods<br># deve ver algo como: actions-runner-controller-xxxxx Running (2/2)</pre><p>Um detalhe importante: o runner expira em ~1h, então precisei aprender a <strong>rotacionar o token</strong> e reiniciar o controller quando necessário.</p><pre>kubectl -n actions-runner-system apply -f - &lt;&lt;&#39;YAML&#39;  <br>apiVersion: actions.summerwind.dev/v1alpha1  <br>kind: RunnerDeployment  <br>metadata:  <br> name: org-runnersspec:  <br> replicas: 1 template: spec: organization: &lt;ORG_NAME&gt; group: Default labels: - self-hosted - Linux - X64YAML</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g8n6H-PU3ggstmgst02hIg.png" /></figure><p>Isso me deu a confiança de que os pipelines estavam rodando dentro do próprio cluster.</p><pre>kubectl get runner -n actions-runner-system</pre><h3>Entrando no Backstage</h3><p>Agora vem a parte mais empolgante do Dev Experience, o <strong>Backstage</strong>.<br>Essas etapas iniciais de configuração do Backstage vão ser bem úteis lá na frente quando estivermos gerando uma imagem e fazendo deploy dele. Comecei com a criação da aplicação usando npx @backstage/create-app.</p><pre>docker pull node:22-bookworm-slim  <br>docker run --rm \ -e AUTH_GITHUB_CLIENT_ID=&lt;GITHUB_CLIENT_ID&gt; \ -e AUTH_GITHUB_CLIENT_SECRET=&lt;GITHUB_CLIENT_SECRET&gt; \ -p 3000:3000 -p 7007:7007 \ -v /path/to/backstage-app:/app \ -w /app \ node:22-bookworm-slim bash</pre><pre>npx @backstage/create-app@latestcd my-backstage-appyarn start</pre><p>Access: <a href="http://localhost:3000/">http://localhost:3000</a></p><p>Dessa forma você já consegue ver a cara do Backstage, mas para registrar um componente no Catalog é necessário o catalog-info.yaml que mostro mais adiante, seguindo esses 3 principais pilares básicos de configuração dele (Software Catalog, Software Template e TechDocs):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/994/1*HVv_xDt-zdxqkKTULX1e0w.png" /></figure><p><a href="https://backstage.io/docs/overview/what-is-backstage">https://backstage.io/docs/overview/what-is-backstage</a></p><h3>Software Catalog</h3><p>Imagina precisar gerenciar milhares de aplicações, softwares, componentes, bibliotecas, etc. que são criados diariamente pelos times Com o Software Catalog a equipe pode gerenciar, manter, adicionar, etc. tudo o que existe no seu ecossistema, ou seja, chega de ter aquele software que ninguém sabe de quem é.</p><p>O catálogo do Backstage permite mapear ownership, lifecycle e dependências de forma padronizada. Cada componente é descrito por um catalog-info.yaml. Pode incluir Owner, System, Type e Status.</p><p>E como podemos registrar componentes que criamos antes da instalação do Backstage? Ou seja, outros componentes que minha organização já possui? É extremamente simples, basta adicionar o <em>catalog-info.yaml</em> ao seu repositório, ele deve se parecer com isso:</p><pre>apiVersion: backstage.io/v1alpha1<br>kind: Component<br>metadata:<br>  name: ${{values.app_name}}<br>  description: ${{values.app_desc}}<br>  annotations:<br>    github.com/project-slug: anderson-organization/${{values.app_name}}<br>    backstage.io/techdocs-ref: dir:.<br>spec:<br>  type: service<br>  owner: development<br>  lifecycle: experimental</pre><p>Apontando para esse arquivo é possível registrar o componente no Backstage.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6EVsIfOvvdXqz5m2KgKPwQ.png" /></figure><p>Não vou entrar no detalhe de owners, mas é possível especificar para o componente como sendo apenas um indivíduo ou configurando um grupo.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*u-UBXYkJw7yAr6jGXtk49g.png" /></figure><h3>Software Templates</h3><p>Fundamental para a criação de novos componentes e aplicações, dando ao time autonomia, velocidade e padrão arquitetural seguido pela empresa. Permite que o time escolha, por exemplo, a linguagem para aquele projeto, a estrutura, etc. Como exemplo criei um template de projeto de API REST em Go.</p><p>Busquei usar o formato padrão a seguir para novos projetos, que consiste basicamente de:</p><ul><li><strong>Dockerfile</strong> for build</li><li><strong>GitHub</strong> for repository</li><li><strong>GitHub Actions</strong> for CI/CD</li><li><strong>Docker Hub</strong> for images</li><li><strong>Helm + ArgoCD + Kubernetes</strong> for deploy</li></ul><p><a href="https://github.com/andersonmarquesgit/backstage-software-templates">GitHub - andersonmarquesgit/backstage-software-templates</a></p><p>O repo de templates contém um arquivo que define a pipeline de uso do template, ou seja, quais parâmetros preciso informar? No meu caso usei algo como o nome do componente, uma descrição e o ambiente que quero fazer o deploy:</p><p><a href="https://github.com/andersonmarquesgit/backstage-software-templates/blob/main/go-app/template.yaml">backstage-software-templates/go-app/template.yaml at main · andersonmarquesgit/backstage-software-templates</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3WcFiuBhTjbnqt-lf1btTw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/695/1*s4Gr5Rhs0mMDJacOjj9I1Q.png" /></figure><p>E para que o Backstage consiga criar e publicar repositórios no GitHub é necessário instalar o Action Module específico para ele. <a href="https://backstage.io/docs/features/software-templates/builtin-actions">Aqui</a> tem esse passo detalhado, mas basicamente é executar o seguinte comando no seu diretório do Backstage:</p><pre>yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-github</pre><p>Outra coisa que precisamos validar/importar é o o scaffolder plugin em packages/backend/src/index.</p><pre>backend.add(import(&#39;@backstage/plugin-scaffolder-backend-module-github&#39;));</pre><p>Com essas configurações, temos mais uma importante para que a integração com o GitHub funcione. Em app-config.yaml você encontrará o trecho onde são feitas as integrações do Backstage:</p><pre>integrations:<br>  github:<br>    - host: github.com<br>      # This is a Personal Access Token or PAT from GitHub. You can find out how to generate this token, and more information<br>      # about setting up the GitHub integration here: https://backstage.io/docs/integrations/github/locations#configuration<br>      token: ${GITHUB_TOKEN}<br>    ### Example for how to add your GitHub Enterprise instance using the API:<br>    # - host: ghe.example.net<br>    #   apiBaseUrl: https://ghe.example.net/api/v3<br>    #   token: ${GHE_TOKEN}</pre><p>Ela é necessária para nos conectar com sucesso ao GitHub e executar todas as operações que precisamos. Além disso precisamos definir o target de onde o Backstage encontra o template:</p><pre>    - type: url<br>      target: https://github.com/andersonmarquesgit/backstage-software-templates/blob/main/go-app/template.yaml<br>      rules:<br>        - allow: [Template]</pre><p>Bom, com repositório de templates criado, plugins e módulos GitHub instalados, já é possível utilizar o template na criação e registro do componente.</p><h3><strong>TechDocs</strong></h3><p>Com poucas configurações é possível ter praticamente um site com todo o conhecimento necessário do software, uma documentação sempre atualizada que coexiste com o seu código.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*chjOk02Vds0hKThjppF7aA.png" /></figure><p>E pra isso seu template precisa conter o diretório &quot;docs/index.md&quot; que também deixei um exemplo <a href="https://github.com/andersonmarquesgit/devops-template-app/blob/main/docs/index.md">aqui</a>.</p><pre># Documentation for ${{values.app_name}}<br><br>This application is a template for test and create components using Backstage and standard for pipeline creation using GitHub Actions, Helm, Kubernetes and ArgoCD.<br>Is possible explore all the flow using CI/CD and configurations needs for this.<br>Exist a endpoint for test the application:<br>- `/api/v1/details`<br><br>You can access using URL **http://${{values.app_name}}-${{values.app_env}}.localtest.me/api/v1/details**<br><br>```json<br>{<br>    hostname: &quot;${{values.app_name}}-${{values.app_env}}-xpto&quot;,<br>    message: &quot;New attribute message for test cicd!!&quot;,<br>    time: &quot;2025-09-17T13:58:31.212528637Z&quot;<br>}<br>```</pre><p>Para isso, precisei a dependência com Python + mkdocs, garantindo que a documentação pudesse ser compilada dentro do container.</p><pre>apt-get update &amp;&amp; \apt-get install -y python3 python3-pip python3-venv &amp;&amp; \rm -rf /var/lib/apt/lists/*  <br>python3 -m venv /opt/venvexport PATH=&quot;/opt/venv/bin:$PATH&quot;pip3 install mkdocs-techdocs-core</pre><p>O Backstage não vem com o MkDocs por padrão porque é uma biblioteca, então também precisamos adicionar ao app-config.yaml onde vamos executar a compilação do doc</p><pre>techdocs:<br>  builder: &#39;local&#39;<br>  publisher:<br>    type: &#39;local&#39;<br>  generator:<br>    runIn: local</pre><p>Na parte front-end do Backstage é necessário o uso de plugins, pode ver mais sobre sobre a instalação desse plugin <a href="https://backstage.io/docs/features/techdocs/getting-started">aqui</a>, mas nesse caso packages/app/src/App.tsx já faz essa importação e não precisamos nos preocupar:</p><pre>import {<br>  TechDocsIndexPage,<br>  techdocsPlugin,<br>  TechDocsReaderPage,<br>} from &#39;@backstage/plugin-techdocs&#39;;</pre><p>E no arquivo config-info.yaml já temos a parte do Mkdocs configurada ao usar:</p><pre>backstage.io/techdocs-ref: dir:.</pre><p>Também integrei o plugin do <strong>GitHub Actions</strong>, que mostra dentro do Backstage o status das pipelines do repositório.<br>Isso foi um divisor de águas, porque trouxe visibilidade de CI/CD diretamente para o portal.</p><pre> yarn --cwd packages/app add @backstage-community/plugin-github-actions</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a9JwjjaYnU6IeW4_luI0JQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Flp9_9Fihi58ho-HYRhsWg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/848/1*hvOS1-NmT9gzo9fFcKxB6A.png" /></figure><h3>Conclusão</h3><p>Embora esse artigo não entre em cada detalhe de configuração do Backstage, o que tornaria o conteúdo extenso demais, os repositórios complementares disponibilizados aqui trazem tudo o que você precisa para reproduzir a solução e entender a lógica por trás da automação.</p><p><strong>Repositórios utilizados:</strong></p><ul><li><a href="https://github.com/andersonmarquesgit/backstage-software-templates">backstage-software-templates</a>: contém os templates de aplicações (como o template Go) com integração a pipelines, Helm e ArgoCD.</li><li><a href="https://github.com/andersonmarquesgit/backstage-app">backstage-app</a>: portal Backstage pronto para uso, já configurado com <strong>integrações com GitHub, ArgoCD, PostgreSQL</strong> e suporte a <strong>TechDocs</strong>.</li><li><a href="https://github.com/andersonmarquesgit/devops-template-app">devops-template-app</a>: exemplo funcional de aplicação criada via template, com CI/CD completo e endpoint de teste.</li></ul><p>Em conjunto, esses projetos formam uma base sólida para construir sua própria <em>Internal Developer Platform</em> — com <strong>provisionamento automático, pipelines padronizadas, documentação viva e rastreabilidade fim a fim</strong>.</p><p>O Backstage deixa de ser apenas uma ferramenta e se torna o ponto de convergência da Developer Experience.</p><h4>💬 <strong>Lembre-se:</strong></h4><p>Developer Experience não é sobre tecnologia, é sobre permitir que times entreguem valor com autonomia, consistência e confiança.</p><h4>🔗 Explore o ecossistema completo:</h4><ul><li><a href="https://github.com/andersonmarquesgit/backstage-app">https://github.com/andersonmarquesgit/backstage-app</a></li><li><a href="https://github.com/andersonmarquesgit/backstage-software-templates">https://github.com/andersonmarquesgit/backstage-software-templates</a></li><li><a href="https://github.com/andersonmarquesgit/devops-template-app">https://github.com/andersonmarquesgit/devops-template-app</a></li></ul><h4>📚 Documentação utilizada</h4><ul><li><a href="https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/">ArgoCD Installation</a></li><li><a href="https://github.com/actions/actions-runner-controller/blob/master/docs/quickstart.md">Actions Runner Controller Quickstart</a></li><li><a href="https://backstage.io/docs/next/getting-started/">Backstage Getting Started</a></li><li><a href="https://backstage.io/docs/auth/">Backstage Auth</a></li><li><a href="https://backstage.io/docs/auth/github/provider">Backstage Auth GitHub</a></li><li><a href="https://github.com/backstage/backstage">Backstage GitHub Repo</a></li><li><a href="https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme/team-a-group.yaml">Catalog Example</a></li><li><a href="https://backstage.io/docs/features/techdocs/">TechDocs</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=eca2533e8865" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Money moved nas últimas 24h: uma vitrine de confiança usando Go, Redis e Circuit Breaker]]></title>
            <link>https://medium.com/@andersonmarques.ci/money-moved-nas-%C3%BAltimas-24h-uma-vitrine-de-confian%C3%A7a-usando-go-redis-e-circuit-breaker-b49431375d03?source=rss-b76040a1bdfa------2</link>
            <guid isPermaLink="false">https://medium.com/p/b49431375d03</guid>
            <dc:creator><![CDATA[Anderson Marques]]></dc:creator>
            <pubDate>Sun, 31 Aug 2025 21:16:00 GMT</pubDate>
            <atom:updated>2025-08-31T21:16:00.507Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Objetivo</strong>: A ideia é construir um totalizador quase<em> real‑time</em> das transferências nas últimas 24h, apresentado na moeda local do visitante, com resiliência a falhas, perfeito para uma vitrine de confiança (topo de funil) e pra um produto como a <a href="https://wise.com/br/">Wise</a>. Vai que um dia ela te pede pra desenvolver algo assim :P</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b09k5VBsT3ou-hafDJ6kRw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7hdsJmE7y0ncJfWvJNwQaw.png" /></figure><p>O <a href="https://lovable.dev/">Lovable</a> me ajudou nesse widget maneiro, dá uma experimentada :D</p><h3>TL;DR</h3><ul><li><strong>Problema</strong>: Mostrar, quase em tempo real, quanto dinheiro foi movimentado nas últimas 24h, sem pressionar sistemas core.</li><li><strong>Abordagem</strong>: Pipeline <em>event‑driven</em> que agrega por minuto em moeda base<strong> </strong>(adotei EUR pra facilitar)<strong> </strong>e converte na leitura para a moeda do visitante. Adotei o uso de um <strong>Circuit Breaker + Cache</strong> para o serviço de câmbio pra demonstrar um pouco dessa abordagem de resiliência em sistemas distribuídos.</li><li><strong>Stack</strong>: Go, Redis (Streams + Strings + Sorted Set), gobreaker, Docker Compose. Com Streams a abordagem ficou mais simples, mas nada impede de ser evoluída para RabbitMQ ou Kafka, é tudo trade-off :)</li><li><strong>Por quê</strong>: transparência que gera confiança (social proof) com baixo risco de sinal competitivo, adotando <a href="https://pt.wikipedia.org/wiki/Fuzzing"><strong>fuzzing</strong></a> no número exibido.</li></ul><h3>Contexto do produto: topo de funil</h3><ul><li>O desafio aqui é construir um número <strong>agregado, público</strong>, para aumentar <strong>conversão</strong> de potenciais clientes.</li><li>Não é por usuário, tá mais pra um <strong>card de prova de escala</strong> na landing/app.</li></ul><p>Vou assumir alguns requisitos pra gente ter de início, lembrando que é uma solução high-level. Quer melhorar a solução? Fica a vontade pra se jogar nesse <a href="https://github.com/andersonmarquesgit/money-moved">repositório</a> hehe.</p><h3>Requisitos Funcionais</h3><ol><li>Agregar o total <strong>movimentado nas últimas 24h</strong>.</li><li>Expor <strong>API</strong> que retorna o total na <strong>moeda solicitada</strong> (padrão: base).</li><li>Fornecer <strong>widget</strong> público simples (HTML) com atualização periódica.</li></ol><h3>Requisitos Não Funcionais</h3><ul><li><strong>Baixa latência</strong> de leitura (p95 &lt; 50–100 ms com Redis + CDN).</li><li><strong>Independência</strong> do Transfer Service (consumir somente eventos).</li><li><strong>Resiliência</strong>: Operar mesmo com FX intermitente (Circuit Breaker + Cache, com degradação controlada). Afinal você não quer que seu usuário não veja nenhum valor agregado se seu sistema estive fora :)</li><li><strong>Custo</strong> <strong>previsível</strong>: Agregação por minuto + TTL (~26h).</li><li><strong>Governança</strong>: Sem PII. Opção de fuzzing e disclaimers.</li></ul><h3>Decisões de arquitetura (Resumo)</h3><ul><li><strong>Moeda base</strong>: Usei EUR pra facilitar nosso exemplo. Todos os valores são agregados nessa base.</li><li><strong>Conversão</strong>: No <strong>INGEST</strong> (target para BASE) e na <strong>LEITURA</strong> (BASE para currency do visitante). O visitante também tem a opção de alterar via seleção da moeda no próprio Widget.</li><li><strong>Janela deslizante</strong>: Buckets por minuto com TTL 26h + índice de minutos (ZSET) para somar a janela de 24h.</li><li><strong>Mensageria</strong>: Redis Streams para simplicidade e consumer group caso eu queira escalar o Money Moved Service.</li><li><strong>Resiliência</strong>: gobreaker no cliente de moeda estrangeira (vou chamar de FX <em>Foreign Exchange</em>) + cache de última taxa (fallback) para quando chamar o Rate Service. Ou seja, meu Widget continua útil durante incidentes.</li></ul><h3>Diagrama de alto nível</h3><p>Abaixo busquei descrever passo a passo o que cada peça faz e por que, tanto a ingestão quanto a leitura do total das transações nas últimas 24h.</p><h4><strong>INGEST</strong></h4><h4>1) Transfer Simulator: Escreve eventos no Redis (Stream transfers)</h4><ul><li><strong>Endpoint:</strong> POST /simulate?count=100&amp;spread_minutes=60<br>count: Define quantos eventos quero gerar.<br>spread_minutes: É opcional, ele só “espalha” os <em>timestamps</em> aleatoriamente nos últimos N minutos.<br>Ex.: spread_minutes=60 → ts_unix = agora − rand(0..3600s). Sem isso, todos vêm com agora.</li><li><strong>Randomização:</strong> Usei umrandomEvent: pra definir aleatoriamente a origem, o destino e o amout da transação.<br>source_currency podendo ser {EUR, USD, BRL} (aleatório).<br>target_currency podendo ser {EUR, USD, BRL} (se igual à origem, forço o uso do EUR).<br>source_amount ~ 100..999, target_amount ~ 90..999 (aleatórios).<br>event_id base36 único, ts_unix em UTC.</li><li><strong>Escrita:</strong> cada evento vira uma <strong>entrada no Stream</strong> transfers via XADD. Ou seja o Stream é um “log” temporal. O simulator só anexa eventos nele.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/877/1*8CQnh8uqLiEeJYultLWbqw.png" /></figure><h4>2) Money Moved Service: Consome e agrega (Consumer Group)</h4><ul><li><strong>Criação do grupo:</strong> XGROUP CREATE transfers mm &quot;$&quot; MKSTREAM<br>O &quot;$&quot; diz: “comece a partir de agora” para que eventos criados anteriormente não sejam lidos.</li><li><strong>Leitura:</strong> XREADGROUP com Streams: [ &quot;transfers&quot;, &quot;&gt;&quot; ]<br>O &quot;&gt;&quot; significa “me entregue eventos novos, ainda não entregues a ninguém do grupo”.Count: 100, Block: 2s: lê em lotes e espera até 2s por novas mensagens.</li><li><strong>Processamento: </strong>No handle busco registrar eventos duplicados no cache de Dedup (mm:dedup:{event_id}) e fazer um bucket das transações por minuto mantendo no cache mm:minute:EUR:{yyyyMMddHHmm} {amount_em_EUR}, por exemplo, mm:minute:EUR:202508292254 soma todos os eventos que têm ts_unix entre 22:54:00 e 22:54:59 UTC.<br>Além disso mantenho um índice temporal em mm:minutes:EUR (score=epoch_minute, member=yyyyMMddHHmm)que vai apoiar o API Service a pegar os membros existentes nas últimas 24h e totalizá-los via pipeline GET.<br>Faço um ACK se deu tudo certo, caso contrário aquela mensagem fica pendente para reprocessamento.</li></ul><h4>LEITURA</h4><h4>1) API Service: Soma a janela de 24h e converte se for preciso</h4><ul><li><strong>Janela móvel:</strong> Calculo os minutos entre &quot;<strong>agora−1439&quot;</strong> até &quot;<strong>agora&quot;</strong>. Isso me ajuda a definir o range que vou usar para listar os membros dos minutos existentes e assim somar seus valores.</li><li><strong>Pipeline GET:</strong> Monto um pipeline de GET mm:minute:EUR:{m} para todos os membros e totalizo os valores.</li><li><strong>Conversão na leitura (FX Foreign Exchange): <em>Lembre-se que adotei como base o EUR.</em><br></strong>Se currency == EUR (base), já está pronto.<br>Se currency != EUR, chamo rates.Rate(EUR, currency): E nesse ponto pude brincar um pouco com o circuit breaker. Se estiver fechado e FX responder 200, retorna taxa live, cacheio por 5 min e converto. Se der erro (HTTP ou breaker abriu), tento no cache (getCached).</li></ul><pre>type cachedRate struct {<br>    rate float64<br>    at   time.Time<br>    ttl  time.Duration<br>}</pre><ul><li>Caso exista<strong> </strong>converto com a taxa atual do cache (sem erro). Mas se não houver cache, não converto e respondo em EUR. Adicionei ao header oX-Rate-Fallback: true. pra nos mostrar quando isso ocorrer. Você pode tentar derrubar o container do Rate Service e vai perceber ou aumentar a taxa de erro que deixei randômico em até 30% de random fail.</li></ul><pre>func mockRate(from, to string) float64 {<br> table := map[string]float64{<br>  &quot;EUR:BRL&quot;: 6.0, &quot;BRL:EUR&quot;: 1.0 / 6.0,<br>  &quot;EUR:USD&quot;: 1.1, &quot;USD:EUR&quot;: 1 / 1.1,<br>  &quot;USD:BRL&quot;: 5.4, &quot;BRL:USD&quot;: 1 / 5.4,<br>  &quot;EUR:EUR&quot;: 1.0, &quot;USD:USD&quot;: 1.0, &quot;BRL:BRL&quot;: 1.0,<br> }<br> if v, ok := table[from+&quot;:&quot;+to]; ok {<br>  return v<br> }<br> return 1.0</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/690/1*-T-vApbs3ksfwb9E-JArXg.png" /></figure><h3>Widget</h3><p>Construí um Widget utilizando o <a href="https://lovable.dev/">Lovable</a> (Você consegue construir coisas bem mais complexas e aplicações inteiras com ele tá hehe), só pra ter algo visual e bem estilizado do que seria um totalizar, que é basicamente um html que o Go carrega no handleWidget:</p><pre>func handleWidget(w http.ResponseWriter, r *http.Request) {<br> b, err := publicFS.ReadFile(&quot;public/widget.html&quot;)<br> if err != nil {<br>  http.Error(w, &quot;widget not found&quot;, http.StatusInternalServerError)<br>  return<br> }<br> w.Header().Set(&quot;Content-Type&quot;, &quot;text/html; charset=utf-8&quot;)<br> // HTML em si não precisa de cache forte; quem cacheia é o /total<br> w.Header().Set(&quot;Cache-Control&quot;, &quot;no-store&quot;)<br> _, _ = w.Write(b)<br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jQzCHhzAMseiYvvsO62E2Q.png" /></figure><h3>Bora testar?</h3><p>A aplicação é toda containerizada, então basta executar o docker compose ( docker compose up --build ) e tudo será provisionado, cada serviço possui seu respectivo Dockerfile.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1mFfD92aiGyvLwIfVdnU0w.png" /></figure><h4>1) Simulando transações:</h4><p>Fiz duas chamada para o simulador, ambas originaram de BRL para EUR, onde na primeira, na chave <em>mm:minute:EUR:202508311820</em> totalizou 907 EUR.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3yCoTGWqNuIb3znHmYAqJw.png" /></figure><p>Dado que no random a transação foi para EUR, o total também é 907 EUR com taxa igual a 1.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*s7CGPkH8oTqI6AX3jvWuBA.png" /></figure><p>Com a segunda simulação totalizando 591 EUR de target_amount, ou seja, na chave <em>mm:minute:EUR:202508311827 </em>o valor total de transações foi de 591 EUR.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*W3GZngZqhKerSJr7ZJ2aVA.png" /></figure><p>O total nas últimas 24h para o currency EUR passa a ser de 1498 (907 + 591) EUR. Como a BASE também é EUR o total_base_24h também é 1498 EUR.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*z9SUaYtWaHvorYEtlDO_Tg.png" /></figure><p>Fazendo mais uma simulação, agora totalizado transações de USD para EUR temos um target_amount de 170.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*P8I1gXSVN51wMNdmGGgViQ.png" /></figure><p>Agregando ao nosso total para o currency EUR, agora sendo de 1668 EUR</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*waI8FkzK4Xt0qoz5s-rkkw.png" /></figure><p>No Redis Streams temos 3 buckets de transações, todos consumidos por apenas 1 consumidor (dado que não escalamos) e nenhum evento pendente.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DFuusK8QICnsrNxfNYSo1w.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lP7hGsMiMPIfhrWj1-3HIw.png" /></figure><p>O Widget mostra exatamente o total amount das últimas 24h para o currency EUR.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tUkaRXe1YBvQtpZNpV-ltA.png" /></figure><p>Uma observação, como as taxas de Rate estão mockadas não busquei utilizar os mesmos valores na previsão 24h do widget. Estão aí apenas como exemplo, mas perceba que se eu mudar o currency outro, por exemplo, um visitante do Brasil, teremos BRL e total nas últimas 24h em BRL e com base EUR é 10.008 BRL.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4oyqeP3kOZAYmc9ZY1sElg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IWSkEmhEo0ElwZgnBiSNYg.png" /></figure><p>E como posso testar o circuit breaker e simular o Rate Service com indisponibilidade?</p><p>Todo request ao totalizador me retorna no Header o X-Rate-Source, que pode ser live, cache ou none, que são breaker fechado, breaker aberto pegando do cache e fallback sem cache, respectivamente.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Afy8Wu7FU96e13RrhLdhZA.png" /></figure><p>Perceba que ao esquentar o cache com mais simulações de transações e com o Rate Service interrompido temos a seguinte situação:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/910/1*gT9xcf3mOSdYCm99YSvUOQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Q_rMfqjhVVuhTHq4pmK8sQ.png" /></figure><p>O totalizador tenta considerar o último rate mantido no cache, não conseguiu, então adiciono X-Rate-Fallback=true e X-Rate-Source=none no Header.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5kGIY27tjSTka4A5NnCdWw.png" /></figure><p>Como não houve cache, não converti e respondi em EUR para uma visita com currency BRL.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vunILWV8sYiKJR2snaxdRw.png" /></figure><p>Mas havendo cache o retorno passa a ser o mesmo.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*B_w8yurB73xkXeUdNFwfAg.png" /></figure><h3>Conclusão</h3><p>Saiu desse artigo basicamente de um enunciado de “vitrine de confiança” com uma pipeline event-driven enxuta que agrega volume quase<strong> </strong>real-time em moeda base (EUR), converte na leitura para a moeda do visitante e degrada com elegância quando o FX falha (circuit breaker + cache, sinalizado pelos headers X-Rate-Source/X-Rate-Fallback).<br>O desenho separa bem os domínios, mantém latência baixa com Redis (buckets por minuto + ZSET), e demonstra conceitos que escalam: idempotência, janelas deslizantes, e resiliência a dependências externas. O widget estilizado fecha bem a prova de conceito no topo de funil.</p><p>E você? O que você faria diferente? Qual seria sua abordagem para um prova de conceito como essa? Tem ideia para um proximo passo? Bora contribuir no conhecimento junto :)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b49431375d03" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Chargeback: Construindo uma Arquitetura Event-Driven Resiliente com Go, RabbitMQ, MinIO e FTP]]></title>
            <link>https://medium.com/@andersonmarques.ci/chargeback-construindo-uma-arquitetura-event-driven-resiliente-com-go-rabbitmq-minio-e-ftp-7d10b430abcc?source=rss-b76040a1bdfa------2</link>
            <guid isPermaLink="false">https://medium.com/p/7d10b430abcc</guid>
            <dc:creator><![CDATA[Anderson Marques]]></dc:creator>
            <pubDate>Sat, 10 May 2025 01:23:24 GMT</pubDate>
            <atom:updated>2025-05-10T01:23:24.335Z</atom:updated>
            <content:encoded><![CDATA[<h3><strong>Bora entender o desafio?</strong></h3><p>Você com certeza já se deparou com esse desafio por aí, construir uma solução arquitetural capaz de identificar unicamente cada chargeback, armazená-los em arquivos e os enviar para um rede de pagamentos, por exemplo a Mastercard, limitando esse envio a uma quantidade por dia.</p><p>Acredito que você vai ficar &quot;roxo&quot; de vontade de saber o que motivou esse artigo, mas antes vamos pensar um pouco mais no desafio…</p><p>Chargeback ou o famigerado &quot;estorno&quot; é tipo quando a gente vai lá no nosso app do nosso banco favorito (alguns nem são bancos, segundo o BACEN rs) e abre uma contestação de compra pedindo o reembolso do valor. Essa instituição emissora precisa repassar essas contestações para a rede de pagamentos, no nosso exemplo será a Mastercard, e isso pode ocorrer em envios volumosos de arquivos.</p><p>Processar chargebacks de maneira eficiente e resiliente é uma necessidade comum em ecossistemas financeiros, então busquei criar uma arquitetura <strong>event-driven</strong> para simular o fluxo completo de abertura e processamento de chargebacks, do recebimento inicial até o envio de arquivos NDJSON para um servidor FTP, simulando uma integração com a Mastercard.</p><h3>Arquitetura: Visão Geral</h3><p>O projeto combina diversas tecnologias robustas:</p><ul><li><strong>Go (Golang)</strong>: para máxima performance e fácil paralelismo.</li><li><strong>RabbitMQ</strong>: mensageria confiável e desacoplamento entre serviços.</li><li><strong>MinIO</strong>: simulação local de S3 para armazenamento de arquivos.</li><li><strong>Postgres + Cassandra</strong>: bancos especializados para cada etapa.</li><li><strong>FTP</strong>: para entrega dos arquivos em batch.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AHIuZLt6Irahz9dFpXu8QQ.png" /></figure><p>Alguns podem achar que não, mas essa abordagem é totalmente <strong>incremental </strong>resolvendo o essencial e com limitações, mas, claro, como todo system design há trade-off e diversas outras formas de se abordar um problema, lembre-se que <em>&quot;não existe solução bala de prata&quot;.</em></p><p><strong>Arquitetura não é só sobre técnica, é sobre comunicação.</strong> Começar pelo “simples” é tão importante quanto ter a visão completa, então não estranhe a modelo CQRS simples adotado, essa abordagem é amplamente utilizada (<a href="https://bit.ly/3Z2OR5S">https://bit.ly/3Z2OR5S</a>)<strong>. </strong>Sem falar que estou totalmente aberto a discutirmos outras abordagens, você pode naturalmente entender que com um único serviço, salvando os chargebacks num banco de dados relacional, disponibilizando os arquivos no próprio servidor para o batch on-premises baixar e enviar para a Mastercard seja suficiente, e com certeza vai funcionar muito bem também.</p><p><strong>Dado isso, vamos entender um pouco cada componente proposto:</strong></p><ul><li><strong>Chargeback API:</strong> Recebe requisições HTTP, verificar existência de chargebacks já aberto e publica eventos no RabbitMQ (<em>chargeback-opened</em>) para criação caso não exista.</li><li><strong>Chargeback Processor:</strong> Consome eventos de <em>chargeback-opened</em> para persistir o chargeback e adicioná-lo aos arquivos NDJSON, fiz isso em lotes que podem ser configurados por quantidade de chargeback ou por tempo de execução. A cada arquivo pronto um evento é gerado para o <em>chargeback-batch.</em></li><li><strong>MinIO:</strong> Armazena os NDJSON simulando o S3.</li><li><strong>Chargeback Batch:</strong> Agenda e controla o envio dos arquivos NDJSON para Mastercard.</li><li><strong>Mastercard:</strong> Vou usar um servidor FTP para simular a Mastercard recebendo os arquivos.</li><li><strong>Cassandra:</strong> Armazenei o chargeback, bem como seu status, arquivo em que foi enviado para Mastercard, etc. A ideia original seria usar o DynamoDB como KVS para termos mais escalabilidade, desempenho e simplicidade, o que certamente usaria nesse cenário em ambiente de produção pois queremos acessos rápidos aos chargebacks, contudo o Cassandra vai atender super bem nosso design por oferecer esses recursos adicionais ao de um simples KVS.</li><li><strong>Postgres:</strong> Tem o objetivo de manter o controle de envio dos arquivos, ou seja, status de envio, retry, url do arquivo, etc.</li></ul><h3>Implementação Técnica</h3><h4>Microserviços ou Módulos?</h4><p>Antes de mergulhar no código, é importante responder a uma pergunta comum: <strong>os componentes API, Processor e Batch </strong>são microserviços ou apenas módulos?</p><p>A resposta aqui é clara: <strong>eles são microserviços</strong>. Cada serviço tem seu próprio contexto de negócio e responsabilidade bem definida:</p><ul><li>A API lida com entrada HTTP.</li><li>O Processor faz flush para NDJSON e escreve no S3/MinIO.</li><li>O Batch trata o envio de arquivos para a Mastercard.</li></ul><p>Cada serviço é <strong>implantável separadamente</strong>, ou seja, você pode:</p><ul><li>Escalar a API independentemente do Processor;</li><li>Fazer deploy de novas versões do Batch sem afetar os outros serviços.</li><li>Mesmo que estejam no mesmo repositório <strong>monorepo-style</strong>, arquiteturalmente eles seguem o princípio de <strong>autonomia</strong>, típico de microserviços.</li></ul><p>São 3 microserviços independentes, cada um com build e deploy isolados.</p><p>O projeto está organizado seguindo <strong>Clean Architecture</strong> (ou <strong>Hexagonal Architecture</strong>), o que ajuda a manter <strong>baixo acoplamento</strong> e <strong>alta coesão</strong>. <br><strong><em>Código fonte aqui: </em></strong><a href="https://github.com/andersonmarquesgit/chargeback"><strong><em>https://github.com/andersonmarquesgit/chargeback</em></strong></a></p><pre>chargeback-api/<br>├── cmd/<br>│   └── main.go<br>├── internal/<br>│   ├── application/<br>│   │   └── application.go<br>│   ├── domain/<br>│   │   ├── models/<br>│   │   │   └── chargeback.go<br>│   │   └── repositories/<br>│   │       └── chargeback_repository.go<br>│   ├── infrastructure/<br>│   │   ├── respositories/<br>│   │   │   └── cassandra/<br>│   │   │       └── chargeback_repository.go<br>│   │   ├── rabbitmq/<br>│   │   │   ├── producers/<br>│   │   │   │   └── chargeback-opened-producers.go<br>│   │   │   ├── connection.go<br>│   │   │   └── event.go<br>│   │   ├── logging/<br>│   │   │   └── logging.go<br>│   │   └── middlewares/<br>│   ├── interfaces/<br>│   │   ├── http/<br>│   │   │   ├── handlers/<br>│   │   │   │   └── chargeback_handler.go<br>│   │   │   └── routes/<br>│   │   │       └── routes.go<br>│   │   └── messaging/<br>│   │       └── publisher.go<br>│   ├── presentation/<br>│   ├── usecases/<br>│   └── config/<br>│       └── config.go<br>├── docs/ # Swagger docs<br>├── go.mod<br>├── chargeback-api.dockerfile</pre><p>Os outros serviços seguem a mesma filosofia, com pequenas mudanças como por exemplo consumers e scheduler no batch.</p><p>Todos os serviços usam env vars (com defaults seguros), por exemplo:</p><pre>  Minio: MinioConfig{<br>   Endpoint:   getEnv(&quot;MINIO_ENDPOINT&quot;, &quot;localhost:9000&quot;),<br>   AccessKey:  getEnv(&quot;MINIO_ACCESS_KEY&quot;, &quot;admin&quot;),<br>   SecretKey:  getEnv(&quot;MINIO_SECRET_KEY&quot;, &quot;password&quot;),<br>   UseSSL:     false,<br>   BucketName: getEnv(&quot;MINIO_BUCKET_NAME&quot;, &quot;chargebacks&quot;),<br>  },<br>  FTP: FTPConfig{<br>   Host:     getEnv(&quot;FTP_HOST&quot;, &quot;localhost&quot;),<br>   Port:     getEnvAsInt(&quot;FTP_PORT&quot;, 21),<br>   Username: getEnv(&quot;FTP_USER&quot;, &quot;admin&quot;),<br>   Password: getEnv(&quot;FTP_PASS&quot;, &quot;admin&quot;),<br>  },<br>  Scheduler: SchedulerConfig{<br>   Enabled: getEnvAsBool(&quot;SCHEDULER_ENABLED&quot;, true),<br>   Interval: getEnvAsDurationWithUnit(<br>    &quot;SCHEDULER_INTERVAL_VALUE&quot;,<br>    &quot;SCHEDULER_INTERVAL_UNIT&quot;,<br>    1*time.Minute,<br>   ),<br>   MaxFilesPerDay: getEnvAsInt(&quot;BATCH_MAX_FILES_PER_DAY&quot;, 4),<br>  },</pre><p>Dessa forma é possível fazer controles de flush dos arquivos, ou seja, se queremos controlar por quantidade de chargebacks gravados, por tempo, etc.</p><pre>CHARGEBACK_MAX_RECORDS=2500<br>CHARGEBACK_MAX_DURATION_VALUE=6<br>CHARGEBACK_MAX_DURATION_UNIT=hours</pre><p>Ou mesmo o intervalo de processamento do scheduler e a quantidade de arquivos que enviamos para a Mastercard:</p><pre>SCHEDULER_ENABLED=true<br>SCHEDULER_INTERVAL_VALUE=24<br>SCHEDULER_INTERVAL_UNIT=hours<br>SCHEDULER_MAX_FILES_PER_DAY=4</pre><h4>Chargeback API</h4><p>A Chargeback API é o primeiro ponto de contato da nossa arquitetura. Sua missão é simples e crítica: receber requisições HTTP para abrir um chargeback, verificar se já existe (idempotência), e acionar a mensageria para iniciar o processamento assíncrono.</p><p>Suas responsabilidades são:</p><ul><li>Expor um endpoint HTTP /v1/chargebacks (método POST);</li><li>Verificar se o chargeback já existe (consultando o Cassandra);</li><li>Se não existir: publicar evento chargeback-opened;</li><li><strong>202 Accepted</strong> se for um novo chargeback;</li><li><strong>200 OK</strong> se já existir.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hkwm3aeGH1xEF9OulNuHHQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1Z75kpwG5qy4Mbb2oUKSXQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vl4JSWcZ8p88xUFA14KwBw.png" /></figure><p>Essa abordagem desacopla totalmente a persistência do fluxo de entrada, deixando o Processor cuidar de gravar e preparar os arquivos.</p><h4>Chargeback Processor</h4><p>O Chargeback Processor é parte importante da arquitetura: ele consome os eventos de chargebacks abertos e os grava em arquivos NDJSON, agrupando-os em lotes de maneira resiliente e escalável. É aqui que entramos no processamento assíncrono e geramos os arquivos que mais tarde serão enviados para a Mastercard.</p><p>Suas responsabilidades são:</p><ul><li>Consumir eventos chargeback-opened;</li><li>Persistir o chargeback no Cassandra;</li><li>Gravar o chargeback em arquivos NDJSON (no MinIO);</li><li>Rotacionar arquivos quando um limite de <strong>quantidade de registros</strong> é atingido ou um <strong>timeout de flush</strong> ocorre;</li><li>Publicar evento chargeback-batch ao concluir cada arquivo NDJSON.</li></ul><p>Ao consumir os eventos chargeback-opened o Processor grava o chargeback no Cassandra para garantir consistência e histórico, principalmente usando usando userID e transactionID como chave KVS.</p><p>Outro ponto interessante é o <strong>uso de goroutines</strong> para garantir alta performance. Cada evento consumido da fila (chargeback-opened) é processado de forma <strong>assíncrona</strong>, permitindo que múltiplos chargebacks sejam persistidos e adicionados aos arquivos <strong>em paralelo</strong>, sem bloquear a execução principal.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OzkNwLFPI1KfYQpcigUtxA.png" /></figure><p>Cada chargeback é serializado em formato JSON e gravado no arquivo, onde é mantido aberto até que o número de registros chegue ao MaxRecords (ex.: 2500), ou o MaxDuration expirar (ex.: 1 minuto).</p><p>Quando o arquivo é rotacionado fazemos upload para o <strong>MinIO</strong> (simulando S3) e publicamos o evento chargeback-batch:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wuXOtIgH1U2lYi3eqP3JHw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_SWciN2e5ltAH79jnzrv2Q.png" /></figure><p>Esse design com <strong>goroutines + channels</strong> garante que a aplicação:</p><ul><li>Continue respondendo rapidamente, mesmo sob carga pesada.</li><li>Aproveite ao máximo o modelo <strong>concurrent-safe</strong> do Go para montar os NDJSON sem condições de corrida.</li><li>Seja fácil de escalar ― bastando aumentar o número de workers, tudo ainda gerenciado de forma leve pelo runtime do Go.</li></ul><blockquote><em>Usei goroutines para tratar cada chargeback como uma unidade isolada de trabalho, conseguindo lidar com milhares de requisições de forma fluida e sem sobrecarregar a aplicação.</em></blockquote><pre>go func() {<br>  err = chargebackOpenedEventConsumer.Listen(eventHandlers.ChargebackOpenedEventHandler.HandleChargebackOpenedEvent)<br><br>  logging.Infof(&quot;Listening to chargeback opened consumers: %v&quot;, err)<br><br>  if err != nil {<br>   log.Fatalf(&quot;Error listening to chargeback opened consumers: %v&quot;, err)<br>  }<br> }()</pre><h4>Chargeback Batch</h4><p>O Chargeback Batch é o último elo da cadeia: sua missão é garantir que os arquivos NDJSON criados pelo Processor e disponíveis no MinIO sejam enviados para a Mastercard, simulada aqui por um servidor FTP. Além disso, ele implementa uma estratégia de retry com scheduler para arquivos que falharem no envio e mantem a ordem de execução em FIFO (First In First Out).</p><p>Suas responsabilidades são:</p><ul><li>Agendar e buscar arquivos NDJSON prontos no MinIO;</li><li>Fazer o download local do arquivo;</li><li>Enviar o arquivo via FTP;</li><li>Atualizar status no Postgres:ready failed sent</li><li>Realizar retry automático até 3 vezes (controlado usando o campo <em>retry_count</em>);</li><li>Garantir limite máximo de envio diário (ex.: 4 arquivos/dia).</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9-fmpk7XO4XMKj-daqBEcw.jpeg" /></figure><p>O fluxo do processamento ocorre basicamente com a consulta a tabela <em>batch_files </em>e em seguida segue os seguintes passos:</p><p><strong>Download do MinIO: </strong>O Batch baixa o arquivo NDJSON da URL do MinIO e salva <strong>localmente</strong>, geralmente em /tmp/chargebacks.</p><p><strong>Envio via FTP: </strong>Conexão via stilliard/pure-ftpd e upload para /home/ftpusers/admin.</p><p><strong>Status Update (Postgres): </strong>Se sucesso: sent, atualiza sent_at, se falha failed, incrementa retry_count.</p><p><strong>Lógica de Retry: </strong>Para cada arquivo com status failed, um novo envio é tentado e após 3 falhas, o arquivo não será mais considerado.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g3DjmRfM962X9HbP-p13NQ.png" /></figure><p>No chargeback-batch, a concorrência também é protagonista. O envio dos arquivos NDJSON para o FTP é feito com goroutines dedicadas, garantindo que:</p><ul><li>Os arquivos sejam transferidos <strong>em paralelo</strong>, sem gargalos de IO.</li><li>O controle de status e retries seja <strong>não bloqueante</strong>, mantendo a fila de arquivos fluida.</li><li>O scheduler possa rodar em background de forma leve, verificando e processando lotes sem travar o restante do serviço.</li></ul><h3>Por Que Esse Design?</h3><ul><li><strong>Robustez:</strong> FTP não é confiável, então o design é feito para aguentar falhas e continuar tentando;</li><li><strong>Simplicidade:</strong> O serviço só precisa de Postgres + MinIO + FTP, sem depender diretamente da API/Processor;</li><li><strong>Controle Fino:</strong> Tudo que acontece (download, upload, retry) fica persistido no Postgres para rastreabilidade completa.</li></ul><p>Com isso, temos uma cadeia end-to-end robusta e observável. O Batch, mesmo simples, exerce um papel crítico de garantir entrega e auditabilidade.</p><p>O <strong>Go brilha</strong> nesse cenário com sua facilidade em tratar <strong>concorrência leve e barata</strong>, algo essencial quando estamos lidando com processamento de eventos + IO intenso (como escrita em arquivo e upload FTP).</p><h3>Execução do Projeto</h3><p>Para tornar a execução prática e reproduzível, toda a infraestrutura está <strong>dockerizada</strong> e controlada a partir do diretório project/. A orquestração acontece usando <strong>Docker Compose</strong> e um <strong>Makefile</strong> que automatiza o build dos serviços Go.</p><h4>Estrutura de Diretórios</h4><pre>project/<br>├── db-init/<br>│   ├── cassandra/<br>│   │   └── schema.cql<br>│   └── postgres/<br>│       └── schema.sql<br>├── local-batch-output/     # Arquivos enviados para o FTP (Batch)<br>├── local-output/           # Arquivos gerados pelo Processor<br>├── s3/                     # (Opcional) MinIO extra<br>├── chargeback-test.js      # Script de carga com k6<br>├── docker-compose.yml      # Orquestração completa dos serviços<br>└── Makefile                # Build e comandos utilitários</pre><h4>Makefile: Automatizando Tudo</h4><p>Para simplificar o processo de build e execução, usei o Makefile com 3 comandos principais:</p><h4>- Levantar os Containers:</h4><pre>make up</pre><p><strong>O que faz? </strong>Sobe todos os containers em segundo plano (sem rebuild).</p><h4>- Build + Deploy:</h4><pre>make up_build</pre><p><strong>O que faz? </strong>Para containers existentes e faz o build dos binários Go:</p><ul><li>chargeback-api</li><li>chargeback-processor</li><li>chargeback-batch</li><li>Sobe tudo com docker-compose up --build -d.</li></ul><h4>- Derrubar Containers:</h4><pre>make down</pre><p><strong>O que faz? </strong>Para e remove os containers em execução.</p><h4><strong>Você pode acompanhar o processamento:</strong></h4><ul><li><strong>MinIO:</strong> <a href="http://localhost:9001/"><em>http://localhost:9001</em></a><em><br></em><strong><em>Username:</em></strong><em> </em><em>admin</em><strong><em>Password:</em></strong><em> </em><em>password</em><strong><em>Bucket:</em></strong><em> </em><em>chargebacks</em></li><li><strong>RabbitMQ:</strong> <a href="http://localhost:15672/"><em>http://localhost:15672</em></a><em><br></em><strong><em>Username:</em></strong><em> </em><em>guest</em><strong><em>Password:</em></strong><em> </em><em>guest</em></li><li><strong>FTP (simulado):</strong> <em>FTP rodando na porta 21.</em></li><li><strong>Cassandra</strong> (<strong>Keyspace</strong>: chargebacks): <br><em>Leva cerca de 30s para iniciar o container e construir o schema:<br></em><strong><em>Host:</em></strong><em> </em><em>localhost<br></em><strong><em>Porta:</em></strong><em> </em><em>9042<br></em><strong><em>Username:</em></strong><em> (não configurei autenticação, é a padrão da imagem </em><em>cassandra)<br>Exemplo de URL para conexão (no DBeaver / DataGrip / TablePlus): cassandra://localhost:9042<br></em><strong><em>Observação:</em></strong><em> se a ferramenta exigir </em><strong><em>autenticação</em></strong><em>, a imagem oficial do Cassandra roda sem autenticação por padrão. Se você ativar autenticação, lembre de ajustar a env var no </em><em>docker-compose.<br></em><strong><em>Keyspace:</em></strong><em> </em><em>chargebacks<br></em><strong><em>Tabela principal:</em></strong><em> </em><em>chargebacks_by_user_transaction</em></li><li><strong>Postgres</strong> (<strong>Database</strong>: batch)<br><strong><em>Host:</em></strong><em> </em><em>localhost <br></em><strong><em>Porta:</em></strong><em> </em><em>5432<br></em><strong><em>Table principal:</em></strong><em> </em><em>batch_files<br></em><strong><em>User:</em></strong><em> </em><em>admin<br></em><strong><em>Password:</em></strong><em> </em><em>admin<br>Exemplo de URL de conexão: postgresql://admin:admin@localhost:5432/batch?sslmode=disable</em></li></ul><h3>Testes com k6: Exemplo de Processamento e Teste de Carga</h3><p>Para validar a eficiência e a resiliência da arquitetura desenvolvida, utilizei a ferramenta <a href="https://k6.io/"><strong>k6</strong></a> para simular uma carga alta de criação de chargebacks, em um cenário que reflete o comportamento esperado em produção. A instalação e execução com ele é facinho e o uso do JavaScript ajuda bastante na escrita dos cenários, caso você queira testar algo diferente do que já existe no diretório <em>project</em>.</p><p>O objetivo do teste foi basicamente simular 100 usuários enviando requisições em paralelo, onde cada usuário envia múltiplas requisições, garantindo diversidade dos dados com IDs dinâmicos. Dessa forma foi possível validar a idempotência: o sistema deve aceitar um novo chargeback (HTTP 202) e rejeitar duplicados (HTTP 200).</p><h4>Configuração do Teste</h4><p>O script foi escrito em JavaScript e está localizado no repositório como:</p><pre>project/chargeback-test.js</pre><p>Exemplo do script:</p><pre>import http from &#39;k6/http&#39;;<br>import { check, sleep } from &#39;k6&#39;;<br><br>export default function () {<br>    const url = &#39;http://localhost:8080/v1/chargebacks&#39;;<br>    const payload = JSON.stringify({<br>        user_id: `user_${Math.floor(Math.random() * 1000)}`,<br>        transaction_id: `txn_${Math.floor(Math.random() * 1000000)}`,<br>        reason: `Serviço não prestado na transação txn_${Math.floor(Math.random() * 1000000)}`<br>    });<br><br>    const params = {<br>        headers: { &#39;Content-Type&#39;: &#39;application/json&#39; },<br>    };<br><br>    const res = http.post(url, payload, params);<br><br>    check(res, {<br>        &#39;status is 202 (Created)&#39;: (r) =&gt; r.status === 202,<br>        &#39;status is 200 (Already exists)&#39;: (r) =&gt; r.status === 200,<br>    });<br><br>    sleep(1);<br>}</pre><p><strong>Dica:</strong> usei Math.random() para gerar usuários e transações únicos a cada execução</p><h4>Resultados Obtidos</h4><ul><li><strong>Producer (API):</strong> Testei com o K6 e consegui gerar um volume consistente de requisições (~200 RPS de pico), atingindo ~17k requests por teste. A API sustentou bem, com latências P95 na casa dos 60 ms. Isso mostra que o Cassandra + RabbitMQ conseguiram manter performance sob carga com idempotência funcionando perfeitamente (50% status 202, 50% status 200).</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qt72h4x1V-C8WoDQSb0j_Q.png" /></figure><ul><li><strong>Processor:</strong> O flush ficou configurado para bater em 2.500 registros ou 1 min, entregando um bom equilíbrio entre latência e volume de escrita em lote. Os arquivos NDJSON ficaram bem formatados e organizados.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wuXOtIgH1U2lYi3eqP3JHw.png" /></figure><ul><li><strong>Batch:</strong> O scheduler estava programado para rodar a cada 5 minutos com limite de 4 arquivos diários, o que foi uma ótima escolha para controle. Essa regra impede picos inesperados no Mastercard (FTP) e mantém o fluxo sob controle.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9-fmpk7XO4XMKj-daqBEcw.jpeg" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/371/1*O6Z4-NFajA_2EaIlqRTC0A.png" /></figure><ul><li><strong>RabbitMQ: </strong>O exchange chargeback-opened-exchange manteve um throughput estável (~200 msgs/s durante os testes) e foi corretamente consumido pelo Processor. O exchange chargeback-batch-exchange mostra a comunicação saudável entre Batch e Processor, enviando os arquivos NDJSON para serem processados/exportados.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/680/1*yMPr8WY-cwFni6vKhhAm_A.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YP4fEJ4IXCDF3xKVsS0ffA.png" /></figure><ul><li><strong>MinIO:</strong> Os arquivos foram corretamente salvos no bucket chargebacks, confirmando que o MinIO está bem configurado e funcionando como esperado.</li><li><strong>FTP:</strong> Arquivos NDJSON chegaram no Mastercard (FTP container) como planejado.</li></ul><p>Os gráficos e números mostram uma ótima estabilidade com zero falhas HTTP, latência controlada (P95 ~64ms) e throughput consistente. Performance em ~17k requests em 2 minutos (~143 req/s em média), escalando até ~200 req/s de pico. A API manteve o comportamento idempotente ideal (202 vs 200 responses) o tempo todo.</p><p>Os resultados compravam que a arquitetura escala bem suportando os picos. Acredito que alguns pontos de melhoria futuros seria testarmos cenários com falha (desligar o RabbitMQ/MiniIS para ver a resiliência), implementar limites por usuário, etc.</p><h3>Conclusão</h3><p>Chegamos ao fim dessa jornada de construção de uma arquitetura event-driven robusta, cheia de possibilidades e escolhas técnicas, mas principalmente totalmente aberta a pensarmos formas diferentes de se fazer system design.</p><p>Aqui, trabalhamos num problema super real do mercado financeiro ― o processamento de chargebacks ― e quebramos ele em partes menores, entregando uma solução moderna, escalável e resiliente. E acho que aqui reside minha maior motivação pra essa prova de conceito. Muitas vezes a gente tá diante de um desafio técnico, um problema que precisa ser resolvido ou mesmo numa entrevista de system design, e nem sempre a nossa comunicação ou abordagem atende totalmente a expectativa e nível de conhecimento do outro. O importante no processo será sempre o aprendizado mútuo, contínuo e a experimentação das possibilidades, <em>“não existe solução bala de prata” </em>― arquitetura é sobre fazer trade-offs consciente.</p><h3>E agora?</h3><p>Fica a provocação: que melhorias você faria?</p><ul><li><strong>Adicionaria cache?</strong></li><li><strong>Usaria Kafka ao invés de RabbitMQ?</strong></li><li><strong>Implementaria uma DLQ mais sofisticada?</strong></li><li><strong>Substituiria o FTP por uma API moderna?</strong></li></ul><p>O legal desse projeto é que ele é <strong>incremental</strong> e pode (e deve!) ser melhorado. A minha ideia aqui foi criar uma base sólida, mas flexível, pra você pegar, testar, adaptar e colocar em prática nos seus próprios projetos.</p><h3>Bora debater?</h3><p>Curtiu? Discorda de algo? Bora conversar nos comentários ou me chama no <a href="https://www.linkedin.com/in/anderson-marques-5b1b8b28/">LinkedIn</a>. Nada melhor do que <strong>arquitetar junto</strong> pra evoluir ainda mais. 😄</p><p>Até a próxima! 👋</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7d10b430abcc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Sim, é CQRS mesmo usando o mesmo banco de dados]]></title>
            <link>https://medium.com/@andersonmarques.ci/sim-%C3%A9-cqrs-mesmo-usando-o-mesmo-banco-de-dados-718ada3cb76a?source=rss-b76040a1bdfa------2</link>
            <guid isPermaLink="false">https://medium.com/p/718ada3cb76a</guid>
            <dc:creator><![CDATA[Anderson Marques]]></dc:creator>
            <pubDate>Wed, 30 Apr 2025 21:18:15 GMT</pubDate>
            <atom:updated>2025-04-30T21:18:15.238Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Separar leitura e escrita no código já é um passo poderoso — e muitas vezes suficiente.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LpHTQ207FL7yuCWmOMpWfg.png" /></figure><blockquote>Quando se fala em CQRS, muita gente já imagina filas, eventos, múltiplos bancos de dados e uma arquitetura distribuída complexa. Mas a verdade é que você pode aplicar os princípios de <strong>Command Query Responsibility Segregation</strong> mesmo com uma estrutura simples, usando apenas um banco de dados.</blockquote><h3>A essência do CQRS</h3><p>CQRS é sobre <strong>separar responsabilidades</strong>:</p><ul><li><strong>Comandos (writes)</strong> alteram o estado do sistema.</li><li><strong>Consultas (reads)</strong> apenas recuperam dados.</li></ul><p>Essa separação ajuda a manter o código mais limpo, claro e modular. O importante é que <strong>a lógica de leitura e escrita seja distinta</strong>, mesmo que usem o mesmo repositório físico.</p><h3>Como funciona na prática</h3><p>Imagine dois serviços ou camadas na sua aplicação:</p><ul><li>Um responsável por consultar dados e entregar respostas otimizadas (DTOs, projections).</li><li>Outro que recebe comandos, aplica validações de negócio e persiste mudanças.</li></ul><p>Ambos interagem com o mesmo banco, mas fazem isso com responsabilidades e estruturas diferentes.</p><p>Essa separação pode parecer sutil, mas já traz <strong>clareza arquitetural</strong> e <strong>prepara o terreno para evoluções futuras</strong>.</p><h3>Benefícios dessa abordagem</h3><ul><li><strong>Mais simples de adotar</strong><br>Não exige mudanças na infraestrutura ou múltiplos bancos.</li><li><strong>Evita inconsistência</strong><br>Leitura e escrita compartilham os mesmos dados, sem risco de divergência.</li><li><strong>Ideal para MVPs e projetos pequenos</strong><br>Você colhe os benefícios do CQRS sem complicar demais o início da jornada.</li></ul><h3>Mas… existem limitações</h3><ul><li><strong>Escalabilidade restrita</strong><br>Leitura e escrita compartilham recursos. Em alto volume, isso pode virar gargalo.</li><li><strong>Performance mais difícil de otimizar</strong><br>O mesmo banco precisa servir tanto queries otimizadas quanto transações complexas.</li><li><strong>Risco de contenção</strong><br>Operações simultâneas em massa podem afetar a performance global.</li></ul><h3>Quando essa abordagem é suficiente?</h3><ul><li>Quando seu projeto está em fase inicial.</li><li>Quando o tráfego ainda é moderado.</li><li>Quando seu time quer testar os benefícios do CQRS sem reestruturar tudo.</li></ul><h3>Conclusão</h3><p>Você não precisa começar com uma arquitetura distribuída para aplicar CQRS. A separação lógica entre leitura e escrita — mesmo com um único banco — <strong>já é CQRS</strong> e pode te levar longe com menos esforço.</p><p>No próximo artigo, vamos explorar <strong>como evoluir essa estrutura</strong> para um modelo com <strong>separação física</strong>, ganhando escalabilidade, performance e autonomia entre leitura e escrita.</p><p>👉 <em>Fique de olho no segundo artigo da série!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=718ada3cb76a" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>