A Local-First Progressive Web Application for personal finance management with offline-first architecture and strict double-entry accounting.
This wallet application implements a comprehensive personal finance system that:
- Works Offline: All data stored locally in IndexedDB, fully functional without internet
- Maintains Accounting Integrity: Strict double-entry bookkeeping with balanced debits and credits
- Handles Multiple Currencies: Triple truth system (Display, Account, Budget) with frozen exchange rates
- Syncs Optionally: BYOB (Bring Your Own Backend) - sync to your own Firestore instance when needed
- Resolves Conflicts Automatically: Last-Write-Wins (LWW) strategy for seamless multi-device usage
- All data stored in browser's IndexedDB for instant access
- Full functionality offline - no internet required for day-to-day use
- Optional synchronization to user's personal Firestore instance
- Every transaction maintains balanced debits and credits
- Preserves the accounting equation:
Assets = Liabilities + Equity - Editable entries with direct corrections or reversing entries
- Display Currency: What you see in the UI (configurable)
- Account Currency: Native currency of each account
- Budget Currency: Your home currency for budgeting
- Exchange rates frozen at transaction time for historical accuracy
- Last-Write-Wins (LWW) conflict resolution
- Atomic sync for transaction groups (all ledger entries together)
- Uses
_lww_timestamp,_device_id,_versionfor conflict detection
- Framework: Nuxt 4.3 with PWA support
- UI Components: shadcn-vue
- Storage: IndexedDB (via Dexie.js)
- Sync: Firebase JS SDK (optional, user-configured)
- Math: decimal.js (avoids floating point errors)
wallet/
├── .github/
│ └── copilot-instructions.md # GitHub Copilot instructions
├── docs/
│ ├── implementation/ # Implementation documentation
│ │ ├── database-schema.md # Complete data models and schemas
│ │ └── plan.md # Phased development roadmap
│ ├── deployment-guide.md # Deployment guide
│ └── user-guide.md # User guide
└── README.md # This file
- GitHub Copilot Instructions - Essential project overview and development guidelines
- Database Schema - Complete data models, IndexedDB and Firestore schemas
- Implementation Plan - Phased development roadmap and technical details
- Local-First: App must work fully offline with optional sync
- Double-Entry: All transactions balanced, maintaining accounting integrity
- Denormalized Ledger: Self-contained entries for efficient offline queries
- UUID-Based: Conflict-free ID generation for distributed systems
- Frozen Exchange Rates: Historical accuracy without data corruption
Overall Progress: 92% Complete
Phase 1 Complete: Core Data Layer ✅
Phase 2 Complete: Accounting Engine ✅
Phase 3 Complete: PWA Foundation ✅
Phase 4 Complete: Sync Implementation ✅
Phase 5 Complete: User Interface ✅
Phase 6 Nearly Complete: Testing & Optimization ✅ (92% complete)
- Code Base: ~10,370 lines of TypeScript/Vue
- Test Coverage: 106 unit tests (79.1% statements, 94.2% branches) + 47 active E2E tests
- Build Size: 404 KB gzipped (1.68 MB uncompressed)
- Dependencies: 5 production, 16 dev (zero critical vulnerabilities)
- Pages: 6 complete UI pages with full functionality
- Performance: Lazy loading for Firebase SDK, virtual scrolling for large lists
The core data layer has been implemented with:
- ✅ Nuxt 4.3 project setup with TypeScript
- ✅ ESLint and Vitest configuration
- ✅ Database schema with Dexie.js
- ✅ CRUD operations for all entities
- ✅ Double-entry validation
- ✅ Unit tests with 79.1% statement coverage, 94.2% branch coverage
The accounting engine has been implemented with:
- ✅ High-level transaction API (income, expense, transfer, multi-split)
- ✅ Balance calculation engine (point-in-time, history, net worth)
- ✅ Multi-currency conversion and formatting
- ✅ Currency utilities (34 currencies including PEN, parsing, formatting)
- ✅ Comprehensive unit tests
The PWA capabilities have been implemented with:
- ✅ Service worker with Workbox (auto-update, offline caching)
- ✅ PWA manifest (installable app)
- ✅ Network status detection (online/offline indicators)
- ✅ Update notifications and install prompts
- ✅ App icons and visual assets
- ✅ Production build optimized for offline use
The synchronization engine has been implemented with:
- ✅ Firebase SDK integration (BYOB - Bring Your Own Backend)
- ✅ Last-Write-Wins conflict resolution
- ✅ Bidirectional sync (upload and download)
- ✅ Device tracking with persistent device IDs
- ✅ Sync status UI with real-time indicators
- ✅ Firebase configuration page
- ✅ Firestore security rules documentation
The complete user interface has been delivered with:
- ✅ 6 pages: Home, Accounts, Transactions, Budgets, Reports, Settings
- ✅ Transaction forms (Expense, Income, Transfer modals)
- ✅ Account management with balance display
- ✅ Budget tracking with spending totals
- ✅ Financial reports (Net Worth, Income vs Expenses)
- ✅ Responsive navigation and mobile-first design
The testing and optimization phase is nearly complete (92% complete):
- ✅ Playwright E2E testing infrastructure
- ✅ 47 active E2E tests across 9 test suites (3 skipped - service worker testing)
- ✅ Automated accessibility testing (WCAG 2.1 AA)
- ✅ Performance benchmarking tests
- ✅ CI/CD integration for E2E tests
- ✅ Security audit and vulnerability fixes
- ✅ Additional E2E test scenarios (budgets, reports, multi-currency)
- ✅ User documentation (comprehensive user guide)
- ✅ Deployment documentation
- ✅ Firebase lazy loading optimization (reduces initial bundle)
- ✅ Virtual scrolling for large transaction lists (1000+ items)
- ⏳ Extended browser testing (Safari, Firefox, Edge)
- ⏳ Performance monitoring integration (Lighthouse CI)
See DEVELOPMENT.md for development guide, PHASE1_SUMMARY.md for Phase 1 details, PHASE2_SUMMARY.md for Phase 2 details, PHASE3_SUMMARY.md for Phase 3 details, PHASE4_SUMMARY.md for Phase 4 details, PHASE5_SUMMARY.md for Phase 5 details, PHASE6_SUMMARY.md for Phase 6 details, and Implementation Plan for the complete roadmap.
[Add your license here]
[Add contribution guidelines here]