FinTrack
Plataforma de gestão financeira pessoal inspirada em aplicações de organização financeira, desenvolvida com foco em arquitetura, experiência do usuário e evolução para recursos de Open Finance.
Visão geral
FinTrack é uma plataforma de gestão financeira pessoal pensada como um produto SaaS. O backend é Laravel e a interface é Vue 3 com TypeScript, ligados por Inertia.js, o que dispensa uma API REST separada para as telas do aplicativo.
As telas cobrem o fluxo de um produto financeiro: dashboard, lançamentos, contas, cartões de crédito, relatórios, limites de gastos, conexão bancária (Open Finance), notificações, perfil, assinatura e suporte, além de landing page e blog público.
Tecnologias
- Laravel
- PHP
- Vue 3
- Inertia.js
- Tailwind CSS
- PostgreSQL
- Docker
Funcionalidades
- Login com validação e limite de tentativas por usuário e IP, além das telas de cadastro e de recuperação de senha.
- Telas do aplicativo em Vue 3 + TypeScript: dashboard, lançamentos, contas, cartões, limites de gastos, notificações, perfil, assinatura e suporte.
- Relatórios mensal, anual, por categoria e de receitas versus despesas.
- Tela de Conexão Bancária que representa o fluxo de Open Finance Brasil: instituições, modal de autorização em etapas e status por conta.
- Registro de despesas por WhatsApp: uma mensagem como "gastei R$ 35 no almoço" vira uma transação, via workflow n8n e endpoint da API do Laravel.
- Endpoint POST /api/n8n/webhook protegido por segredo em header, com limite de 30 requisições por minuto e validação do payload.
- Landing page, página de planos e blog público.
Arquitetura
FinTrack é um monólito Laravel com Inertia.js: os controllers devolvem páginas Vue diretamente, sem camada de API para a interface. A única API HTTP é a usada pela automação com n8n.
- Rotas separadas por contexto em routes/web (public, auth, app e admin), mais routes/api.php para a integração com o n8n.
- Controllers do aplicativo organizados por módulo em app/Http/Controllers/App (Conta, Lançamento, Cartão de Crédito, Categorias, Relatório, Limites de Gastos, Perfil, Plano, Suporte, Conexão Bancária, Configurações).
- Páginas Vue em resources/js/pages (App, Auth, Web e Blog) e componentes reutilizáveis em resources/js/Components (buttons, inputs, feedback e layout).
- Ziggy e Laravel Wayfinder expõem as rotas do Laravel para o frontend.
- Middleware próprio (EnsureN8nSecret) e rate limiter dedicado ("n8n") para a rota de integração.
Integração com n8n e WhatsApp
O workflow "WhatsApp — Registrar Despesa" está versionado no repositório (docker/n8n/workflows). Ele recebe a mensagem por webhook, interpreta o texto, chama a API do Laravel e responde ao usuário pelo WhatsApp.
- Webhook recebe a mensagem e um nó de código extrai o texto.
- Outro nó de código identifica o valor (aceita formatos como "R$ 35", "35,90" e "25.90"), a descrição e uma categoria por palavras-chave, com "Outros" como padrão.
- Se a mensagem foi reconhecida, o workflow chama POST /api/n8n/webhook no Laravel; caso contrário, responde com uma mensagem de formato inválido.
- Sucesso, erro da API e formato inválido têm respostas distintas, tanto para o webhook quanto para o envio no WhatsApp.
- No Docker Compose, o n8n roda ao lado de uma instância da Evolution API, usada para o envio das mensagens.
Banco de dados e infraestrutura
O banco do aplicativo Laravel é SQLite por padrão (.env.example) e o Docker Compose provê um MySQL 8.4 para o ambiente com Sail. O PostgreSQL 16 do compose é o banco da Evolution API, o serviço de WhatsApp usado pela automação.
- Migrations de users, accounts (banco, tipo de conta, saldo), credit_cards (bandeira, limite, fatura) e transactions (tipo receita, despesa ou transferência, valor, data, categoria, pago).
- Tabelas do blog: posts, categories, authors, tags, post_meta, media, newsletter_subscribers e social_accounts.
- Docker Compose com aplicação (Sail), MySQL, PostgreSQL, Redis, Evolution API e n8n.
Screenshots
Desenvolvimento e desafios
O backend usa Laravel 13 (PHP 8.4 ou superior) e Inertia.js 2. O frontend usa Vue 3.5, TypeScript 5.9, Tailwind CSS 4 e Vite 7, com ícones Lucide. ESLint e Prettier cuidam da qualidade do código do frontend.
O desenvolvimento seguiu a linha "interface primeiro": as telas e as rotas nomeadas de cada módulo foram estruturadas antes da persistência. Hoje a persistência real está no login, nas migrations e no fluxo de transações via n8n.
Transformar texto livre em lançamento financeiro
Desafio
Mensagens de WhatsApp como "paguei R$ 25,90 no café" não têm formato fixo, e o valor pode vir com ou sem "R$", com vírgula ou ponto.
Solução
Um nó de código no n8n extrai o valor por expressão regular, deriva a descrição do trecho após preposições como "no", "na" e "de", e classifica a categoria por palavras-chave. Mensagens que não seguem o padrão recebem uma resposta de formato inválido em vez de gerar um lançamento errado.
Proteger o endpoint chamado pela automação
Desafio
A rota que cria transações é chamada por um serviço externo, sem sessão de usuário, e não pode ficar aberta.
Solução
O middleware EnsureN8nSecret compara o header X-N8N-Secret com o segredo configurado e responde 401 quando ele é inválido. A rota tem limite de 30 requisições por minuto, valida o payload (tipo, valor maior que zero, data no formato Y-m-d) e associa a transação a um usuário definido em configuração. Os testes de feature cobrem autenticação, validação e criação da transação.
Da interface à persistência
Desafio
As telas foram construídas antes do backend de cada módulo. Nos controllers de contas, lançamentos, cartões e conexão bancária, as ações de escrita ainda estão marcadas como TODO, e as telas trabalham com dados de exemplo.
Solução
As migrations de accounts, credit_cards e transactions já existem, e o primeiro fluxo de escrita implementado é o registro de transações pela API. Conectar as demais ações dos controllers a esses modelos é o passo seguinte do projeto.
Conclusão
FinTrack foi um exercício de arquitetura full-stack: monólito Laravel com Inertia e Vue, automação de entrada de dados por WhatsApp com n8n e modelagem inicial do domínio financeiro. O projeto segue em evolução: a interface está estruturada para receber a persistência dos módulos e a integração Open Finance ainda é uma representação em interface, sem conexão real com instituições.
Projetos relacionados
FutureData
Sistema de gestão para assistência técnica: ordens de serviço de ponta a ponta, portal do cliente e atendimento automatizado por WhatsApp com IA.