Tucano: finanças e compras com agente no Telegram
Meu papel
Projeto pessoal: autor do produto inteiro, do design e da identidade ao agente no Telegram.
Controle financeiro morre na hora de anotar. O Tucano junta finanças e lista de compras num app só e tira o atrito do registro: dá para lançar um gasto mandando uma mensagem, ou um áudio, para um bot no Telegram.
Agente no Telegram: "gastei 50 no mercado no Nubank em 3x" vira uma transação no cartão, parcelada e já com categoria. Entende áudio, lembra o contexto da conversa e responde consultas como o resumo do mês.
Finanças: receitas e despesas por competência, pendente ou pago, assinaturas recorrentes e cartões de crédito.
Compras: listas mensais com orçamento, catálogo de produtos com marca padrão e preço por unidade.
Painel: as análises do mês numa tela só.
Mobile-first: navegação inferior, botão flutuante e formulários em bottom sheet, para lançar algo em segundos.
Por baixo: React 19 + Vite + TypeScript no front, Convex como backend (banco, autenticação, storage e HTTP actions para o webhook do Telegram), OpenRouter para o agente, transcrição de áudio pela OpenAI e deploy contínuo na Vercel.
Antes
A primeira versão, em Firebase, dependia de formulário para tudo, e a consulta do dashboard fazia cerca de 91 leituras ao banco.
O problema
Planilha de gastos funciona por duas semanas. O difícil sempre foi registrar: abrir o app certo, achar a categoria, lembrar em qual cartão passou e em quantas vezes. Cada passo a mais é um gasto que fica de fora, e um controle com buraco não serve para decidir nada.
A primeira versão do Tucano, em Firebase, já juntava finanças e lista de compras, mas ainda dependia de formulário para tudo. Faltava um jeito de registrar na hora, do jeito que a gente fala.
A solução
Reescrevi o Tucano do zero com React 19, Vite e TypeScript no front e Convex como backend: banco, autenticação, storage e consultas em tempo real, com deploy contínuo na Vercel publicando o Convex junto.
A peça central é um agente no Telegram. Um webhook (HTTP action do Convex) recebe a mensagem; se for áudio, a OpenAI transcreve; um modelo via OpenRouter interpreta o pedido e devolve uma de 13 ações estruturadas (lançar despesa, compra parcelada no cartão, assinatura, item na lista, resumo do mês…). Cada ação é validada antes de virar caso de uso, a categoria é escolhida entre as do próprio usuário e o contexto da conversa fica guardado para pedidos em vários turnos.
No app, a interface é mobile-first: navegação inferior, botão flutuante e bottom sheet. O dashboard concentra análises do mês; a consulta dele começou com cerca de 91 leituras ao banco e caiu para 3 com busca em lote. A identidade visual é uma cor só, verde sobre quase-preto, e o logo nasce do anel da visão mensal.
Decisões e trade-offs
O modelo devolve uma de 13 ações estruturadas, validadas antes de virar caso de uso, em vez de executar texto livre. A categoria é escolhida entre as do próprio usuário. O dashboard passou a buscar em lote, caindo de cerca de 91 para 3 leituras.
Os resultados
O Tucano está no ar, com o agente do Telegram funcionando de ponta a ponta. Registrar um gasto virou mandar uma mensagem ou um áudio; o lançamento já cai com valor, cartão, parcelas e categoria, e aparece no app em tempo real. A reescrita saiu em 40 commits, com testes em Vitest e convex-test cobrindo o agente, a transcrição e o webhook.
Resultados em números
- 91 → 3Leituras no dashboard
- 13Ações do agente
- 10Tabelas no Convex
- 40Commits da reescrita
- 10Arquivos de teste