retirement-wasm

This repository is now organized around a browser-local retirement planner:

• frontend/ is a SvelteKit app that owns the UI shell
• crates/retirement-sim-core/ is the shared Rust simulation core
• crates/retirement-sim-wasm/ exposes that core to the browser through WebAssembly
• backend/ is an Axum server that serves the static frontend and runtime config

The first implementation slice establishes the Rust workspace, WebAssembly build pipeline, worker boundary, and product shell. The real simulation model lands in the backlog notes under docs/unaddressed/notes/.

Current Architecture

1. frontend/scripts/build-wasm.mjs builds crates/retirement-sim-wasm/ into frontend/src/lib/wasm/pkg/ with wasm-pack.
2. SvelteKit imports that generated package from a dedicated Web Worker.
3. The worker initializes the Rust-generated WASM module and exposes a typed handshake.
4. The Axum backend serves /static/config.json, /healthz, and the built SPA bundle.

Model Guide

If you want the practical explanation of the form fields, monthly math, and known limits, start here:

• docs/simulation-math.md - a succinct technical guide to the model, inputs, and caveats
• docs/types.md - the shared payload shapes and cross-stack schema contracts
• docs/TESTING.md - how to verify changes to the model and UI

Requirements

• Node.js 24+
• npm 11+
• Rust 1.95.0 with edition 2024 support
• the wasm32-unknown-unknown target

The repo pins the Rust toolchain in the root rust-toolchain.toml.

Local Development

Frontend:

cd frontend
npm install
npm run dev

Backend:

cargo run -p retirement-wasm-backend

The frontend dev server proxies /static and /healthz to the backend.

To start both together:

./mk/run-dev

Validation

Frontend:

cd frontend
npm install
npm run check
npm run build
npm run test -- --run

Rust workspace:

cargo test --workspace

Full wrapper:

./mk/test

Deployment Shape

The Docker image builds the frontend, compiles the Rust backend as a static binary, copies the built frontend into the runtime image, and serves everything from one process.

Backlog

Implementation routing lives in:

• docs/unaddressed/notes/0000-retirement-app-routing.md

The next planned slices after the WASM pipeline are the shared domain schema, canonical assumptions, and the deterministic month-by-month household engine.