Skip to content
RafaelHDSVPublic

About

Controle financeiro pessoal para entender o mês sem virar planilha: contas, lançamentos, importação de extrato, orçamentos, caixinhas de investimento, a pagar, dashboard e relatórios.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Fluxo

Veja seu dinheiro com clareza.
Controle financeiro pessoal em BRL — sem planilha, sem Open Finance, com o extrato que você já tem.

Demo ao vivo GitHub MIT Stack Node 22+

Abrir app · Preview · Setup · Contribuir


💡 O que é

Controle financeiro individual: contas, lançamentos manuais, orçamentos, caixinhas, a pagar, dashboard e relatórios (importação CSV/OFX opcional/legado).

Autenticação Supabase, dados isolados por usuário (RLS), moeda BRL.

🚨 Problema Planilha e apps genéricos não batem com o extrato do banco nem com a fatura do cartão.
🎯 Abordagem O saldo da conta é a âncora; lançamento pago move o caixa; cartão usa compra e vencimento.
🚫 Fora de escopo Open Finance (custo de agregador) — entrada principal = arquivo que você exporta.

🖼️ Preview

Dados fictícios (valores altos de propósito). Nada de conta bancária real.

Dashboard do Fluxo

Mais telas (login, transações, contas, investimentos)
Login Transações
Login Transações
Contas Investimentos
Contas Investimentos

Como funciona

SPA React  →  BFF Express (Vercel /api)  →  Supabase (fluxo_* + Auth + RLS)
                      ↓
            saldo da conta = âncora; lançamento pago move o caixa

Produção: https://fluxo.getvieira.com. Living docs: docs/context.md.


🎯 Por que assim

  • ⚓ Saldo das contas é a âncora (editável; lançamento pago move o saldo)
  • 📊 No dashboard (período atual), o Saldo do mês espelha essa âncora — não é “receitas − despesas”
  • ✍️ Entrada principal: lançamento manual (CSV/OFX legado, se ainda tiver extrato)
  • 💳 No cartão, compra e vencimento são datas diferentes; períodos usam o vencimento
  • 🚫 Open Finance fica de fora de propósito

✨ Funcionalidades

🏦 Contas e saldo

  • Contas de débito e cartão de crédito
  • Saldo âncora; marcar pago (débito/fatura) baixa a conta
  • Cartão: fechamento + vencimento da fatura

💳 Transações

  • Receita, despesa, transferência e ajuste
  • Marcar pago move o saldo da conta de pagamento
  • Crédito: data da compra + vencimento; fatura paga baixa a corrente
  • Transferência ↔ caixinha (aporte/resgate)

📥 Importações

  • Importação legado: CSV/OFX genérico
  • Regras de renomeação e categorização
  • Preview + stepper antes de gravar

🎯 Orçamentos, caixinhas e wishlist

  • Limite por categoria com alerta perto do teto
  • Caixinhas (CRUD) com progresso
  • Wishlist com imagem opcional

📊 A pagar, dashboard e relatórios

  • Pendências do período
  • KPIs e gráficos (ECharts)
  • Saldo do mês (atual) = âncora da conta

📱 Experiência

  • Tema claro / escuro
  • Sidebar no desktop
  • Nav inferior + “Mais” no mobile (safe-area)

🔧 Stack

Camada Tecnologia
🎨 Frontend React 18 · Vite · TypeScript · Tailwind · shadcn/ui · React Router · ECharts · Lucide
⚙️ Backend Node.js · Express 5 (BFF → Serverless /api na Vercel)
🔒 Auth / DB Supabase — PostgreSQL · Auth (e-mail/senha) · RLS
🛠️ Tooling Yarn na raiz · Node 22+

Tabelas fluxo_*. Front → BFF (JWT) → Postgres.

frontend/          # Vite + React
backend/           # Express BFF + migrations
  migrations/      # SQL 001 → 010
  src/modules/     # rotas por domínio
.github/           # templates de issue/PR

docs/ e backend/scripts/ são locais — não vão no repositório público.


⚡ Setup

✅ Pré-requisitos

🗄️ 1. Banco

No SQL Editor do Supabase, aplique backend/migrations/ na ordem (001 → 010).

🔑 2. Variáveis de ambiente

cp frontend/.env.example frontend/.env
cp backend/.env.example backend/.env
Variável Onde Uso
VITE_SUPABASE_URL frontend URL do projeto
VITE_SUPABASE_ANON_KEY frontend Chave anônima (cliente)
VITE_BACKEND_URL frontend Local: http://localhost:3693. Produção: vazio (same-origin)
DATABASE_URL backend Connection string Postgres
SUPABASE_URL backend Auth / JWKS
SUPABASE_ANON_KEY backend Runtime
SUPABASE_JWT_SECRET backend Recomendado (Dashboard → API → JWT Secret)
CORS_ORIGIN backend Local: http://localhost:3333
PORT backend Local: 3693

Nunca commite .env com valores reais — só .env.example.

🚀 3. Subir localmente

yarn
yarn dev
Serviço URL
Frontend http://localhost:3333
API (BFF) http://localhost:3693

Crie a conta no registro, cadastre as contas (saldo) e lance as transações na mão.

🧪 Scripts úteis

cd backend && yarn test     # parsers OFX/CSV e ciclo de crédito
cd frontend && yarn lint
cd frontend && yarn build
cd backend && yarn build

☁️ Deploy (Vercel)

Um projeto serve o SPA e o BFF em /api/*.

  1. Importe o repositório (Root Directory = raiz do monorepo).
  2. Configure as variáveis:
Variável Obrigatória Notas
VITE_SUPABASE_URL sim Build do front
VITE_SUPABASE_ANON_KEY sim Build do front
VITE_BACKEND_URL não Vazio em produção
DATABASE_URL sim Runtime
SUPABASE_URL sim Runtime
SUPABASE_ANON_KEY sim Runtime
SUPABASE_JWT_SECRET recomendado Validação JWT
CORS_ORIGIN opcional Local usa http://localhost:3333
  1. Publique. Em produção o front chama /api/... no mesmo domínio.

📝 Decisões de produto

Tema Decisão
Moeda BRL apenas
Open Finance Fora de escopo
Saldo Âncora = fluxo_accounts.balance; período atual no dashboard usa essa âncora
Pago Toggle de despesa reaplica delta de caixa (fluxo manual sem OFX)
Crédito Entra em despesas/orçamentos pela data efetiva; pagar a fatura baixa a conta de pagamento
Caixinhas Aporte/resgate via transferência + goal_id / goal_direction

Mudanças nessas regras: discuta na issue antes de implementar.


🤝 Contribuindo

  1. Descreva problema e solução no PR
  2. Rode lint, testes e build
  3. Sem secrets no diff

CONTRIBUTING.md · Código de Conduta · vulnerabilidades: SECURITY.md


📄 Licença

MIT © 2026 Rafael Vieira — LICENSE.


☕ Apoie o projeto

Se o Fluxo te ajudou a organizar as finanças ou serviu de base para outro trabalho, um café faz diferença.

Buy Me a Coffee

Comunidade: CHANGELOG · CONTRIBUTING · CODE_OF_CONDUCT

About

Controle financeiro pessoal para entender o mês sem virar planilha: contas, lançamentos, importação de extrato, orçamentos, caixinhas de investimento, a pagar, dashboard e relatórios.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Used by

Contributors

Languages