Wiroom Pension Calculator Development

You are working with the Wiroom pension calculator, a React-based application that helps users determine if they're financially prepared for retirement using Monte Carlo simulation to model investment uncertainty.

Development Commands

Use these npm scripts for common development tasks:

Project Architecture Overview

The application is structured around three core layers:

1. **Mathematical Core** - Deterministic calculations and Monte Carlo simulation

2. **UI Layer** - React components with tab-based input system and chart visualization

3. **Type System** - TypeScript interfaces defining data structures

Core Mathematical Components

Pension Calculations (`src/pension-calculations.ts`)

This file contains the deterministic pension projection logic:

**Main Function**: `calculatePensionProjection()`

- **Accumulation Phase** (before retirement): `pot = pot * (1 + growthRate) + annualContribution`

- **Drawdown Phase** (after retirement): `pot = pot * (1 + growthRate) - annualDrawdown + statePension`

Monte Carlo Simulation (`src/monte-carlo.ts`)

Implements probabilistic modeling of market uncertainty:

**Key Functions**:

State Pension Integration (`src/state-pension.ts`)

Implements UK state pension rules:

**Key Functions**:

UI Architecture

Component Hierarchy

**Main Component**: `src/pension-calculator.tsx`

**Tab-Based Input System**:

**Visualization Component**: `src/components/PensionChart.tsx`

Chart Scaling Solution

**Problem**: The 95th percentile in optimistic scenarios can reach extreme values, making median/quartile lines appear flat.

**Solution** (implemented in `PensionChart.tsx`):

1. Set yAxisMax to 110% of the 75th percentile maximum

2. Clamp p95 data points above this threshold to `undefined` (breaks line on chart)

3. Preserve original unclamped values in custom tooltip

4. Display "(cropped)" indicator in tooltip for clamped values

Reusable Components

Data Flow

Follow this sequence when implementing features:

1. **User Input** → `PensionParams` interface in `src/types.ts`

2. **Deterministic Calculation** → `calculatePensionProjection()`

3. **Monte Carlo Simulation** → `runMonteCarloSimulation()`

4. **Percentile Calculation** → `calculatePercentiles()`

5. **Visualization** → Chart rendering with data clamping in `PensionChart`

TypeScript Interfaces

Key types defined in `src/types.ts`:

Testing

**Test Suite**: `src/pension-calculator.test.ts`

- Basic functionality

- Edge cases

- Mathematical precision

- Realistic scenarios

- Stress tests

- Data integrity

- State pension integration

**Critical Test Cases**:

Development Guidelines

When Modifying Calculations

1. Always preserve the two-phase model (accumulation vs drawdown)

2. Ensure pot depletion logic only applies during drawdown

3. Verify state pension is added at correct eligibility age

4. Run full test suite after changes: `npm test`

5. Check TypeScript types: `npm run typecheck`

When Modifying Charts

1. Maintain data clamping logic to prevent flat visualization

2. Preserve unclamped values in tooltips

3. Test with extreme scenarios (very high volatility, optimistic returns)

4. Ensure chart remains readable across all percentiles

When Adding Features

1. Update `PensionParams` interface if adding new user inputs

2. Update calculation functions to handle new parameters

3. Add corresponding UI controls in appropriate tab component

4. Write tests covering new functionality

5. Update this documentation if adding significant new patterns

Common Tasks

Adding a New Input Parameter

1. Add field to `PensionParams` in `src/types.ts`

2. Update `calculatePensionProjection()` to use new parameter

3. Add UI control in relevant tab component

4. Add test cases in `pension-calculator.test.ts`

Modifying Chart Display

1. Edit `src/components/PensionChart.tsx`

2. Be careful with data clamping logic (yAxisMax calculation)

3. Test with extreme values to ensure readability

4. Update tooltip if adding new data fields

Adjusting State Pension Rules

1. Update logic in `src/state-pension.ts`

2. Update constants (current rate: £11,973/year)

3. Update eligibility age calculations if UK rules change

4. Run state pension integration tests

Important Constraints