Projeto pessoal de gestão financeira. Self-hosted, manual e open source.

⚠️ Não há versão online hospedada. Você precisa clonar o repositório e rodar localmente ou no seu próprio servidor ou computador.

---

---

📖 Índice

• Sobre o Projeto
• Features
• Tech Stack
• Início Rápido
  • Opção 1: Desenvolvimento Local (Recomendado para Devs)
  • Opção 2: Docker Completo (Usuários Finais)
  • Opção 3: Docker + Banco Remoto
• Scripts Disponíveis
• Docker - Guia Detalhado
• Configuração de Variáveis de Ambiente
• Banco de Dados
• Arquitetura
• Contribuindo
• Apoie o Projeto

---

🎯 Sobre o Projeto

Opensheets é um projeto pessoal de gestão financeira que criei para organizar minhas próprias finanças. Cansei de usar planilhas desorganizadas e aplicativos que não fazem exatamente o que preciso, então decidi construir algo do jeito que funciona pra mim.

A ideia é simples: ter um lugar onde consigo ver todas as minhas contas, cartões, gastos e receitas de forma clara. Se isso for útil pra você também, fique à vontade para usar e contribuir.

📊 Estatísticas do Projeto

• ~200 componentes React organizados por feature
• 15+ tabelas de banco de dados com relações complexas
• 20+ widgets no dashboard principal
• 18+ queries paralelas otimizadas para performance
• 736 linhas de schema Drizzle ORM
• Docker multi-stage com imagem final de ~200MB
• 100% TypeScript com strict mode
• Self-hosted - seus dados, seu controle

💡 Licença Não-Comercial: Este projeto é gratuito para uso pessoal, mas não pode ser usado comercialmente. Veja mais detalhes na seção Licença.

⚠️ Avisos importantes

1. Não há versão hospedada online

Este projeto é self-hosted. Você precisa rodar no seu próprio computador ou servidor. Não existe uma versão pública online onde você pode simplesmente criar uma conta.

2. Não há Open Finance

Você precisa registrar manualmente suas transações. Se você procura algo que sincroniza automaticamente com seu banco, este projeto não é pra você.

3. Requer disciplina

O Opensheets funciona melhor para quem:

• Tem disciplina de registrar os gastos regularmente
• Quer controle total sobre seus dados
• Gosta de entender exatamente onde o dinheiro está indo
• Sabe rodar projetos localmente ou tem vontade de aprender

Se você não se importa em dedicar alguns minutos por dia (ou semana) para manter tudo atualizado, vai funcionar bem. Caso contrário, provavelmente vai abandonar depois de uma semana.

O que tem aqui

💰 Controle de contas e transações

• Registre suas contas bancárias, cartões e dinheiro em espécie
• Adicione receitas, despesas e transferências entre contas
• Organize tudo por categorias (moradia, alimentação, transporte, etc.)
• Veja o saldo atual de cada conta e extratos detalhados
• Importação em massa de lançamentos via texto

📊 Relatórios e gráficos

• Dashboard com resumo mensal das suas finanças
• Gráficos de evolução do patrimônio
• Comparação de gastos por categoria
• Relatórios detalhados de categorias com histórico
• Entenda pra onde seu dinheiro está indo

💳 Faturas de cartão de crédito

• Cadastre seus cartões e acompanhe as faturas
• Veja o que ainda não foi fechado na fatura atual
• Controle de limites e vencimentos
• Visualização de faturas por período

🎯 Orçamentos

• Defina quanto quer gastar por categoria no mês
• Acompanhe se está dentro do planejado
• Indicadores visuais de progresso do orçamento

💸 Parcelamentos avançados

• Controle completo de compras parceladas
• Antecipação de parcelas com cálculo de desconto
• Análise consolidada de parcelas em aberto
• Rastreamento de séries de parcelas

🤖 Insights com IA

• Análises financeiras geradas por IA (Claude, GPT, Gemini)
• Insights personalizados sobre seus gastos
• Recomendações e alertas inteligentes
• Histórico de insights salvos por período

👥 Gestão colaborativa

• Cadastro de pagadores/recebedores
• Sistema de compartilhamento com permissões (admin/viewer)
• Notificações automáticas por e-mail
• Colaboração em lançamentos compartilhados

📝 Anotações e tarefas

• Notas de texto para organização
• Listas de tarefas com checkboxes
• Sistema de arquivamento
• Anexação de anotações a lançamentos

📅 Visualização em calendário

• Visão mensal de todos os lançamentos
• Navegação intuitiva por data
• Filtros e organização temporal

⚙️ Preferências e personalização

• Tema claro/escuro
• Modo privacidade (oculta valores)
• Customização de comportamento (magnetlines, etc.)
• Configurações de usuário personalizadas

Stack técnica

Construído com tecnologias modernas que facilitam o desenvolvimento:

• Next.js 16 com App Router e Turbopack
• TypeScript em tudo
• PostgreSQL 18 como banco de dados
• Drizzle ORM para trabalhar com o banco
• Better Auth para login (email + OAuth)
• shadcn/ui para os componentes da interface
• Docker para facilitar deploy e desenvolvimento
• Tailwind CSS para estilização

O projeto é open source, seus dados ficam no seu controle (pode rodar localmente ou no seu próprio servidor), e você pode customizar o que quiser.

---

✨ Features

🔐 Autenticação

• Better Auth 1.4.10 integrado
• OAuth (Google)
• Autenticação por email/senha
• Session management com tokens
• Protected routes via middleware
• Verificação de email

🗄️ Banco de Dados

• PostgreSQL 18 (última versão estável)
• Drizzle ORM 0.45 com TypeScript
• Migrations automáticas
• Drizzle Studio (UI visual para DB)
• Suporte para banco local (Docker) ou remoto (Supabase, Neon, etc)
• Índices otimizados para performance
• Relações complexas e integridade referencial

💼 Gestão Financeira

• Controle completo de contas bancárias
• Gerenciamento de cartões de crédito
• Lançamentos com suporte a:
  • Receitas e despesas
  • Transferências entre contas
  • Parcelamentos com séries
  • Antecipação de parcelas
  • Recorrências
• Categorização flexível
• Orçamentos mensais por categoria
• Faturas de cartão de crédito

🤖 Inteligência Artificial

• Integração com múltiplos providers:
  • Anthropic Claude
  • OpenAI GPT
  • Google Gemini
  • OpenRouter
• Análises financeiras personalizadas
• Insights salvos e histórico

👥 Colaboração

• Sistema de pagadores/recebedores
• Compartilhamento com permissões granulares
• Notificações por email (Resend)
• Códigos de compartilhamento únicos
• Multi-usuário com isolamento de dados

📊 Relatórios e Analytics

• Dashboard interativo com 20+ widgets
• Relatórios detalhados de categorias
• Histórico de transações
• Análise de parcelas consolidada
• Gráficos com Recharts
• Exportação de dados (PDF, Excel)

🎨 Interface

• shadcn/ui components (Radix UI)
• Tailwind CSS v4
• Dark mode com next-themes
• Animações fluidas com Motion
• Responsive design
• Modo privacidade (oculta valores)
• Componentes acessíveis (ARIA)

📝 Produtividade

• Sistema de anotações e tarefas
• Calendário de transações
• Importação em massa
• Calculadora integrada
• Preferências personalizáveis
• Changelog integrado

🐳 Docker

• Multi-stage build otimizado
• Health checks para app e banco
• Volumes persistentes
• Network isolada
• Scripts npm facilitados
• Imagem final ~200MB

🧪 Desenvolvimento

• Next.js 16.1 com App Router
• Turbopack (fast refresh)
• TypeScript 5.9 (strict mode)
• ESLint 9
• React 19.2 (com Compiler)
• Server Actions
• Parallel data fetching
• Streaming SSR

---

🛠️ Tech Stack

Frontend

• Framework: Next.js 16.1.1 (App Router)
• Linguagem: TypeScript 5.9.3
• UI Library: React 19.2.3
• Styling: Tailwind CSS 4.1.18
• Components: shadcn/ui (Radix UI)
• Icons: Remixicon 4.8.0
• Animations: Motion 12.23.26
• Tables: TanStack React Table 8.21.3
• Charts: Recharts 3.6.0
• Forms: React Hook Form + Zod 4.3.4
• Theme: next-themes 0.4.6

Backend

• Runtime: Node.js 22
• Database: PostgreSQL 18
• ORM: Drizzle ORM 0.45.1
• Database Driver: pg 8.16.3
• Auth: Better Auth 1.4.10
• Email: Resend 6.6.0
• Validation: Zod 4.3.4

AI Integration (Opcional)

• AI SDK: Vercel AI SDK 6.0.6
• Anthropic: Claude (via @ai-sdk/anthropic 3.0.2)
• OpenAI: GPT (via @ai-sdk/openai 3.0.2)
• Google: Gemini (via @ai-sdk/google 3.0.2)
• OpenRouter: via @openrouter/ai-sdk-provider 1.5.4

Utilities

• Date Handling: date-fns 4.1.0
• Class Management: clsx 2.1.1 + tailwind-merge 3.4.0
• PDF Export: jspdf 4.0.0 + jspdf-autotable 5.0.2
• Excel Export: xlsx 0.18.5
• Toast Notifications: sonner 2.0.7
• Command Palette: cmdk 1.1.1

DevOps

• Containerization: Docker + Docker Compose
• Package Manager: pnpm
• Build Tool: Turbopack
• Linting: ESLint 9.39.2
• Analytics: Vercel Analytics + Speed Insights

---

🚀 Início Rápido

Escolha a opção que melhor se adequa ao seu caso:

Cenário	Quando usar	Comando principal
Opção 1	Você vai desenvolver e alterar código	docker compose up db -d + pnpm dev
Opção 2	Você só quer usar a aplicação	pnpm docker:up
Opção 3	Você já tem um banco remoto	docker compose up app --build

---

Opção 1: Desenvolvimento Local (Recomendado para Devs)

Esta é a melhor opção para desenvolvedores que vão modificar o código.

Pré-requisitos

• Node.js 22+ instalado (se usar nvm, execute nvm install ou nvm use)
• pnpm instalado (ou npm/yarn)
• Docker e Docker Compose instalados

Passo a Passo

1. Clone o repositório

   git clone https://github.com/felipegcoutinho/opensheets-app.git
   cd opensheets-app
   

2. Instale as dependências

   pnpm install
   

3. Configure as variáveis de ambiente

   cp .env.example .env
   

   Edite o .env e configure:

   # Banco de dados (usando Docker)
   DATABASE_URL=postgresql://opensheets:opensheets_dev_password@localhost:5432/opensheets_db
   
   # Better Auth (gere com: openssl rand -base64 32)
   BETTER_AUTH_SECRET=seu-secret-aqui
   BETTER_AUTH_URL=http://localhost:3000
   

4. Suba apenas o PostgreSQL em Docker

   docker compose up db -d
   

   Isso sobe apenas o banco de dados em container. A aplicação roda localmente.

5. Ative as extensões necessárias no PostgreSQL

   pnpm db:enableExtensions
   

   Ou você pode importar o script diretamente no banco de dados: scripts/postgres/init.sql

6. Execute as migrations

   pnpm db:push
   

7. Inicie o servidor de desenvolvimento

   pnpm dev
   

8. Acesse a aplicação

   http://localhost:3000
   

Por que esta opção?

• ✅ Hot reload perfeito - Mudanças no código refletem instantaneamente
• ✅ Debugger funciona - Use breakpoints normalmente
• ✅ Menos recursos - Só o banco roda em Docker
• ✅ Drizzle Studio - Acesse com pnpm db:studio
• ✅ Melhor DX - Developer Experience otimizada

---

Opção 2: Docker Completo (Usuários Finais)

Ideal para quem quer apenas usar a aplicação sem mexer no código.

Pré-requisitos

• Docker e Docker Compose instalados

Passo a Passo

1. Clone o repositório

   git clone https://github.com/felipegcoutinho/opensheets-app.git
   cd opensheets-app
   

2. Configure as variáveis de ambiente

   cp .env.example .env
   

   Edite o .env:

   # Use o host "db" (nome do serviço Docker)
   DATABASE_URL=postgresql://opensheets:opensheets_dev_password@db:5432/opensheets_db
   
   # Better Auth
   BETTER_AUTH_SECRET=seu-secret-aqui
   BETTER_AUTH_URL=http://localhost:3000
   

3. Suba tudo em Docker

   pnpm docker:up
   # ou: docker compose up --build
   

   Isso sobe aplicação + banco de dados em containers.

4. Acesse a aplicação

   http://localhost:3000
   

5. Para parar

   pnpm docker:down
   # ou: docker compose down
   

Dicas

• Use pnpm docker:up:detached para rodar em background
• Veja logs com pnpm docker:logs
• Reinicie com pnpm docker:restart

---

Opção 3: Docker + Banco Remoto

Se você já tem PostgreSQL no Supabase, Neon, Railway, etc.

Passo a Passo

1. Configure o .env com banco remoto

   DATABASE_URL=postgresql://user:password@host.region.provider.com:5432/database?sslmode=require
   
   BETTER_AUTH_SECRET=seu-secret-aqui
   BETTER_AUTH_URL=http://localhost:3000
   

2. Suba apenas a aplicação

   docker compose up app --build
   

3. Acesse a aplicação

   http://localhost:3000
   

---

📜 Scripts Disponíveis

Desenvolvimento

# Servidor de desenvolvimento (com Turbopack)
pnpm dev

# Build de produção
pnpm build

# Servidor de produção
pnpm start

# Linter
pnpm lint

Banco de Dados (Drizzle)

# Gerar migrations a partir do schema
pnpm db:generate

# Executar migrations
pnpm db:migrate

# Push schema direto para o banco (dev only)
pnpm db:push

# Abrir Drizzle Studio (UI visual do banco)
pnpm db:studio

Docker

# Subir todos os containers (app + banco)
pnpm docker:up

# Subir em background (detached mode)
pnpm docker:up:detached

# Parar todos os containers
pnpm docker:down

# Parar e REMOVER volumes (⚠️ apaga dados do banco!)
pnpm docker:down:volumes

# Ver logs em tempo real
pnpm docker:logs

# Logs apenas da aplicação
pnpm docker:logs:app

# Logs apenas do banco de dados
pnpm docker:logs:db

# Reiniciar containers
pnpm docker:restart

# Rebuild completo (força reconstrução)
pnpm docker:rebuild

Utilitários

# Setup automático de variáveis de ambiente
pnpm env:setup

---

🐳 Docker - Guia Detalhado

Arquitetura Docker

┌─────────────────────────────────────────────────┐
│              docker-compose.yml                 │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────────┐      ┌─────────────────┐ │
│  │   app            │      │      db         │ │
│  │   (Next.js 16)   │◄─────┤  (PostgreSQL 18)│ │
│  │   Port: 3000     │      │  Port: 5432     │ │
│  │   Node.js 22     │      │  Alpine Linux   │ │
│  └──────────────────┘      └─────────────────┘ │
│                                                 │
│  Network: opensheets_network (bridge)                │
│  Volume: opensheets_postgres_data (persistent)       │
│                                                 │
└─────────────────────────────────────────────────┘

Multi-Stage Build

O Dockerfile usa 3 stages para otimização:

1. deps - Instala dependências
2. builder - Builda a aplicação (Next.js standalone)
3. runner - Imagem final mínima (apenas produção)

Benefícios:

• Imagem final muito menor (~200MB vs ~1GB)
• Build cache eficiente
• Apenas dependências de produção no final
• Security: roda como usuário não-root

Health Checks

Ambos os serviços têm health checks:

PostgreSQL:

• Comando: pg_isready
• Intervalo: 10s
• Timeout: 5s

Next.js App:

• Endpoint: http://localhost:3000/api/health
• Intervalo: 30s
• Start period: 40s (aguarda build)

Volumes e Persistência

volumes:
  postgres_data:
    name: opensheets_postgres_data
    driver: local

• Os dados do PostgreSQL persistem entre restarts
• Para apagar dados: pnpm docker:down:volumes
• Para backup: docker compose exec db pg_dump...

Network Isolada

networks:
  opensheets_network:
    name: opensheets_network
    driver: bridge

• App e banco se comunicam via network interna
• Isolamento de segurança
• DNS automático (app acessa db:5432)

Comandos Docker Avançados

# Entrar no container da aplicação
docker compose exec app sh

# Entrar no container do banco
docker compose exec db psql -U opensheets -d opensheets_db

# Ver status dos containers
docker compose ps

# Ver uso de recursos
docker stats opensheets_app opensheets_postgres

# Backup do banco
docker compose exec db pg_dump -U opensheets opensheets_db > backup.sql

# Restaurar backup
docker compose exec -T db psql -U opensheets -d opensheets_db < backup.sql

# Limpar tudo (containers, volumes, images)
docker compose down -v
docker system prune -a

Customizando Portas

No arquivo .env:

# Porta da aplicação (padrão: 3000)
APP_PORT=3001

# Porta do banco de dados (padrão: 5432)
DB_PORT=5433

---

🔐 Configuração de Variáveis de Ambiente

Copie o .env.example para .env e configure:

Variáveis Obrigatórias

# === Database ===
DATABASE_URL=postgresql://opensheets:opensheets_dev_password@localhost:5432/opensheets_db

# === Better Auth ===
# Gere com: openssl rand -base64 32
BETTER_AUTH_SECRET=seu-secret-super-secreto-aqui
BETTER_AUTH_URL=http://localhost:3000

Variáveis Opcionais

PostgreSQL (customização)

POSTGRES_USER=opensheets
POSTGRES_PASSWORD=opensheets_dev_password
POSTGRES_DB=opensheets_db

Portas (customização)

APP_PORT=3000
DB_PORT=5432

OAuth Providers

GOOGLE_CLIENT_ID=seu-google-client-id
GOOGLE_CLIENT_SECRET=seu-google-client-secret

GITHUB_CLIENT_ID=seu-github-client-id
GITHUB_CLIENT_SECRET=seu-github-client-secret

Email (Resend)

RESEND_API_KEY=re_seu_api_key
EMAIL_FROM=noreply@seudominio.com

AI Providers

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_GENERATIVE_AI_API_KEY=...
OPENROUTER_API_KEY=sk-or-...

Gerando Secrets

# BETTER_AUTH_SECRET
openssl rand -base64 32

# Ou use o script automático
pnpm env:setup

---

🗄️ Banco de Dados

Escolhendo entre Local e Remoto

Modo	Quando usar	Como configurar
Local	Desenvolvimento, testes, prototipagem	DATABASE_URL com host "db" ou "localhost"
Remoto	Produção, deploy, banco gerenciado	DATABASE_URL com URL completa do provider

Drizzle ORM

Schema Definition

Os schemas ficam em /db/schema.ts:

import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  email: text("email").notNull().unique(),
  name: text("name"),
  createdAt: timestamp("created_at").defaultNow(),
});

Gerando Migrations

# Após alterar /db/schema.ts
pnpm db:generate

# Aplica migrations
pnpm db:migrate

# Ou push direto (dev only)
pnpm db:push

Drizzle Studio

Interface visual para explorar e editar dados:

pnpm db:studio

Abre em: https://local.drizzle.studio

Migrations Automáticas (Docker)

No docker-compose.yml, migrations rodam automaticamente:

command:
  - |
    echo "📦 Rodando migrations..."
    pnpm db:push

    echo "✅ Iniciando aplicação..."
    node server.js

Backup e Restore

# Backup (banco local Docker)
docker compose exec db pg_dump -U opensheets opensheets_db > backup_$(date +%Y%m%d).sql

# Backup (banco remoto)
pg_dump $DATABASE_URL > backup.sql

# Restore (Docker)
docker compose exec -T db psql -U opensheets -d opensheets_db < backup.sql

# Restore (remoto)
psql $DATABASE_URL < backup.sql

---

🏗️ Arquitetura

Estrutura de Pastas

opensheets/
├── app/                           # Next.js App Router
│   ├── api/                       # API Routes
│   │   ├── auth/[...all]/        # Better Auth endpoints
│   │   └── health/               # Health check endpoint
│   ├── (auth)/                   # Rotas públicas de autenticação
│   │   ├── login/                # Página de login
│   │   └── signup/               # Página de cadastro
│   ├── (dashboard)/              # Rotas protegidas (requer auth)
│   │   ├── dashboard/            # Dashboard principal
│   │   │   └── analise-parcelas/ # Análise de parcelas
│   │   ├── lancamentos/          # Lançamentos/transações
│   │   ├── contas/               # Contas bancárias
│   │   │   └── [contaId]/extrato # Extrato da conta
│   │   ├── cartoes/              # Cartões de crédito
│   │   │   └── [cartaoId]/fatura # Fatura do cartão
│   │   ├── categorias/           # Categorias
│   │   │   ├── historico/        # Histórico de categorias
│   │   │   └── [categoryId]/     # Detalhes da categoria
│   │   ├── pagadores/            # Pagadores/recebedores
│   │   │   └── [pagadorId]/      # Detalhes do pagador
│   │   ├── orcamentos/           # Orçamentos mensais
│   │   ├── anotacoes/            # Anotações e tarefas
│   │   │   └── arquivadas/       # Anotações arquivadas
│   │   ├── insights/             # Insights de IA
│   │   ├── relatorios/           # Relatórios
│   │   │   └── categorias/       # Relatório de categorias
│   │   ├── calendario/           # Visão de calendário
│   │   ├── changelog/            # Histórico de mudanças
│   │   └── ajustes/              # Configurações
│   ├── (landing-page)/           # Página inicial pública
│   ├── layout.tsx                # Root layout
│   └── globals.css               # Estilos globais (Tailwind)
│
├── components/                    # React Components (~200 arquivos)
│   ├── ui/                       # shadcn/ui base components
│   │   ├── button.tsx
│   │   ├── dialog.tsx
│   │   ├── table.tsx
│   │   └── ... (40+ componentes)
│   ├── lancamentos/              # Componentes de lançamentos
│   │   ├── dialogs/             # Diálogos (criar, editar, detalhes)
│   │   ├── table/               # Tabela com filtros avançados
│   │   ├── shared/              # Componentes compartilhados
│   │   └── page/                # Página completa
│   ├── dashboard/                # Widgets do dashboard (20+ widgets)
│   │   ├── accounts-summary.tsx
│   │   ├── income-expense-chart.tsx
│   │   ├── category-breakdown.tsx
│   │   └── ...
│   ├── cartoes/                  # Componentes de cartões
│   ├── contas/                   # Componentes de contas
│   ├── categorias/               # Componentes de categorias
│   ├── pagadores/                # Componentes de pagadores
│   ├── orcamentos/               # Componentes de orçamentos
│   ├── anotacoes/                # Componentes de anotações
│   ├── insights/                 # Componentes de insights IA
│   ├── relatorios/               # Componentes de relatórios
│   ├── calendario/               # Componentes de calendário
│   ├── calculadora/              # Calculadora integrada
│   ├── sidebar/                  # Sidebar de navegação
│   ├── skeletons/                # Estados de loading
│   └── month-picker/             # Seletor de mês/período
│
├── lib/                          # Lógica de negócio e utilitários
│   ├── auth/
│   │   ├── config.ts            # Configuração Better Auth
│   │   ├── server.ts            # Auth helpers (servidor)
│   │   └── client.ts            # Auth client
│   ├── db.ts                    # Conexão Drizzle ORM
│   ├── dashboard/               # Fetchers do dashboard
│   │   ├── fetch-dashboard-data.ts  # Fetcher principal (18+ queries paralelas)
│   │   ├── accounts.ts
│   │   ├── metrics.ts
│   │   └── ... (15+ fetchers especializados)
│   ├── lancamentos/             # Lógica de lançamentos
│   │   ├── constants.ts
│   │   ├── form-helpers.ts
│   │   ├── categoria-helpers.ts
│   │   └── formatting-helpers.ts
│   ├── actions/                 # Helpers de Server Actions
│   │   ├── helpers.ts           # Error handling, revalidation
│   │   └── types.ts             # ActionResult types
│   ├── schemas/                 # Zod validation schemas
│   ├── utils/                   # Utilitários gerais
│   │   ├── currency.ts          # Formatação de moeda
│   │   ├── date.ts              # Manipulação de datas
│   │   ├── period/              # Utilitários de período (YYYY-MM)
│   │   └── calculator.ts        # Lógica da calculadora
│   └── ...                      # Outros helpers
│
├── db/                           # Banco de dados
│   └── schema.ts                # Schema Drizzle (736 linhas)
│                                 # 15+ tabelas com relações complexas
│
├── drizzle/                      # Migrations geradas
│   ├── migrations/
│   └── meta/
│
├── hooks/                        # React Hooks customizados
│   ├── use-month-period.ts      # Gerenciamento de período
│   ├── use-form-state.ts        # Estado de formulários
│   ├── use-calculator-state.ts  # Estado da calculadora
│   └── use-mobile.ts            # Detecção mobile
│
├── public/                       # Assets estáticos
│   ├── logos/                   # Logos de bancos
│   ├── bandeiras/               # Bandeiras de cartões
│   ├── icones/                  # Ícones de categorias
│   ├── avatares/                # Avatares de usuários
│   ├── providers/               # Logos de providers
│   └── fonts/                   # Fontes customizadas
│
├── scripts/                      # Scripts utilitários
│   ├── setup-env.sh             # Setup de variáveis de ambiente
│   └── postgres/
│       ├── init.sql             # Script de inicialização do PostgreSQL
│       └── enable-extensions.ts # Habilita extensões do PostgreSQL
│
├── Dockerfile                    # Multi-stage build otimizado
├── docker-compose.yml            # Orquestração Docker
├── next.config.ts                # Configuração Next.js
├── drizzle.config.ts             # Configuração Drizzle ORM
├── tailwind.config.ts            # Configuração Tailwind CSS
├── postcss.config.mjs            # PostCSS config
├── components.json               # shadcn/ui config
├── eslint.config.mjs             # ESLint config
├── tsconfig.json                 # TypeScript config
├── package.json                  # Dependências e scripts
├── .env.example                  # Template de variáveis de ambiente
├── CLAUDE.md                     # Guia completo para IA
└── README.md                     # Este arquivo

Principais Diretórios

Diretório	Descrição	Arquivos
app/(dashboard)/	Páginas protegidas da aplicação	~50
components/	Componentes React reutilizáveis	~200
lib/	Lógica de negócio, helpers e utilitários	~80
db/	Schema do banco de dados	1
hooks/	React hooks customizados	~10
public/	Assets estáticos (imagens, ícones, logos)	~100
scripts/	Scripts de automação	~5

Estrutura do Banco de Dados

O OpenSheets possui um schema robusto com 15+ tabelas e relações complexas:

┌─────────────────────────────────────────────────────────────────┐
│                    TABELAS PRINCIPAIS                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  user                      user_preferences                      │
│  ├── id                   ├── id                                │
│  ├── name                 ├── user_id → user.id                 │
│  ├── email                ├── disable_magnetlines                │
│  └── ...                  └── ...                                │
│                                                                  │
│  contas                    cartoes                              │
│  ├── id                   ├── id                                │
│  ├── user_id → user.id    ├── user_id → user.id                 │
│  ├── nome                 ├── conta_id → contas.id              │
│  ├── tipo_conta           ├── nome                              │
│  ├── saldo_inicial        ├── bandeira                          │
│  └── ...                  ├── dt_fechamento                     │
│                           ├── dt_vencimento                      │
│                           └── ...                                │
│                                                                  │
│  categorias                pagadores                            │
│  ├── id                   ├── id                                │
│  ├── user_id → user.id    ├── user_id → user.id                 │
│  ├── nome                 ├── nome                              │
│  ├── tipo                 ├── email                             │
│  ├── icone                ├── share_code (único)                │
│  └── ...                  ├── role                              │
│                           └── ...                                │
│                                                                  │
│  pagador_shares                                                 │
│  ├── id                                                         │
│  ├── pagador_id → pagadores.id                                  │
│  ├── shared_with_user_id → user.id                             │
│  ├── created_by_user_id → user.id                              │
│  ├── permission (read/write)                                    │
│  └── ...                                                         │
│                                                                  │
│  lancamentos (TABELA PRINCIPAL)                                │
│  ├── id                                                         │
│  ├── user_id → user.id                                          │
│  ├── conta_id → contas.id                                       │
│  ├── cartao_id → cartoes.id                                     │
│  ├── categoria_id → categorias.id                              │
│  ├── pagador_id → pagadores.id                                  │
│  ├── nome                                                        │
│  ├── valor                                                       │
│  ├── tipo_transacao (receita/despesa/transferencia)            │
│  ├── forma_pagamento                                            │
│  ├── condicao (aberto/realizado/cancelado)                     │
│  ├── data_compra                                                │
│  ├── periodo (YYYY-MM)                                          │
│  ├── qtde_parcela                                               │
│  ├── parcela_atual                                              │
│  ├── series_id (agrupa parcelas)                               │
│  ├── transfer_id (agrupa transferências)                       │
│  ├── antecipado (boolean)                                       │
│  ├── antecipacao_id → installment_anticipations.id            │
│  └── ...                                                         │
│                                                                  │
│  installment_anticipations                                      │
│  ├── id                                                         │
│  ├── user_id → user.id                                          │
│  ├── series_id                                                  │
│  ├── lancamento_id → lancamentos.id                            │
│  ├── periodo_antecipacao                                        │
│  ├── parcelas_antecipadas (JSONB array)                        │
│  ├── valor_total                                                │
│  ├── desconto                                                   │
│  └── ...                                                         │
│                                                                  │
│  faturas                   orcamentos                           │
│  ├── id                   ├── id                                │
│  ├── user_id → user.id    ├── user_id → user.id                 │
│  ├── cartao_id → cartoes  ├── categoria_id → categorias.id      │
│  ├── periodo              ├── valor                             │
│  ├── status_pagamento     ├── periodo                           │
│  └── ...                  └── ...                                │
│                                                                  │
│  anotacoes                 saved_insights                       │
│  ├── id                   ├── id                                │
│  ├── user_id → user.id    ├── user_id → user.id                 │
│  ├── titulo               ├── period                            │
│  ├── descricao            ├── model_id                          │
│  ├── tipo (nota/tarefa)   ├── data (JSON)                       │
│  ├── tasks (JSON)         ├── created_at                        │
│  ├── arquivada            └── updated_at                        │
│  └── ...                                                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

ÍNDICES OTIMIZADOS:
• user_id + period (queries do dashboard)
• user_id + purchase_date (ordenação por data)
• series_id (agrupamento de parcelas)
• cartao_id + period (faturas)
• user_id + condition (filtros de condição)
• share_code (compartilhamento)

Fluxo de Autenticação

1. Usuário acessa rota protegida
   ↓
2. middleware.ts verifica sessão (Better Auth)
   ↓
3. Se não autenticado → redirect /login
   ↓
4. Usuário faz login (OAuth Google ou email/senha)
   ↓
5. Better Auth valida credenciais e cria sessão
   ↓
6. Cookie de sessão é salvo no navegador
   ↓
7. Inicialização automática de dados do usuário:
   - Categorias padrão criadas
   - Preferências inicializadas
   ↓
8. Usuário acessa dashboard ✅

Fluxo de Dados (Dashboard)

1. Usuário acessa /dashboard
   ↓
2. Server Component busca userId da sessão
   ↓
3. fetchDashboardData() executa 18+ queries em paralelo:
   - Métricas (receitas, despesas, saldo)
   - Contas e seus saldos
   - Cartões e faturas
   - Lançamentos recentes
   - Gráficos de categorias
   - Parcelas em aberto
   - Orçamentos vs. realizado
   - ... e mais 10+ datasets
   ↓
4. Dados retornados em ~200-500ms (otimizado)
   ↓
5. Server Component renderiza com dados
   ↓
6. Client Components hidratam com interatividade
   ↓
7. Dashboard totalmente funcional ✅

Fluxo de Build (Docker)

1. Stage deps: Instala dependências
   ↓
2. Stage builder: Builda Next.js (standalone)
   ↓
3. Stage runner: Copia apenas build + deps prod
   ↓
4. Container final: ~200MB (otimizado)

---

🆕 Destaques e Funcionalidades Recentes

O OpenSheets está em desenvolvimento ativo. Aqui estão algumas das funcionalidades mais interessantes já implementadas:

💸 Sistema Avançado de Parcelamentos

O controle de parcelamentos vai além do básico:

• Séries de parcelas: Agrupa todas as parcelas de uma compra
• Antecipação inteligente: Antecipe parcelas com cálculo automático de desconto
• Análise consolidada: Veja todas as parcelas em aberto e o impacto nos próximos meses
• Rastreamento completo: Histórico de todas as operações de antecipação

🤖 Insights Financeiros com IA

Integração robusta com múltiplos providers de IA:

• Multi-provider: Escolha entre Claude, GPT, Gemini ou OpenRouter
• Análises personalizadas: IA analisa seus padrões de gastos e sugere melhorias
• Histórico persistente: Insights salvos por período para acompanhamento
• Contextual: A IA tem acesso aos seus dados financeiros para análises precisas

👥 Colaboração e Compartilhamento

Sistema completo para gestão colaborativa de finanças:

• Pagadores compartilhados: Compartilhe acesso a pagadores específicos
• Permissões granulares: Defina quem pode visualizar ou editar
• Códigos únicos: Cada pagador tem um código de compartilhamento exclusivo
• Notificações automáticas: E-mails enviados automaticamente via Resend
• Multi-usuário seguro: Isolamento completo de dados entre usuários

📊 Relatórios Detalhados

Analytics poderosos para entender suas finanças:

• Dashboard interativo: 20+ widgets com diferentes visualizações
• Relatórios de categorias: Análise profunda por categoria com histórico
• Comparativos mensais: Veja a evolução dos seus gastos ao longo do tempo
• Exportações: PDF e Excel para análise externa
• Gráficos interativos: Recharts com dados em tempo real

📝 Produtividade Integrada

Ferramentas para manter tudo organizado:

• Anotações: Notas de texto para lembretes e planejamentos
• Tarefas: Listas com checkboxes para acompanhamento
• Arquivamento: Mantenha o histórico sem poluir a interface
• Calendário: Visualize todos os lançamentos em um calendário mensal
• Calculadora: Calculadora integrada para planejamento rápido

🎨 Experiência do Usuário

Atenção aos detalhes que fazem diferença:

• Modo privacidade: Oculte valores sensíveis com um clique
• Tema adaptável: Dark/light mode com persistência
• Preferências: Customize o comportamento da aplicação
• Importação em massa: Cole múltiplos lançamentos de uma vez
• Responsivo: Funciona perfeitamente em desktop e mobile

🔒 Segurança e Performance

Construído com as melhores práticas:

• Isolamento de dados: Cada usuário vê apenas seus próprios dados
• Índices otimizados: Queries rápidas mesmo com milhares de registros
• Server Actions: Mutações seguras no servidor
• Type-safety: TypeScript strict em toda a codebase
• Validação robusta: Zod schemas para todos os inputs

📦 Developer Experience

Feito por desenvolvedores, para desenvolvedores:

• Hot reload instantâneo: Turbopack para desenvolvimento rápido
• Type inference: Drizzle ORM com tipos automáticos
• Migrations automáticas: Schema sync simplificado
• Docker completo: Ambiente reproduzível em qualquer lugar
• Scripts facilitados: Comandos npm para tudo

---

🤝 Contribuindo

Contribuições são muito bem-vindas!

Como contribuir

1. Fork o projeto
2. Clone seu fork

   git clone https://github.com/seu-usuario/opensheets-app.git
   

3. Crie uma branch para sua feature

   git checkout -b feature/minha-feature
   

4. Commit suas mudanças

   git commit -m 'feat: adiciona minha feature'
   

5. Push para a branch

   git push origin feature/minha-feature
   

6. Abra um Pull Request

Padrões

• Use TypeScript
• Documente features novas
• Use commits semânticos (feat, fix, docs, etc)

---

💖 Apoie o Projeto

Se o Opensheets está sendo útil para você e você quer apoiar o desenvolvimento contínuo do projeto, considere se tornar um sponsor!

Por que apoiar?

• 🚀 Desenvolvimento contínuo - Novas features e melhorias regulares
• 🐛 Correções de bugs - Manutenção ativa e suporte
• 📚 Documentação - Guias e tutoriais detalhados
• 💡 Novas ideias - Implementação de sugestões da comunidade

Outras formas de contribuir

Além do suporte financeiro, você pode contribuir:

• ⭐ Dando uma estrela no repositório
• 🐛 Reportando bugs e sugerindo melhorias
• 📖 Melhorando a documentação
• 💻 Submetendo pull requests
• 💬 Compartilhando o projeto com outras pessoas

---

📄 Licença

Este projeto está licenciado sob a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).

✅ Você PODE:

• Usar o projeto para fins pessoais
• Modificar o código-fonte
• Distribuir e compartilhar o projeto
• Fazer fork e criar versões modificadas

❌ Você NÃO PODE:

• Uso comercial - Ganhar dinheiro com o projeto (vender, SaaS, consultoria baseada nele)
• Remover créditos - Você deve manter a atribuição ao autor original
• Mudar a licença - Suas modificações devem usar a mesma licença

📋 Requisitos:

• Dar crédito ao autor original (Felipe Coutinho)
• Indicar se modificações foram feitas
• Distribuir sob a mesma licença (CC BY-NC-SA 4.0)

Resumo: Use livremente para projetos pessoais, contribua, modifique - mas não ganhe dinheiro com isso.

Para o texto legal completo, consulte o arquivo LICENSE ou visite creativecommons.org.

---

🙏 Agradecimentos

• Next.js
• Better Auth
• Drizzle ORM
• shadcn/ui
• Vercel

---

📞 Contato

Desenvolvido por: Felipe Coutinho GitHub: @felipegcoutinho Repositório: opensheets

---

⭐ Se este projeto foi útil pra você:

• Dê uma estrela no repositório
• Apoie o projeto como sponsor
• Compartilhe com outras pessoas

Desenvolvido com ❤️ para a comunidade open source