Um pequeno dashboard financeiro full-stack construído com Next.js. Ele lê faturas de cartão de crédito em arquivos CSV, classifica estabelecimentos em categorias, expõe rotas de API no servidor e renderiza gráficos e tabelas em um cliente React.
Ao vivo em: https://cardtracker.sugiro.ai/
O que é usado neste projeto e qual papel cada peça desempenha.
Next.js é o framework principal. Ele cuida de rotas, renderização no servidor, endpoints de API e do processo de build. O projeto usa a pasta app/ , ou seja, segue o modelo mais novo de App Router em vez do router legado baseado em pages/ .
React sustenta o dashboard interativo. O painel principal é um componente cliente, então gráficos, filtros, atribuição de categoria, estado local e chamadas de busca rodam no navegador depois que a aplicação carrega.
O código é escrito em JavaScript, não em TypeScript. Não existem arquivos de tipos nem configuração de TS, então o projeto fica mais leve, mas abre mão de checagem estática.
Recharts é usado para a camada visual de relatórios. Ele dirige os gráficos de pizza e linha do dashboard e se encaixa naturalmente na árvore de componentes React.
Os dados de transação vêm de arquivos CSV mensais. As regras de categorização são semeadas em arquivos JSON. Em desenvolvimento local, as alterações podem ser persistidas em JSON; em deploy, o projeto pode usar Upstash Redis.
O código do servidor usa APIs do Node como node:fs, node:path, e node:crypto. Isso significa que não é um site puramente estático: ele precisa de um runtime Node para ler arquivos, processar dados e atender requisições autenticadas.
A história de runtime, da requisição no navegador ao dashboard renderizado.
O projeto roda com next dev localmente e next build mais next start em produção. A rota principal vive em app/page.js.
Antes de mostrar o dashboard, o servidor verifica cookies e senhas baseadas em ambiente em lib/auth.js. Se o usuário não estiver autenticado, a aplicação renderiza uma tela de senha no lugar do painel.
Depois do login, o componente de dashboard no navegador chama /api/months, /api/data/[month]e /api/categories. Esses handlers rodam no servidor e retornam JSON.
O servidor carrega arquivos de fatura da pasta do perfil selecionado, parseia as linhas CSV, normaliza nomes de estabelecimentos, aplica regras de categorização e devolve os dados preparados para a interface.
O componente cliente mantém meses carregados em estado local, calcula totais, filtra categorias, ordena transações e alimenta visualizações do Recharts e tabelas customizadas.
O projeto é compacto, mas ainda assim possui uma divisão de responsabilidades bastante clara.
package.json next.config.mjs app/page.js app/api/months/route.js app/api/data/[month]/route.js app/api/categories/route.js components/dashboard-client.js lib/auth.js lib/profiles.js lib/statements.js lib/rules-store.js lib/normalize.js
Esta é uma estrutura típica de Next.js full-stack pequeno: rotas em app/, UI em components/, e lógica de servidor reaproveitável em lib/.
Este app é orientado por arquivos, com Redis como ajudante opcional de deploy.
Transações vivem em arquivos CSV mensais como 2026-04.csv.
Regras de categoria ficam em arquivos JSON como categories.json.
O servidor lê esses arquivos diretamente usando as APIs de filesystem do Node.
Isso deixa o projeto simples de entender e fácil de rodar localmente.
O projeto inclui @upstash/redis como dependência.
Se as credenciais Redis existirem, regras salvas vão para um hash no Redis.
Sem Redis, o desenvolvimento local volta para arquivos JSON.
Os extratos em si continuam baseados em arquivo, não em banco de dados.
Um sistema de autenticação leve e próprio, em vez de um provider externo.
O app gera um hash da senha específica do perfil e o grava em um cookie HTTP-only. A cada requisição, o servidor verifica se esse cookie bate com a senha configurada nas variáveis de ambiente. É muito mais simples que OAuth ou um banco de usuários, e cabe bem em uma ferramenta pessoal.
lib/profiles.js define perfis separados para a conta principal, uma conta secundária e um modo demo. Cada perfil tem seu próprio diretório de extratos, arquivo de categorias, chave Redis e variável de ambiente para senha.
Os comandos práticos que fazem o projeto rodar.
npm install npm run dev npm run build npm start
O script dev limpa a pasta .next e inicia o servidor de desenvolvimento. Build e start são os comandos normais de produção em Next.js.
DASHBOARD_PASSWORD_[NOMEDOPERFIL] para perfis protegidos.
UPSTASH_REDIS_REST_URL e UPSTASH_REDIS_REST_TOKEN apenas se a persistência com Redis for desejada.
Arquivos CSV de extrato disponíveis nos diretórios de perfil esperados.
Card Tracker é uma pequena aplicação full-stack em Next.js, não apenas um site frontend. Ela usa React para a UI, Node.js no servidor, JavaScript em vez de TypeScript, arquivos CSV e JSON como camada de dados principal e Upstash Redis apenas como camada opcional de persistência para regras. A arquitetura é simples e prática: dados em arquivo, autenticação própria, rotas de API e um dashboard no navegador com gráficos.