The Problem
Personal finance tracking typically means either manual spreadsheet entry or handing bank data to a third-party service. Compasso sits between those: it parses bank PDF statements locally, keeps all data in a local SQLite database, and provides a multi-user web dashboard for categorization and reporting. The privacy-first angle is the core differentiator—no cloud sync, no external data processing.
What This Does
Compasso is a full-stack TypeScript monorepo with three packages: apps/web (React + Vite + Tailwind), apps/api (Express + better-sqlite3), and packages/shared (shared types and constants). The API exposes routes for auth, workspaces, transactions, categories, recurring detection, reports, and backup/restore—all under apps/api/src/routes/. PDF parsing lives in apps/api/src/parsers/ with bank-specific implementations for Novo Banco (cgd.ts) and CGD (novo-banco.ts), plus a registry pattern for adding more banks.
The categorization engine (apps/api/src/services/categoryMatcher.ts) uses user-defined patterns to suggest categories, and recategorizer.ts re-applies rules when categories change. The frontend provides pages for dashboard, transactions, reports, recurring items, and workspace management, with i18n support for English and Portuguese (apps/web/src/i18n/locales/).
How To Use It
Setup: Requires Node.js 18+ and npm 9+. Install with npm install, then build the shared package with npm run build -w @compasso/shared.
Configuration: Copy .env.example to .env in the project root. Required variables: PORT, HOST, NODEENV, and ALLOWEDORIGINS. Optional: DATABASEPATH (defaults to ./data), RESENDAPIKEY and EMAILFROM for password reset emails via Resend.
Running it: npm run dev starts both frontend (port 5180) and backend (port 5181). For production, npm run build then use Docker Compose:
npm install npm run build -w @compasso/shared npm run dev or for production: docker compose up -d --build
Real-World Use
A small team or household can run this on a home server or NAS. Users register, create workspaces, invite others with role-based access (owner/editor/viewer), and upload monthly bank PDFs. The system parses transactions, suggests categories based on user-defined patterns, and generates monthly/annual reports with charts. The backup/restore feature (apps/api/src/routes/backup.ts) allows exporting workspace data as a portable file.
Code Health & Issues
Med - No rate limiting on auth endpoints: rateLimiter.ts exists but isn't referenced in auth.ts routes, leaving login/register vulnerable to brute force. Med - Email service is a hard dependency for password reset: emailService.ts will fail silently if RESENDAPIKEY isn't set, and the README acknowledges this but doesn't provide a fallback. Low - No frontend tests: All 35 test files are API-side (vitest). The React frontend has no test coverage, which is a gap for a UI-heavy app. Low - Upload directory is gitignored but .gitkeep exists: apps/api/uploads/.gitkeep suggests uploads are expected there, but the path isn't configurable via env vars. Good signs: CI workflow exists (.github/workflows/ci.yml), structured error handling (errors.ts), schema validation (apps/api/src/schemas/), and a license file are all present.
The Bottom Line
Compasso is a well-structured, genuinely useful personal finance tool with a clear privacy-first stance. The bank-specific PDF parsers and pattern-based categorization are the standout features. It's better suited to a technically comfortable individual or small team than a non-technical user—the setup requires Node.js and environment configuration. The lack of frontend tests and the unguarded auth endpoints are the main concerns before production use.