Pulse Ledger

Brain-dump your expenses, simulate your budget. PulseLedger instantly turns raw text into an interactive cashflow tracker with real-time what-if sliders.

Comment

Inspiration

Traditional personal finance tools suffer from a major friction point: tedious, manual data entry. Forcing users to punch in rows of expenses, categorize line items, and navigate complex drop-downs feels less like managing money and more like unpaid administrative work.

PulseLedger was inspired by the need to eliminate this friction entirely. Instead of forms and spreadsheets, what if you could simply brain-dump a messy paragraph of your monthly earnings and spending, let AI structure it instantly, and simulate budget adjustments using live What-If sliders? I wanted to build a lightning-fast, single-screen utility that turns text into a real-time financial simulation.

What it does

PulseLedger is a single-screen cashflow simulation tool. The core user flow runs seamlessly end-to-end:

  1. Brain-Dump or Preset Loading: Users type a plain-English narrative of their income and expenses or select from three built-in preset scenarios (e.g., Post-Payday Squeeze).
  2. Resilient Parsing: The app extracts structured items via OpenRouter (openai/gpt-4o-mini) or an offline-safe local regex fallback parser.
  3. Live What-If Simulation: Fixed essentials (such as rent or utilities) remain securely locked as read-only rows, while flexible and discretionary expenses feature $0\% \text{--} 150\%$ interactive sliders.
  4. Calculated Daily Pace & Metrics: Scrubbing sliders instantly recomputes top KPIs like the Safe Daily Allowance versus actual daily burn:

$$\text{Safe Daily Allowance} = \frac{\text{Monthly Income} - \text{Total Fixed Essentials}}{30}$$

  1. Action Plan Export: Users can copy a clean 5-part Markdown action plan and cuts checklist directly to their clipboard.

How it was built

PulseLedger was built from an empty folder using a strict, spec-driven development process with the Devpost Learn Skill Pack (challengepost/learn-ai-basics).

  • Frontend & UI: Developed with Next.js (App Router) and React 19, styled using Tailwind CSS and shadcn/ui primitives in a high-contrast dark fintech aesthetic. Typography combines Geist Sans for UI labels and Geist Mono with tabular-nums for all financial digits to eliminate horizontal jitter during live slider manipulation.
  • Validation & State: Zod acts as the single source of truth across API payloads, LLM responses, and browser localStorage persistence ("pulse_ledger_state").
  • Zero-Latency Computation: All derived metrics, KPI cards, and percentage proportions are computed synchronously in client memory via useMemo.

Challenges

  1. Preventing State Drift on Hydration: Keeping simulatedAmount synchronized when hydrating from localStorage or scrubbing sliders presented a risk of data drift. I solved this by enforcing a single normalization helper function (computeSimulatedAmount), ensuring baseline amounts and slider percentages strictly derive simulated totals.
  2. Resilient Offline Parsing: Relying solely on a live AI endpoint risked breaking live demos if network conditions faltered. Building a robust deterministic local regex/keyword parser fallback guaranteed that the app remains 100% functional offline or without an API key configured.
  3. Balancing Scope: Keeping the app strictly single-screen without user auth or multi-month historical databases required ruthless scoping, ensuring the proof-of-concept focused entirely on the high-impact "brain-dump to simulation" core loop.

Accomplishments

  • Successfully architecting a resilient hybrid parsing engine that seamlessly toggles between an AI model via OpenRouter and a local fallback parser without interrupting the user experience.
  • Designing a high-performance, single-screen dashboard where UI elements and financial metrics update in real time with zero-latency $\text{useMemo}$ computations.
  • Maintaining a strict spec-driven workflow from scope to production-ready code, ensuring zero scope creep during a rapid development sprint.

What I learned

  • How effective a structured Scope $\rightarrow$ PRD $\rightarrow$ Spec workflow is when partnering with AI coding agents to eliminate scope drift.
  • The importance of single-source-of-truth contracts using Zod to seamlessly connect server API validation, client-side state, and browser storage persistence.
  • That focusing on a single, highly polished end-to-end user flow (from raw text to simulated budget cut) makes for a much more compelling proof-of-concept than building a sprawling, half-finished application.

What's next for Pulse Ledger

  • Adding multi-month cashflow comparisons and trend visualization to track savings over time.
  • Expanding export options to include direct PDF reports or shareable snapshot links.
  • Integrating optional bank statement CSV parsing alongside the existing natural-language brain-dump input.

Built With

Share this project:

Updates

Submission history