Openmonetis

<p align="center"> <img src="./public/images/logo_small.png" alt="OpenMonetis Logo" height="80" /> </p> <p align="center"> Projeto pessoal de gestão financeira. Self-hosted, manual e open source. </p>

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

---

<p align="center"> <img src="./public/images/dashboard-preview-light.webp" alt="Dashboard Preview" width="800" /> </p>

---

📖 Índice

• Sobre o Projeto
• Instalação via Script
• Início Rápido (manual)
• Scripts Disponíveis
• Docker
• Storage S3 Compatível
• Variáveis de Ambiente
• Arquitetura
• Contribuindo
• Apoie o Projeto
• Licença

---

🎯 Sobre o Projeto

OpenMonetis é 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.

💡 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.

2. Não há Open Finance — Não há conexão automática com bancos. Você pode registrar transações manualmente ou importar extratos nos formatos OFX e XLS/XLSX.

3. Requer disciplina — O OpenMonetis funciona melhor para quem tem disciplina de registrar os gastos regularmente, quer controle total sobre seus dados e gosta de entender exatamente onde o dinheiro está indo.

Funcionalidades

💰 Contas e transações — Contas bancárias, cartões, dinheiro. Receitas, despesas e transferências. Categorização, extratos detalhados e importação de extratos OFX e XLS/XLSX com detecção automática de categoria.

📊 Dashboard e relatórios — Widgets interativos de métricas, gráficos de evolução, comparativos por categoria, tendências, uso de cartões, top estabelecimentos. Exportação em PDF e Excel.

💳 Faturas de cartão — Acompanhe faturas por período, controle limites e vencimentos.

🎯 Orçamentos — Defina limites por categoria e acompanhe o progresso.

💸 Parcelamentos avançados — Séries de parcelas, antecipação com cálculo de desconto, análise consolidada.

🤖 Insights com IA — Análises geradas por Claude, GPT, Gemini ou OpenRouter. Insights personalizados e histórico salvo.

👥 Gestão colaborativa — Pagadores com permissões (admin/viewer), notificações automáticas por e-mail, códigos de compartilhamento.

📝 Anotações e tarefas — Notas de texto, listas com checkboxes, sistema de arquivamento.

📅 Calendário financeiro — Visualize todos os lançamentos em um calendário mensal.

📲 OpenMonetis Companion — App Android que captura notificações bancárias (Nubank, Itaú, Bradesco, Inter, C6 e outros) e envia como pré-lançamentos para revisão. Repositório.

⚙️ Personalização — Tema dark/light e modo privacidade.

Stack técnica

• Next.js (App Router, Turbopack) + React + TypeScript
• PostgreSQL + Drizzle ORM
• Better Auth (email/senha, OAuth, Passkeys/WebAuthn)
• shadcn/ui (Radix UI) + Tailwind CSS
• Docker (multi-stage build)
• Biome (linting + formatting)
• Vercel AI SDK (Claude, GPT, Gemini, OpenRouter)

---

⚡ Instalação via Script

A forma mais rápida de instalar. O script verifica dependências, configura o .env interativamente e sobe o banco automaticamente.

Pré-requisito: Node.js 22+

# Mac / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/setup.mjs -o setup.mjs && node setup.mjs

# Windows (PowerShell)
curl -o setup.mjs https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/setup.mjs ; node setup.mjs

O script irá:

• Verificar Node, pnpm, Git e Docker
• Perguntar se quer banco local (Docker) ou remoto (Supabase, Neon, etc.)
• Gerar o BETTER_AUTH_SECRET automaticamente
• Configurar opcionais: Google OAuth, e-mail, IA, domínio público
• Clonar o repositório, instalar dependências e aplicar o schema

---

🚀 Início Rápido (manual)

Pré-requisitos

• Node.js 22+ e pnpm
• Docker e Docker Compose

Passo a Passo

1. Clone e instale

   git clone https://github.com/felipegcoutinho/openmonetis.git
   cd openmonetis
   pnpm install
   

2. Configure o .env

   cp .env.example .env
   

   Edite o .env com suas credenciais. O principal é o DATABASE_URL e o BETTER_AUTH_SECRET:

   # Banco local (Docker): use host "localhost"
   DATABASE_URL=postgresql://openmonetis:openmonetis_dev_password@localhost:5432/openmonetis_db
   
   # Banco remoto (Supabase, Neon, etc): use a URL completa do provider
   # DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require
   
   BETTER_AUTH_SECRET=seu-secret-aqui  # gere com: openssl rand -base64 32
   BETTER_AUTH_URL=http://localhost:3000
   

3. Suba o banco de dados (pule se estiver usando banco remoto)

   docker compose up db -d
   pnpm db:extensions
   

4. Execute as migrations e inicie

   pnpm db:push
   pnpm dev
   

5. Acesse http://localhost:3000

Docker completo (app + banco em containers): use pnpm docker:up ao invés dos passos 3-4.

---

📜 Scripts Disponíveis

Desenvolvimento

pnpm dev              # Dev server (Turbopack)
pnpm build            # Build de produção
pnpm start            # Servidor de produção
pnpm lint             # Biome check
pnpm lint:fix         # Biome auto-fix

Banco de Dados

pnpm db:generate      # Gerar migrations
pnpm db:migrate       # Executar migrations
pnpm db:push          # Push schema direto (dev)
pnpm db:studio        # Drizzle Studio (UI visual)

Utilitários

pnpm backup           # Backup do banco (requer scripts/backup.sh configurado)

Docker

pnpm docker:up        # Subir app + banco
pnpm docker:up:d      # Subir em background
pnpm docker:up:db     # Subir apenas o banco
pnpm docker:down      # Parar containers
pnpm docker:down:volumes  # Parar e remover volumes (⚠️ apaga dados!)
pnpm docker:logs      # Logs em tempo real
pnpm docker:restart   # Reiniciar
pnpm docker:rebuild   # Rebuild completo

---

🐳 Docker

O Dockerfile usa multi-stage build (deps → builder → runner) com imagem final ~200MB rodando como usuário não-root.

Health checks configurados para ambos os serviços (PostgreSQL via pg_isready, app via GET /api/health).

Comandos úteis

docker compose exec app sh                                      # Shell da aplicação
docker compose exec db psql -U openmonetis -d openmonetis_db    # Shell do banco
docker compose ps                                                # Status
docker compose exec db pg_dump -U openmonetis openmonetis_db > backup.sql  # Backup
docker compose exec -T db psql -U openmonetis -d openmonetis_db < backup.sql  # Restore

Customizando Portas

APP_PORT=3001   # Padrão: 3000
DB_PORT=5433    # Padrão: 5432

---

☁️ Storage S3 Compatível

O suporte a anexos de lançamentos usa upload direto com URL pré-assinada. Essa configuração é opcional, mas passa a ser necessária se você quiser habilitar anexos no app.

Variáveis

S3_ENDPOINT=
S3_REGION=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_BUCKET=

Compatibilidade

• O código atual espera um provider com API compatível com S3 e suporte a PutObject, GetObject, HeadObject, DeleteObject e URLs pré-assinadas.
• A implementação usa endpoint customizado e forcePathStyle: true em src/shared/lib/storage/s3-client.ts.
• Em geral isso cobre MinIO, Cloudflare R2, Backblaze B2 S3-Compatible, DigitalOcean Spaces e AWS S3. Mas foi testado apenas no Supabase Storage.
• Se o seu provider exigir virtual-hosted-style em vez de path-style, você vai precisar ajustar essa configuração antes de usar anexos.
• Se as variáveis de S3 não forem configuradas, mantenha os anexos desabilitados no seu fluxo de uso.

---

🔐 Variáveis de Ambiente

Copie .env.example para .env e configure:

Obrigatórias

DATABASE_URL=postgresql://openmonetis:openmonetis_dev_password@localhost:5432/openmonetis_db
BETTER_AUTH_SECRET=seu-secret-aqui    # openssl rand -base64 32
BETT