Aura

A probabilistic pocket accountant — a web application for personal finance management with Monte Carlo forecasting. Built with React 19, Vite, TypeScript, and Tailwind CSS. Actively under development as of early 2026.

Overview

Aura provides transaction management, goal tracking, asset management, CSV import, and probabilistic financial forecasting. The Monte Carlo simulation engine models a range of possible outcomes rather than single deterministic projections, giving users a realistic spread of financial scenarios.

All data persists to localStorage — no backend required for MVP. Zod schemas validate all data at read/write boundaries.

Tech Stack

Technology	Version	Purpose
React	^19.2.4	UI framework
Vite	^7.3.1	Build tool and dev server
TypeScript	^5.6.0	Strict-mode typed language
Tailwind CSS	^3.4.1	Utility-first styling
Vitest	^4.0.18	Unit and integration testing
Zod	^4.3.6	Runtime schema validation
Recharts	^3.7.0	Chart visualization (PieChart)
PapaParse	^5.5.3	CSV parsing for import

Architecture Decisions

Decision	Rationale	Status
React + Vite + TypeScript + Tailwind	Modern frontend stack aligned with existing apps/Chess project in the org	Implemented
Zod for runtime validation	Type-safe schema validation at localStorage and CSV import boundaries	Implemented
localStorage for persistence	Simple persistence without backend complexity for MVP	Implemented
Monte Carlo forecasting	Probabilistic range of outcomes vs. deterministic single-point projection	Implemented
Seeded RNG (SeededRandom class)	LCG-based seeded random for reproducible pipeline runs; Math.random() fallback for UI	Implemented
Holdout oracle calibration	Independent RNG stream prevents circular self-referential calibration in analyze.ts	Implemented

Key Patterns

Pattern	Description	Files
Zod schema validation	All data types as Zod schemas in types.ts, parsed on load/save	src/types.ts
localStorage persistence	Centralized storage service with typed get/save functions	src/services/storage.ts
Simulation service	Monte Carlo engine isolated in dedicated service	src/services/forecasting.ts
Form component pattern	Each form (Transaction, Goal, Asset, Transfer) is self-contained	src/components/*Form.tsx
Seeded random utility	LCG-based SeededRandom class for reproducible simulations	src/utils/seeded-random.ts

Current Status (v1.1 Milestone)

• Phase 1 (Foundation Fixes): Complete — seeded RNG, oracle calibration, documented thresholds
• Phase 2 (Test Coverage): Pending — metric unit tests, property-based tests, golden baselines
• Phase 3 (E2E Verification): Pending — 16 scenario combinations, JUnit XML output
• Phase 4 (UX Fixes): Pending — layout/spacing, visualization clarity
• CI/CD: Fixed (ubuntu-latest runner, lock file committed)
• Test coverage: <30% on components; 48 tests passing on core logic

Technical Debt

Item	Impact
Monolithic App.tsx (370 ln)	All state in one file — needs custom hooks/context
No error boundaries	React errors crash entire app
CSV import uses any types	Bypasses TypeScript safety on CSV row data
localStorage unencrypted	Financial data stored in plaintext
Low component test coverage	<30% — forms and CLI need tests

Lessons Learned

• Test selector specificity: Multiple forms with the same placeholder text caused ambiguous selector errors in Vitest.
• Recharts type strictness: Tooltip formatter and label callbacks need explicit null handling.
• Circular calibration: Using rng() < prediction as ground truth is self-referential — the oracle must use an independent RNG stream.
• Pipeline goal difficulty: Goals that are trivially solvable cluster predictions at 0.0/1.0, making calibration coverage degenerate.
• Lock file must be committed: Excluding package-lock.json in .gitignore blocks npm ci and GitHub Actions npm caching.

See Also

• Tech Stack — React + Vite stack documentation for the org
• Technical Debt Registry — tracked debt items for Aura
• localStorage Validation — Zod-based validation pattern established in this project