WealthFolio Brasil

Current state#

WealthFolio Brasil is an independent adaptation of the open-source Wealthfolio project ↗ (opens in a new tab). This case study focuses specifically on the integration, reliability, automation and infrastructure work developed on top of the upstream codebase.

Wealthfolio already provided a strong open-source foundation. The challenge was not rebuilding portfolio tracking. It was adapting that foundation for a real Brazilian financial workflow, where external institution data, persistent state and interrupted operations have to remain understandable.

The public fork is available at github.com/Juanfg8/wealthfolio-brasil ↗ (opens in a new tab). The case intentionally keeps the upstream product and the Brazilian engineering layer separate.

Upstream foundation vs our work#

The upstream Wealthfolio project provides the portfolio-tracking foundation: accounts, holdings, activities, performance views, local-first storage, manual workflows and CSV import. It is licensed under AGPL-3.0. The fork retains that credit and does not claim authorship of the original product.

The engineering layer in WealthFolio Brasil extends that foundation around Brazilian operation: a Pluggy / Open Finance adapter, explicit account linking, deterministic import behavior, investment-state protection, operational diagnostics, persistence safeguards, lifecycle handling and release gates. The evidence panel above is the short version; the source and commit trail is recorded in the internal evidence matrix.

The challenge#

Financial software fails in ordinary-looking places: an import runs twice, an external page omits a pagination field, an investment response is incomplete, a state file is replaced without a durable flush, or a process receives SIGTERM while a request is still writing.

The Brazilian adaptation therefore treats synchronization as an operational workflow, not as a single API call. Accounts begin in review, links are explicit, imported transactions carry source identity, and suspicious or incomplete data is allowed to stop a snapshot instead of silently rewriting the portfolio.

Open Finance#

Pluggy is read-only at the provider boundary. The adapter discovers institutions, accounts, transactions, bills, investments and reserved balances, then passes selected data through Wealthfolio’s existing account, activity and snapshot services.

The important boundary is explicit linking: a discovered account is not automatically merged into an existing Wealthfolio account. Transaction imports require a linked transaction-mode account, and investment snapshots require a linked holdings-mode account. That keeps the external relationship reviewable and avoids turning name similarity into authorization.

Data integrity#

The sync path uses a deterministic idempotency key, pluggy:<accountId>:<txId>, so re-running the same provider data does not create duplicate activity rows. Sync and link endpoints serialize read-modify-write access to pluggy_state.json; this protects links, cost basis and remembered flow IDs from clobbering one another.

The adapter also guards against common failure shapes: missing pagination metadata cannot silently truncate a full page, failed Pluggy items preserve their previous investment state, and a response that would wipe investments without evidence is blocked from replacing the stored snapshot. These are narrow correctness decisions, not a claim that the provider is infallible.

Reliability engineering#

The fork makes operational state inspectable. The read-only diagnostics summary reports build identity, Pluggy scheduler and item state, database reachability and WAL mode, the latest backup, and balance-reconciliation flags. It is protected by the same session-auth layer as the other API routes and is covered by a route-shape test.

The Pluggy state replacement path fsyncs the temporary file before the atomic rename and fsyncs the containing directory after the rename. SQLite runs with WAL-backed persistence in the server path, and the repository includes database snapshot, restore and migration checks. The wording stays deliberately narrow: these are implemented safeguards and checks, not a guarantee against every storage or infrastructure failure.

Shutdown is also part of reliability. SIGTERM and Ctrl+C are wired into Axum’s graceful shutdown so new accepts stop and in-flight HTTP requests can finish. The source comments document the remaining boundary: the SQLite writer actor is not yet drained by the application lifecycle, so a follow-up remains visible rather than being described as complete.

Performance and build/cache work#

The repository contains performance-correctness changes around cost basis, cash-flow treatment and return calculations, plus Cargo and Docker BuildKit cache mounts for local or persistent builders. The CI comments are explicit that a fresh GitHub Actions runner does not automatically retain named cache mounts.

No wall-clock benchmark is published here. There is no reproducible, user-facing timing result in the inspected evidence that would justify one.

Release discipline#

The public workflow runs formatting checks, Clippy with warnings denied, workspace tests, an AI package test pass and a release-mode server check. A separate financial regression gate runs before the GHCR image publication job. Review commits also show adversarial defect tests, release-candidate cleanup and regression fixes.

That sequence is the capability being demonstrated: changes move through tests and validation before they become a published image. The case does not claim that every future release is risk-free; it shows the gates that exist in the inspected fork.

Why it matters#

This is the work of entering an established codebase, preserving what already works, extending only where the Brazilian workflow requires it, and making the failure boundaries legible. The result is more credible when the original foundation, the added engineering and the remaining follow-ups are all visible.

Open-source attribution#

Wealthfolio is the original open-source project and remains credited to its original authors and contributors. WealthFolio Brasil is an independent adaptation/fork; this case covers the Pluggy integration, synchronization, reliability, automation and infrastructure work developed on top of the upstream codebase.

The upstream source is available at github.com/wealthfolio/wealthfolio ↗ (opens in a new tab), and the adaptation is available at github.com/Juanfg8/wealthfolio-brasil ↗ (opens in a new tab). The inspected repository includes the GNU Affero General Public License v3.0 and the upstream trademark guidance. Wealthfolio is a trademark of Teymz Inc.; this page does not imply sponsorship, affiliation or endorsement.