Klipper — Wealth Operating System
Sistema pessoal de gestão financeira e patrimonial. Matemática ancora. Narrativa sem
evidência não altera decisão. Código sem teste não entra.
Stack: Nuxt 3.21 (Vue 3, SPA/PWA) · Rails 8 (PostgreSQL, JWT) · Vercel · Render · Neon
Produção: https://klipper.quebec.com.br · Repo: https://github.com/Borussia80/Klipper
Monorepo
apps/
klipper-web/ ← Nuxt 3.21 — frontend (dashboard, transações, orçamento, investimentos, import)
klipper-api/ ← Rails 8 — backend (API JSON, JWT, PostgreSQL)
quebec-web/ ← Nuxt 3.21 — landing page institucional
Cada app tem seu próprio package.json/Gemfile e roda independente.
Executar localmente
Opção 1 — cada app na mão (dia a dia de desenvolvimento)
# Backend — requer o Postgres local no ar.
# O daemon do Docker está desabilitado nesta máquina; o banco roda em Podman:
podman start klipper-pg-test # ou, se não existir:
# podman run -d --name klipper-pg-test -p 5432:5432 \
# -e POSTGRES_PASSWORD=postgres postgres:16
cd apps/klipper-api
bin/rails db:prepare
bin/rails server -p 3001
# Frontend, em outro terminal
cd apps/klipper-web
npm install
npm run dev # http://localhost:3000
Opção 2 — stack completa via Docker Compose (perfil "local pessoal")
Sobe Postgres + API + Web + proxy Caddy isolados na rede Docker, só acessível em
127.0.0.1:8080 — pensado pra guardar dado financeiro real localmente, sem expor
serviço nenhum além do proxy.
Esta opção depende de um daemon Docker funcionando, que não é o caso da máquina
de desenvolvimento atual (ver Opção 1). Rodar com podman-compose é plausível mas
não foi testado — trate o comando abaixo como não verificado.
cp .env.local.example .env.local # preencher POSTGRES_PASSWORD e RAILS_MASTER_KEY
docker compose --env-file .env.local -f docker-compose.local.yml up -d --build
Testes
# Backend (RSpec)
cd apps/klipper-api
TEST_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/klipper_test" \
bundle exec rspec --format documentation
# Frontend (Vitest)
cd apps/klipper-web
npm run test
TDD é obrigação técnica neste repo — ver CLAUDE-process.md (ciclo Red → Green →
Refactor, F.I.R.S.T., SRP). Código sem teste correspondente não entra.
CI/CD
GitHub Actions (.github/workflows/ci.yml) roda em todo push/PR: Brakeman + Bundler
Audit (segurança Ruby) → RuboCop (lint) → RSpec (backend). Deploy é automático a partir
de merge em main:
- Frontend (
klipper-web, quebec-web) → Vercel, target: production
- Backend (
klipper-api) → Render (apps/klipper-api/render.yaml), Postgres em Neon
klipper-api está no plano Free do Render — a primeira requisição após um período de
inatividade sofre cold start (~30s). Migrations rodam via bin/docker-entrypoint a cada
boot do container, não via render.yaml/preDeployCommand (o Render Free ignora esse
hook — só roda em planos pagos).
Documentação
| O quê | Onde |
|---|
| Contexto de sessão / arquitetura | CLAUDE.md |
| Processo de desenvolvimento (TDD, F.I.R.S.T., SRP) | CLAUDE-process.md |
| Roadmap de produto + backlog de segurança | ROADMAP_KLIPPER_WEALTH_OS.md |
| Plano de execução da auditoria de 14/09/2026 | PLANO_EXECUCAO_KLIPPER_2026-09-14.md |
| Feature Kakebo — especificação do ciclo mensal | docs/KAKEBO.md |
| Auditorias de segurança | docs/security/ |
| ADRs | docs/adrs/ |
| Runbook de erros de operação/deploy | docs/operations/matriz-erros.md |
Regra de ouro
Matemática ancora. Narrativa sem evidência não altera decisão. Código sem teste não
entra. Não existe "adicionar teste depois".
