Skip to content
Felipe Sousa

FelpsXP Finance

A multi-tenant household finance product, live and in daily use: accounts, cards, instalments, loans, goals and expenses split between the people who live there, built for iOS, Android and web from one codebase.

BackendAppSecIAMFrontend

Problem

Personal finance tools are almost always designed for one person. A household is a different problem: several people, shared accounts and cards, and commitments that belong to one member but affect everyone’s month. And the requirement that drives everything is not a feature: two households can never see each other’s money.

Solution

A multi-tenant product where each household is a fully isolated tenant, with the isolation enforced by the database rather than by convention in application code. One codebase renders to iOS, Android and web; business rules live in the API and in a shared package of pure functions used by both sides, so a preview in the interface and the value actually written are computed by the same function.

Screens

Captures of the production app, with a fictitious household created only for this demo: names, accounts and amounts are invented, and no real data appears here.

  • The app dashboard with the total balance, balances per account and per person, the projected end-of-month balance and the card statement to pay.The app dashboard with the total balance, balances per account and per person, the projected end-of-month balance and the card statement to pay.
    Dashboard: balances derived from the ledger, per account and per person, and the projected month-end balance.
  • The transaction list grouped by day, with the category, account, payment method and status of each entry.The transaction list grouped by day, with the category, account, payment method and status of each entry.
    Transactions grouped by day, each with its account, payment method and status.
  • A checking account with its linked credit card, the available limit and the upcoming statements, each with options to pay or renegotiate.A checking account with its linked credit card, the available limit and the upcoming statements, each with options to pay or renegotiate.
    Accounts and cards: available limit and the future statements created by an instalment purchase.
  • The bills-to-pay screen with the card statements month by month, from December through September of the following year.The bills-to-pay screen with the card statements month by month, from December through September of the following year.
    To pay: a R$ 3,600 purchase in 10 instalments, spread statement by statement.
  • The household monthly goal with an income target, an expense limit and savings targets, and progress for the month.The household monthly goal with an income target, an expense limit and savings targets, and progress for the month.
    Monthly goals for the whole household or per person, with progress so far.

Architecture highlights

  • Tenant isolation via row-level security from the first migration, with explicit table grants alongside it: the lesson of a real production failure
  • Platform administration kept entirely outside the tenant model, so the isolation rule has no exceptions to get wrong
  • Authentication behind its own internal interface, so the provider can be replaced without touching screens or rules
  • Every value is an integer number of cents, never a floating-point number
  • Three distinct dates per commitment (the month it belongs to, the date it is owed, the date the money actually moved), because collapsing them into one field makes reporting, reminders and cash flow mutually incompatible
  • Balances derived from the ledger on every read, never kept as a running total that could drift from the rows it claims to summarise
  • Instalments as siblings under a shared group id, with no privileged first row: a shape that later solved an unrelated problem unchanged, one bill paid by several household members, with no new table
  • Recurrence made idempotent by a progress pointer, which can tell "not generated yet" from "generated and deliberately discarded"
  • Errors and logs that carry no financial or personal data, by logging which operation failed rather than maintaining a redaction list
  • A pure, dependency-free financial maths package covered by automated tests: instalment splitting, card cycles, recurrence, discounts and interest, and reading a bank slip’s own digits offline

Challenges

  • A real production failure where correct isolation policies were never reached, because the underlying table-permission check denied the request first: a correct policy behind a missing grant looks exactly like a broken product
  • Modelling money that arrives without being earned (a loan’s principal, a correction to an unlogged balance) so the balance is right without contaminating what derives from income
  • Leaving a household free to rename its own categories while the system still needs to find the ones it relies on
  • Categorising a typed description without sending the household’s spending outside the system or depending on a network

Responsibilities

  • Design the multi-tenant model and the isolation boundary
  • Implement the API and business rules, including calendar and rounding arithmetic
  • Build the single client that serves iOS, Android and web
  • Operate the product in production, with transactional e-mail in the real account flow

Outcomes

  • Live and in daily use by the family, not in a demo environment; the store launch (Android and iOS) is planned for 2027
  • Designed to consume the ecosystem platform only through its API, with no access to its source or database; that integration is not wired up yet
  • The tested financial maths package is already separated so it can be published on its own

Learnings

  • A correct isolation policy is useless if the permission underneath it denies first. The failure mode does not announce itself as a permissions problem: it presents as the product simply not working, and it took a production failure to learn to look one layer down
  • Deriving is cheaper than storing: a balance computed on every read can never drift from the ledger it claims to summarise, and recomputing costs far less than reconciling later
  • A good shape pays for itself twice: instalments as siblings under a group, with no privileged row, solved an unrelated problem unchanged (one bill paid by several people), with no new table and no downstream reader needing to know the group exists
  • Idempotency has to come from a pointer, not from "does a record already exist?": that question cannot tell "not generated yet" from "generated and deliberately discarded"
  • Not every categorisation problem wants a language model: scoring against the household’s own history worked better here, keeps spending inside the system, and works with no network

Stack

TypeScriptExpo RoutertRPCNode.jsPostgreSQLRow-Level SecurityVitest