Concepts
Six short essays covering the vocabulary MavenFin uses everywhere — in URL paths, request payloads, and response objects. Once these click, the API reads itself.
Household
A household is the top-level client record — the central object every other resource hangs off of. It bundles the personal record (client and spouse), demographic data (DOB, gender, state), contact info, and the full inputs blob: accounts, asset-allocation strategies (AAS), spending goals, income streams, and tax assumptions.
URLs are scoped under /households/{id}. The household is the unit of authorization — any
token issued to a user-tenant pair can act on every household that tenant owns, and nothing more. Sandbox
households are seeded with realistic but fictional data and reset nightly.
Read the full inputs object via GET /households/{id}/inputs. Mutate any field there and every
downstream projection result changes deterministically — there is no other hidden state.
Plans & Scenarios
A plan (sometimes called a scenario) is a what-if branch over a household. It starts as a clone of the household's base inputs, then diverges with overrides: maybe a later retirement age, maybe a more aggressive AAS, maybe a different Social Security claim age, maybe a Roth conversion layered on top. The household's identity stays intact; the plan carries the deltas.
Plans nest under their household: /households/{id}/plans/{planId}. The base plan is the
identity transformation — running its projection produces the same result as if no plan were attached. The
usual workflow is to keep the base plan as the "current trajectory" and then create one or more named
comparison plans (Retire @ 65, Retire @ 67 + Roth) and diff their results.
Withdrawal strategies
When the projection needs cash and no income stream covers the gap, the withdrawal strategy decides which account pays. MavenFin ships four production-grade strategies, each a deterministic ordering across account types:
| Code | Name | Order | Best for |
|---|---|---|---|
T | Taxable-first | Taxable → Trad → Roth | Maximum Roth runway |
TD | Traditional-first | Trad → Taxable → Roth | Compressing future RMDs |
Roth | Roth-first | Roth → Taxable → Trad | Bracket-stuffing legacy goals |
Pro | Pro-rata | Weighted blend | Smoothing AGI year-over-year |
The strategy is a plan-level input. The projection engine resolves cash needs each month: it first looks at income streams (wages, pension, Social Security), then RMDs (mandatory and unavoidable), then taxes, and only then taps the withdrawal strategy to close the gap.
Monte Carlo
The deterministic projection answers what happens under the assumed return curve. Monte Carlo answers how likely is success across thousands of paths. The engine takes the deterministic plan and re-rolls equity and bond returns under a normal distribution parametrized by user-supplied mean and volatility (defaults: equity 7% / 18%, bonds 3% / 5%).
Each run replays the deterministic plan with its own random walk. Counted: paths that sustain spending to
plan end. Reported: the success rate and the percentile fan of terminal portfolio value
(P10 / P25 / P50 / P75 / P90). Pass an explicit seed for bit-identical reruns — useful for
regression tests and audit trails.
Roth conversion optimization
A Roth conversion moves dollars from a traditional IRA (taxable on withdrawal) to a Roth IRA (already taxed, never taxed again) — paying the tax bill now at today's bracket, in exchange for tax-free growth and no RMDs forever. The lifetime question is: how much, in which years, at what marginal cost?
The optimizer supports three strategies:
thresholdRoth— convert any year where current marginal bracket is below a fixed target.bracketFill— convert exactly enough to fill the chosen marginal bracket to its top. The 22% and 24% brackets are usually the sweet spot for retirees pre-RMD.dynamic— let the engine search the conversion-amount surface and pick the year-by-year amounts that maximize after-tax lifetime portfolio.
The optimizer accounts for IRMAA tier crossings, NIIT, capital-gains stacking, ACA-subsidy cliffs (if modeled), and RMD timing. The response contains a year-by-year schedule and the cumulative tax-savings curve vs. the no-conversion baseline.
Tax engine
Every projection row carries a full tax breakdown: AGI, taxable income, federal tax, state tax, FICA, Medicare premiums, IRMAA tier, capital-gains tax, QBI deduction, AMT, effective rate, and marginal bracket. The engine applies inflation-indexed brackets, the standard deduction (with the over-65 bump), and per-state rules for the 50 states + DC.
Tax results are reproducible: same inputs, same year, same number. The federal/state codepaths are validated against the parity reference suite to a fraction of a cent across 7,968 synthetic households.