WealthFolio Brasil

Estado atual#

WealthFolio Brasil é uma adaptação independente do projeto open-source Wealthfolio ↗ (abre em uma nova aba). Este caso cobre especificamente o trabalho de integração, confiabilidade, automação e infraestrutura desenvolvido sobre o código upstream.

Wealthfolio já oferecia uma base open-source forte. O desafio não era reconstruir o acompanhamento de carteiras. Era adaptar essa base para um fluxo financeiro brasileiro real, em que dados externos de instituições, estado persistente e operações interrompidas precisam continuar compreensíveis.

O fork público está em github.com/Juanfg8/wealthfolio-brasil ↗ (abre em uma nova aba). O caso mantém intencionalmente o produto upstream e a camada de engenharia brasileira separados.

Fundação upstream vs nosso trabalho#

O projeto Wealthfolio upstream fornece a fundação de acompanhamento de carteiras: contas, posições, atividades, visões de performance, armazenamento local, fluxos manuais e importação por CSV. Ele é licenciado sob AGPL-3.0. O fork preserva esse crédito e não reivindica autoria do produto original.

A camada de engenharia do WealthFolio Brasil estende essa base para a operação brasileira: adaptador Pluggy / Open Finance, vínculos explícitos de contas, comportamento determinístico de importação, proteção do estado de investimentos, diagnósticos operacionais, salvaguardas de persistência, ciclo de vida e gates de release. O painel acima é o resumo; o rastro de código e commits está registrado na matriz interna de evidências.

O desafio#

Software financeiro falha em lugares aparentemente comuns: uma importação roda duas vezes, uma página externa omite um campo de paginação, uma resposta de investimento fica incompleta, um arquivo de estado é substituído sem flush durável ou um processo recebe SIGTERM enquanto uma requisição ainda grava.

A adaptação brasileira trata a sincronização como fluxo operacional, não como uma chamada isolada de API. Contas descobertas começam em revisão, vínculos são explícitos, transações importadas carregam identidade de origem e dados suspeitos ou incompletos podem impedir um snapshot em vez de reescrever a carteira silenciosamente.

Open Finance#

Pluggy é somente leitura no limite do provedor. O adaptador descobre instituições, contas, transações, faturas, investimentos e saldos reservados, então passa os dados selecionados pelos serviços existentes de contas, atividades e snapshots do Wealthfolio.

O limite importante é o vínculo explícito: uma conta descoberta não é mesclada automaticamente com uma conta existente do Wealthfolio. Importações de transações exigem uma conta vinculada em modo de transações, e snapshots de investimentos exigem uma conta vinculada em modo de posições. Assim, a relação externa continua revisável e similaridade de nome não vira autorização.

Integridade dos dados#

O fluxo usa a chave determinística pluggy:<accountId>:<txId>, então repetir os mesmos dados do provedor não cria linhas de atividade duplicadas. Os endpoints de sync e vínculo serializam o acesso de leitura-modificação-escrita a pluggy_state.json; isso protege vínculos, custo-base e IDs de fluxos contra sobrescritas concorrentes.

O adaptador também protege contra formas comuns de falha: metadados de paginação ausentes não truncam silenciosamente uma página cheia, itens Pluggy que falharam preservam o estado anterior de investimentos e uma resposta que limparia investimentos sem evidência é impedida de substituir o snapshot armazenado. São decisões estreitas de correção, não uma afirmação de que o provedor é infalível.

Engenharia de confiabilidade#

O fork torna o estado operacional inspecionável. O resumo diagnóstico somente leitura informa identidade do build, estado do scheduler e dos itens Pluggy, alcance e modo WAL do banco, o backup mais recente e sinais de reconciliação de saldo. Ele é protegido pela mesma camada de autenticação de sessão das outras rotas de API e possui teste de formato de resposta.

O caminho de substituição do estado Pluggy faz fsync do arquivo temporário antes do rename atômico e do diretório depois do rename. O SQLite usa persistência em WAL no caminho do servidor, e o repositório inclui verificações de snapshot, restore e migração. A redação permanece estreita: são salvaguardas e verificações implementadas, não uma garantia contra qualquer falha de armazenamento ou infraestrutura.

O shutdown também faz parte da confiabilidade. SIGTERM e Ctrl+C estão ligados ao graceful shutdown do Axum, interrompendo novos accepts e permitindo que requisições HTTP em andamento terminem. Os comentários do código deixam claro o limite restante: o writer actor do SQLite ainda não é drenado pelo ciclo de vida da aplicação, então esse follow-up continua visível.

Performance e build/cache#

O repositório contém mudanças de correção de performance em custo-base, tratamento de fluxos de caixa e cálculos de retorno, além de mounts de cache do Cargo e do Docker BuildKit para builders locais ou persistentes. Os comentários do CI deixam explícito que um runner novo do GitHub Actions não retém automaticamente esses mounts nomeados.

Nenhum benchmark de tempo é publicado aqui. A evidência inspecionada não traz um resultado reproduzível e voltado ao usuário que justifique um número.

Disciplina de release#

O workflow público executa verificações de formatação, Clippy com warnings proibidos, testes do workspace, uma passagem de testes do pacote de IA e um check do servidor em modo release. Um gate separado de regressão financeira roda antes do job de publicação da imagem no GHCR. Commits de revisão também mostram testes adversariais, limpeza de release candidate e correções de regressão.

Essa sequência é a capacidade demonstrada: mudanças passam por testes e validação antes de virarem uma imagem publicada. O caso não afirma que todo release futuro é livre de risco; mostra os gates existentes no fork inspecionado.

Por que importa#

Este é o trabalho de entrar em um código existente, preservar o que já funciona, estender somente onde o fluxo brasileiro exige e tornar visíveis os limites de falha. O resultado fica mais crível quando a fundação original, a engenharia adicionada e os follow-ups restantes aparecem juntos.

Atribuição open-source#

Wealthfolio é o projeto open-source original e continua creditado a seus autores e contribuidores originais. WealthFolio Brasil é uma adaptação/fork independente; este caso cobre o trabalho de integração Pluggy, sincronização, confiabilidade, automação e infraestrutura desenvolvido sobre o código upstream.

O código upstream está em github.com/wealthfolio/wealthfolio ↗ (abre em uma nova aba), e a adaptação está em github.com/Juanfg8/wealthfolio-brasil ↗ (abre em uma nova aba). O repositório inspecionado inclui a GNU Affero General Public License v3.0 e a orientação de marcas upstream. Wealthfolio é uma marca registrada da Teymz Inc.; esta página não implica patrocínio, afiliação ou endosso.