Household Budget — AI-Assisted Family Finance Tracker
A full-stack household budget app with a single ledger, offline-first design, and an AI assistant wired into real household data.
- 731
- Budget cells migrated
- 61
- Real categories imported
- 0
- npm vulnerabilities found
The challenge
For three years, Saad managed his household budget through an increasingly unwieldy Excel spreadsheet: nested formulas, one tab per year, no mobile-friendly view, and no reliable way to track two separate savings pools without copy-paste errors creeping in. There was no way to log an expense offline, see budget-versus-actual variance per category at a glance, or ask a simple question about the household's own finances without reopening the file. The real challenge wasn't just rebuilding the spreadsheet as a web app — it was migrating three years of real history without losing anything or letting balances drift out of sync.
The solution
Saad built a household budget app around one core principle: a single transaction ledger is the source of truth, with every balance shown anywhere in the app recomputed live rather than stored separately. The app covers:
- expense/income logging in about 3 seconds, working fully offline;
- a year-overview budget grid with 4 view modes (blended, estimate, actual, variance);
- two named savings pools ("normal" and "urgent") computed automatically;
- a savings-goals wishlist with an "affordable now" indicator;
- a subscriptions module and a loans module;
- native support for a daret (Moroccan rotating savings circle) as a ledger category;
- an AI assistant (Gemini) answering from the household's own real data.
The results
The migration successfully imported 61 real categories, 731 budget cells (2023-2025 locked as historical record, 2026 left editable), 17 savings goals and 8 subscriptions from the old spreadsheet, with no balance drift between the historical record and the new unified ledger. A dated internal security review found and fixed two genuine vulnerabilities: a cross-household data-isolation gap via an unvalidated foreign key, and a refresh token with no revocation path, replaced by a dedicated table with rotation and reuse detection. An npm dependency audit of the backend found zero vulnerabilities, confirming a foundation built for real household use.
Methodology and project management
The project was built in an intensive two-week sprint (late June to early July 2026, 18 commits), working from the real existing data rather than placeholder fixtures from day one. Schema migrations are written as plain hand-written SQL rather than Knex's own JS migrations, a deliberate choice to keep explicit control over every structural change. The import script was purpose-built and tested to absorb the real Excel history without loss. Once the feature set was in place, a dedicated security review closed out the cycle before anything went further, rather than being treated as an afterthought.
Technical architecture and performance
The backend runs on Node.js/Express with MySQL 8 and Knex as the query builder, with JWT authentication (access + refresh) via Passport stored in HttpOnly cookies rather than localStorage. The frontend is Angular 19 with Tailwind/DaisyUI, built as an installable Progressive Web App with a service worker and an IndexedDB offline write-queue that syncs once back online. Capacitor wraps the same web app into an installable Android app with biometric unlock, loading the live hosted web app at runtime — so every web deploy instantly updates the installed Android app too, with no separate build step.