MoneyQuest
An interactive 12-month financial life simulation that makes everyday money decisions visible before they become expensive.
Status
BuildingFocus
Full Stack, Product Experiment
Primary Stack
Java 21 + Spring Boot
Type
Case Study
Product at a glance
See the year take shape
Four screens show MoneyQuest from first payday through monthly play, financial-health reflection, and the final year summary.
Overview
Overview
MoneyQuest is a full-stack educational simulation for young South African professionals. Players navigate a Johannesburg first-job year, make choices about housing, transport, technology, savings, debt, and lifestyle, then see those choices reshape their cash flow and financial health.
Anonymous quest bootstrap with a signed token so players can start without an account
South African context with PAYE, UIF, Johannesburg costs, recurring commitments, debt, and life events
Five-dimensional financial health view covering resilience, liquidity, debt load, saving habit, and lifestyle balance
Year-in-Money summary with spending breakdowns, monthly cash flow, annualised surprises, and key decisions
What-if simulations and replay flows that make alternative choices inspectable
Motivation
Why I Built It
MoneyQuest is an exploration of experiential financial education. Personal finance advice often arrives as a list of rules, but the hard part is understanding how ordinary choices interact over time.
The simulation gives a young professional a first year of independence to navigate. The goal is not to reward one perfect answer; it is to make trade-offs, recurring commitments, surprises, and consequences easier to feel and remember.
Problem
The Problem
Problem statement
Personal finance is often presented as isolated rules, while real decisions compound. A housing choice changes future cash flow, a phone contract creates a recurring commitment, and an unexpected event tests whether savings exist when they are needed.
A more expensive home changes what is available next month. A phone contract becomes a future commitment. A family emergency exposes whether savings exist when they are needed. These connections are difficult to understand when every decision is taught in isolation.
MoneyQuest also needed to feel locally relevant. PAYE, UIF, Johannesburg rent, Gautrain costs, store accounts, family support, and load-shedding surprises make the scenario concrete for the audience it is designed to teach.
Solution
The Solution
The product starts with a payslip and then moves month by month through a financial year. Each month combines income, recurring commitments, debt repayments, decisions, life events, and a transaction feed so the player can see what changed.
The experience continues after the simulation: a five-dimension financial-health view explains the current position, the Year in Money summary exposes annualised costs and defining decisions, What-If forks compare alternative choices, and Replay Quest makes the experiment repeatable.
Stack
Tech Stack
Decisions
Technical Decisions
Keep the simulation state on the backend
Runs, commitments, debt, savings, transactions, decisions, and life events are persisted by the Spring Boot service. That gives the simulation one authoritative state model and makes the same run available to the health, summary, what-if, and replay screens.
Use anonymous quest bootstrap with a signed token
Players can start immediately without creating an account. The API returns a signed token for the quest, while registration and login remain available when persistent identity is needed.
Keep the frontend statically exportable
The Next.js frontend can be developed independently, then exported and served by the Spring Boot application in the production container. This keeps deployment compact without coupling local frontend iteration to the backend build.
Make scenario paths reproducible with seeds
An optional seed makes event selection inspectable and gives development and debugging a repeatable run. That is especially useful for a simulation whose value depends on the relationship between several months of state.
Challenges
Challenges
Making consequences visible without turning the product into a spreadsheet
The interface has to surface enough financial detail to teach, while preserving the pace of a playable story. Cash displays, transaction history, compact health cards, and the annual summary give the numbers context without making every screen a ledger.
Keeping calculations consistent across views
The same run feeds the game, financial health, Year in Money, and What-If experiences. Persisting the domain state in the backend and mapping it through a typed service boundary prevents each screen from inventing its own version of the player’s finances.
Balancing realism with a deliberately finite simulation
MoneyQuest is an educational model, not a complete financial planner. A finite catalogue, a defined South African scenario, and explicit scope limits make the first experience understandable while leaving room for future datasets and hosted runs.
Lessons
What I Learned
A financial lesson becomes more memorable when the player experiences the trade-off before reading the explanation.
A simulation needs a single source of truth for state if several views are going to explain the same journey.
Local context is part of product design: tax, transport, housing, and family obligations shape the meaning of a choice.
Reproducible scenarios make probabilistic behaviour easier to test, debug, and discuss.
Status
Current Status
building
MoneyQuest is actively in development. The repository contains the current implementation, tests, and setup path; there is no public demo URL attached yet.
Architecture
System Design
MoneyQuest — current repository shape
Next.js / TypeScript frontend
Spring Boot REST API
Domain state