Pular para o conteúdo
Felipe Sousa

FelpsXP Finance

Organizador financeiro multi-inquilino para uma casa, no ar e em uso diário: contas, cartões, parcelas, empréstimos, metas e despesas divididas entre os moradores, de um mesmo código para iOS, Android e web.

BackendAppSecIAMFrontend

Problema

Ferramenta de finanças pessoais é quase sempre desenhada para uma pessoa. Uma casa é outra coisa: várias pessoas, contas e cartões compartilhados, e compromissos que pertencem a um morador mas afetam o mês de todo mundo. E o requisito que manda em tudo não é funcional: duas casas jamais podem enxergar o dinheiro uma da outra.

Solução

Um produto multi-inquilino onde cada casa é um inquilino isolado, com o isolamento garantido pelo banco de dados em vez de por convenção no código. Um único código-fonte gera iOS, Android e web; as regras de negócio vivem na API e num pacote de funções puras compartilhado entre servidor e cliente, para que a prévia na tela e o valor gravado sejam calculados pela mesma função.

Telas

Capturas do app em produção, com uma casa fictícia criada só para demonstração: nomes, contas e valores são inventados, e nenhum dado real aparece aqui.

  • Dashboard do app com saldo total, saldo por conta e por pessoa, saldo projetado para o fim do mês e a fatura do cartão a pagar.Dashboard do app com saldo total, saldo por conta e por pessoa, saldo projetado para o fim do mês e a fatura do cartão a pagar.
    Dashboard: saldos derivados do extrato, por conta e por pessoa, e o saldo projetado do mês.
  • Lista de transações agrupada por dia, com categoria, conta, forma de pagamento e situação de cada lançamento.Lista de transações agrupada por dia, com categoria, conta, forma de pagamento e situação de cada lançamento.
    Transações agrupadas por dia, cada uma com conta, forma de pagamento e situação.
  • Conta corrente com o cartão de crédito vinculado, o limite disponível e as próximas faturas, cada uma com a opção de pagar ou renegociar.Conta corrente com o cartão de crédito vinculado, o limite disponível e as próximas faturas, cada uma com a opção de pagar ou renegociar.
    Contas e cartões: limite disponível e as faturas futuras geradas pela compra parcelada.
  • Tela de contas a pagar com as faturas do cartão mês a mês, de dezembro até setembro do ano seguinte.Tela de contas a pagar com as faturas do cartão mês a mês, de dezembro até setembro do ano seguinte.
    A pagar: uma compra de R$ 3.600 em 10 parcelas, distribuída fatura a fatura.
  • Meta mensal da casa com alvo de receita, limite de despesa e metas de economia, e o progresso do mês.Meta mensal da casa com alvo de receita, limite de despesa e metas de economia, e o progresso do mês.
    Metas do mês para a casa inteira ou por pessoa, com o progresso até agora.

Destaques de arquitetura

  • Isolamento por inquilino com row-level security desde a primeira migração, mais grants explícitos de tabela ao lado: a lição de uma falha real em produção
  • Administração da plataforma inteiramente fora do modelo de inquilino, para que a regra de isolamento não tenha exceção pra dar errado
  • Autenticação atrás de uma interface interna própria, para o provedor poder ser trocado sem tocar em tela nem em regra
  • Todo valor é inteiro em centavos, nunca ponto flutuante
  • Três datas distintas por compromisso (mês de competência, data devida e data em que o dinheiro se moveu), porque juntar as três num campo só torna relatório, lembrete e fluxo de caixa mutuamente incompatíveis
  • Saldos derivados do extrato a cada leitura, nunca guardados como total corrente que pode divergir das linhas que diz resumir
  • Parcelas como irmãs sob um mesmo identificador de grupo, sem primeira linha privilegiada: forma que depois serviu inalterada para uma conta dividida entre vários moradores, sem tabela nova
  • Recorrência idempotente por ponteiro de progresso, que distingue "ainda não gerado" de "gerado e descartado de propósito"
  • Erro e log que não carregam dado financeiro nem pessoal, por registrar qual operação falhou em vez de manter lista de redação
  • Pacote de matemática financeira puro e sem dependências, coberto por testes automatizados: parcelamento, ciclo de fatura, recorrência, juros e desconto, e leitura offline dos dígitos de um boleto

Desafios

  • Uma falha real em produção onde as políticas de isolamento corretas nunca eram alcançadas, porque a checagem de permissão da tabela negava a requisição antes: política certa atrás de grant ausente se parece exatamente com produto quebrado
  • Modelar dinheiro que entra sem ter sido ganho (principal de empréstimo, correção de saldo não lançado) de forma que o saldo fique certo sem contaminar o que deriva de renda
  • Manter uma casa livre pra renomear as próprias categorias enquanto o sistema ainda precisa encontrar as que ele mesmo usa
  • Categorizar descrição digitada sem mandar o gasto da casa pra fora nem depender de rede

Responsabilidades

  • Desenhar o modelo multi-inquilino e a fronteira de isolamento
  • Implementar a API e as regras de negócio, incluindo a aritmética de calendário e arredondamento
  • Construir o cliente único que atende iOS, Android e web
  • Operar o produto em produção, com e-mail transacional no fluxo real de conta

Resultados

  • Em produção e em uso diário pela família, não em ambiente de demonstração; o lançamento nas lojas (Android e iOS) está previsto para 2027
  • Projetado para consumir a plataforma do ecossistema apenas pela API dela, sem acesso ao código nem ao banco; essa integração ainda não está ligada
  • O pacote de matemática financeira, testado, já está separado para ser publicado de forma independente

Aprendizados

  • Política de isolamento correta é inútil se a permissão embaixo dela nega antes. O modo de falha não avisa que é de permissão: ele se apresenta como o produto simplesmente não funcionando, e foi preciso uma falha em produção pra aprender a olhar uma camada abaixo
  • Derivar sai mais barato que guardar: saldo calculado a cada leitura nunca diverge do extrato que diz resumir, e o custo de recalcular é irrisório perto do custo de reconciliar depois
  • Uma forma boa se paga duas vezes: parcelas como irmãs sob um grupo, sem linha privilegiada, resolveu inalterada um problema não relacionado (uma conta paga por várias pessoas), sem tabela nova e sem nenhum leitor precisar saber que o grupo existe
  • Idempotência tem que ser por ponteiro, não por "já existe um registro?": essa pergunta não distingue "ainda não gerei" de "gerei e o usuário descartou de propósito"
  • Nem toda categorização pede modelo de linguagem: pontuar contra o histórico da própria casa resolveu melhor aqui, mantém o gasto dentro do sistema e funciona sem rede

Stack

TypeScriptExpo RoutertRPCNode.jsPostgreSQLRow-Level SecurityVitest