Freelance Income Planner

Overview

Freelance Income Planner is a client-side income calculator that helps freelancers and consultants understand their real take-home pay. It goes beyond simple rate-times-hours math by factoring in taxes (simple percentage or progressive brackets), business expenses, personal cost of living, vacation weeks, and multi-currency billing.

The app runs entirely in the browser with no backend, no accounts, and no data transmission. State persists in localStorage so users can return to their scenarios without re-entering data. The interface is fully bilingual (English/Spanish) with instant language switching.

Two views serve different planning needs: Snapshot mode gives an immediate breakdown of current income, while Forecast mode enables three-scenario comparison (pessimistic, realistic, optimistic) with monthly projection charts and runway analysis.

The Challenge

• Unpredictable income: Freelancers face variable hours, seasonal demand, and client churn. A simple hourly rate doesn't tell you what you'll actually take home.
• Multi-currency complexity: Digital nomads billing in USD while spending in MXN or EUR need real-time conversion that accounts for exchange rate fluctuations in every calculation step.
• Tax opacity: Self-employment taxes are calculated on taxable income (gross minus business expenses), not raw gross. Most online calculators get this wrong, overstating tax burden.
• Privacy concerns: Entering detailed financial data into online tools means trusting a third party with sensitive information. Most freelancers would rather not.

The Solution

Privacy-first architecture: All computation happens client-side in pure TypeScript functions. No API calls for calculations, no user accounts, no analytics on financial data. The only external call is an optional exchange rate fetch.

Accurate tax modeling: Tax is calculated on taxable income (gross minus business expenses), matching standard self-employment tax treatment. Progressive bracket mode supports jurisdiction-specific rates. The engine reports deficits honestly rather than clamping to zero.

Dual-currency model: Users set a billing currency (what clients pay) and a spending currency (where they live). The exchange rate is user-controlled with an optional live FX fetch. All 9 combinations of USD/MXN/EUR are supported with correct bidirectional conversion.

Three-scenario forecasting: Forecast mode runs three independent calculation sets with adjustable rates, hours, and vacation weeks. Monthly projection charts apply seasonal multipliers. Runway analysis shows how long savings last under each scenario.

Technical Highlights

• Pure calculation engine: All income math lives in lib/calculations.ts as side-effect-free functions, validated against 151 edge cases covering tax logic, division safety, currency roundtrips, and deficit scenarios
• Single source of truth: Display components consume engine results rather than recalculating independently, eliminating drift between summary cards, breakdowns, and charts
• Server/client discipline: Strict Next.js 14 App Router patterns — 'use client' only where hooks or browser APIs are required
• Zustand with selective subscriptions: State management avoids unnecessary re-renders through granular store access patterns across 20+ interactive components
• Defensive numerics: Division-by-zero guards, NaN/Infinity propagation checks, and input validation clamping across all calculation paths
• Bidirectional currency conversion: Exchange rate interpretation is context-aware (billing-to-spending multiplies, spending-to-billing divides) with fallback heuristics