Creating a Financial Scenario

Creating a financial scenario is the foundation of building a comprehensive financial plan in Wealthie. The application provides a streamlined workflow for creating new scenarios that automatically populates client data while leveraging organizational defaults for consistency. All scenario creation begins through the Create New Scenario modal, accessible from the main Scenarios page.

The "Create New Scenario" Modal

Core Inputs

Household Selection

• Search and select the household for which you're creating the scenario
• If no households exist, you'll be prompted to create one first
• The system validates that the selected household has sufficient member data before allowing scenario creation

Scenario Name

• Provide a unique and descriptive name for the new scenario
• The system automatically checks for duplicate names within the same household and prevents creation if a duplicate exists
• Common naming conventions: "Base Plan", "Retirement at 60", "Conservative Strategy", "Property Sale Scenario"

Planner Type Selection Choose from three planner types based on the scope and complexity of the financial plan:

1. Full Planner (Default)

   • Comprehensive financial planning with all features enabled
   • Includes: Income, Expenses, Savings, Investments, KiwiSaver, Properties, Goals, What-If scenarios
   • Use for: Complete financial plans with property ownership, complex investments, and full lifecycle planning

2. KiwiSaver Planner

   • Focused exclusively on KiwiSaver retirement savings
   • Includes: Income, Expenses, KiwiSaver accounts
   • Excludes: Properties, Investment Funds, Savings (only KiwiSaver balances)
   • Use for: Clients primarily focused on KiwiSaver contributions and retirement income from KiwiSaver only

3. Lite Planner

   • Simplified planning without property management
   • Includes: Income, Expenses, Savings, Single consolidated Investment Fund, KiwiSaver
   • Excludes: Properties, Multiple investment funds (consolidates all investments into one fund)
   • Use for: Younger clients without property, simple retirement planning, clients with straightforward financial situations

Important: The planner type is set at scenario creation and determines which data is imported from the household database. Choose carefully based on the planning scope.

Scenario Creation Workflow

Standard Creation: "Create Scenario"

This is the primary method for creating new scenarios and works by intelligently combining three data sources in priority order:

Data Source Priority:

1. Explicit Client Data (Highest Priority): Information entered in the household database

   • Member names, ages (calculated from date of birth), and partner status
   • Income records from the Income tab
   • Expense records from the Expenses tab
   • Assets (KiwiSaver, Investments, Savings, Properties)
   • Liabilities (Mortgages, Loans linked to assets)

2. Scenario Defaults (Medium Priority): Organization-wide defaults configured in Scenario Metrics

   • Economic assumptions (inflation rates, investment returns)
   • Fund selections (default investment and KiwiSaver funds)
   • Contribution rates (if not specified in household data)
   • Toggle states (which input fields are visible by default)

3. System Defaults (Lowest Priority): Hard-coded fallback values

   • Used only if neither client data nor scenario defaults exist
   • Examples: 95 for ending age, 2% for inflation rate, 5.5% for investment returns

How Data is Processed by Planner Type

Full Planner Data Processing: The system fetches and processes all available household data:

Properties:

• Fetches all property assets from the household database
• Prioritizes owner-occupied properties first, then investment properties
• Supports up to 5 properties per scenario
• Automatically links mortgages/loans to properties
• Calculates loan terms and repayment schedules
• Identifies rental income linked to investment properties
• Applies default property growth rate (3%) and transaction costs (3% of value)

Investment Funds:

• Creates separate fund entries for each investment asset
• Maintains individual fund balances, names, and providers
• Sets up withdrawal priority based on the order of assets
• Applies organization's default investment fund characteristics (return, risk, income portion, fees)
• If multiple investment assets exist, creates Fund 1, Fund 2, Fund 3, etc.

Income Processing:

• Primary incomes: First income record for each member (member_id 1 and 2)
• Additional incomes: All other income records not linked to properties
• Property incomes: Handled separately and linked to specific properties
• Frequency conversion: Converts all income frequencies (weekly, fortnightly, monthly, quarterly) to annual amounts
• Net-to-Gross conversion: Automatically converts net incomes to gross for tax calculations

Expense Processing:

• Regular expenses: All expense records not linked to property liabilities
• Property expenses: Handled separately as part of property cash flows
• Frequency conversion: Annualizes all expense frequencies
• Splits into pre-retirement (starting age to 64) and retirement (65 to 95) periods

KiwiSaver Processing:

• Identifies KiwiSaver and Superannuation assets by member (member_id 1 and 2)
• Applies default contribution rates if not specified in household data
• Sets up KiwiSaver fund periods with organization's default fund characteristics
• Includes income portion, fees, tiered fees, and advice fees from the selected default fund

KiwiSaver Planner Data Processing: Highly focused on KiwiSaver-only planning:

What's Included:

• Primary income for main member and partner (for KiwiSaver contribution calculations)
• Annual expenses (for cashflow and retirement planning)
• KiwiSaver accounts for both members with balances
• Contribution rates (employee and employer)
• NZ Superannuation (if enabled)

What's Excluded:

• All property assets and liabilities (completely ignored)
• All investment fund assets (set to 0)
• All savings accounts (set to 0)
• Additional incomes beyond primary employment
• Property-linked income and expenses

Why KiwiSaver Planner?

• Clean, focused analysis for clients only interested in KiwiSaver retirement planning
• Eliminates complexity of property and investment management
• Ideal for younger clients building their first retirement savings
• Simplifies presentation when KiwiSaver is the only retirement vehicle

Lite Planner Data Processing: Simplified planning without property complexity:

What's Included:

• Primary and additional incomes (not property-linked)

• Regular expenses (not property-linked)

• Savings account balances (consolidated)

• Single consolidated investment fund: All investment assets are combined into one fund

  • Total value = sum of all investment asset balances
  • Description: "Consolidated X Investment(s)" where X is the count
  • Uses organization's default fund characteristics
  • Simplifies to a single withdrawal priority

• KiwiSaver accounts for both members

What's Excluded:

• All property assets and liabilities
• Property-linked income (rental income)
• Property-linked expenses (mortgage payments)
• Multiple investment fund tracking (consolidated into single fund)

Why Lite Planner?

• Perfect for renters or clients without property investments
• Reduces complexity for clients with straightforward financial situations
• Faster scenario creation and easier client comprehension
• Ideal for younger professionals or those early in their financial journey

Advanced Creation: Copy Existing Scenario

The system includes a powerful scenario copying feature that allows advisers to create new scenarios based on existing ones:

Workflow:

1. Toggle "Use existing scenario as default" switch
2. Select an existing scenario from the household (filtered by planner type)
3. Choose whether to update with current data or create exact copy

Two Copying Modes:

Mode 1: Exact Copy (Use updated details = OFF)

• Creates a perfect duplicate of the selected scenario
• Preserves all values, assumptions, investment periods, and configurations
• Only changes: scenario name, creation timestamps, planner_type (if changed)
• Use for: Comparing different what-if scenarios with same baseline, creating variations for sensitivity analysis

Mode 2: Updated Copy (Use updated details = ON)

• Starts with existing scenario structure but updates with current household data

• Updates ages (recalculated from current date of birth)

• Updates incomes and expenses from current household database

• Updates asset balances (KiwiSaver, Investments, Savings, Properties)

• Preserves existing scenario's configuration:

  • Investment fund periods and strategies
  • KiwiSaver fund periods
  • Economic assumptions and rates
  • What-If events
  • All customized settings

• Use for: Annual plan reviews, updating scenarios after client data changes, maintaining scenario structure with fresh data

Important Notes:

• Existing scenarios are filtered by planner type (can only copy scenarios of the same type)
• The scenario copying feature is available regardless of whether household data exists
• Updated copy mode intelligently merges: current data for balances/incomes/expenses, existing scenario for all assumptions and configurations

Scenario Builder (Currently Disabled)

The "Open in Scenario Builder" method is currently commented out in the interface but remains in the codebase for future use. This method would create a nearly blank scenario with only basic household information (names, ages) and redirect to a step-by-step builder interface.

Default Values and Their Application

Fund Characteristics

When creating scenarios, the system automatically applies fund characteristics from the organization's custom or market funds:

For Investment Funds:

• Looks up the default investment fund ID from scenario defaults
• Retrieves actual fund characteristics:
  • Income Portion (% of returns taxed as income vs capital gains)
  • Fees (flat fee % or tiered fee structure)
  • Advice Fees (flat or tiered)
  • Fee tier thresholds and rates

For KiwiSaver Funds:

• Looks up the default KiwiSaver fund ID from scenario defaults
• Retrieves fund characteristics (same as investment funds)
• Applies PIE tax rates instead of marginal tax rates
• Can use either custom KiwiSaver funds or starred MorningStar market funds

Fallback Logic:

1. First, checks for stored characteristics in scenario defaults (for MorningStar funds)
2. Then, looks for the fund in organization's custom funds
3. Then, checks for market fund overrides
4. Finally, uses fund type defaults (Conservative = 75% income, Balanced = 50%, Growth = 25%, Aggressive = 0%)

Economic Assumptions

Standard economic parameters applied to new scenarios:

Inflation Rates:

• General inflation: From scenario defaults or 2.0% system default
• Income inflation: From scenario defaults or falls back to general inflation rate
• Expense inflation: From scenario defaults or falls back to general inflation rate
• Property growth: From scenario defaults or 3.0% system default

Income Periods:

• Main member: Starting age to 64 (retirement age)
• Partner: Partner starting age to 64
• Automatically adjusts if client is already past retirement age

Expense Periods:

• Pre-retirement (Period 1): Starting age to 64
• Retirement (Period 2): 65 to 95
• Same expense amount by default (advisers can adjust post-creation)

Simulation Parameters:

• Number of Monte Carlo simulations: From scenario defaults or 100
• Confidence interval: From scenario defaults or 80%
• Used for risk analysis and probability-of-success calculations

Age Calculations

The system prioritizes date of birth over stored age values for accuracy:

Calculation Method:

Age = Current Year - Birth Year
If birthday hasn't occurred this year: Age = Age - 1

Fallback Hierarchy:

1. Calculate from date_of_birth (most accurate)
2. Use stored age value from household members
3. Use default age (30 for primary member)

Ending Age:

• Always set to 95 for all scenarios
• Represents the planning horizon
• Can be adjusted in the Personal Tab after creation

Data Validation and Error Handling

Household Validation:

• Household must exist and be selected
• Household must have at least one member with a name
• If insufficient data, user is directed to complete household setup

Scenario Name Validation:

• Must not be empty
• Must be unique within the household
• Real-time duplicate checking as user types
• Warning displayed if duplicate detected

Plan Limits:

• Free plan: Maximum 3 scenarios per user
• Paid plans: Unlimited scenarios
• System checks limits before creating scenario

Missing Data Handling:

• If client data missing: Uses scenario defaults
• If defaults missing: Uses system defaults
• No data field is ever left null or undefined
• Ensures scenario always opens successfully in planner

Post-Creation Workflow

Automatic Actions:

1. Scenario is saved to the database with timestamps
2. Success notification is displayed
3. Appropriate planner opens in a new browser tab:
   • Full Planner: /protected/planner?scenarioId=X&household_id=Y
   • KiwiSaver Planner: /protected/kiwisaver-planner?scenarioId=X&household_id=Y
   • Lite Planner: /protected/lite-planner?scenarioId=X&household_id=Y
4. Modal closes
5. Scenarios list refreshes to show the new scenario

Next Steps:

• Review and adjust all imported values in the planner tabs
• Configure investment and KiwiSaver fund periods if needed
• Set up goals and What-If scenarios
• Run simulations to test plan viability
• Generate reports for client presentation

Best Practices

Before Creating Scenarios:

1. Set Up Organization Defaults: Configure Scenario Metrics with standard assumptions
2. Enter Client Data: Complete household setup with all available financial information
3. Choose Appropriate Planner Type: Select based on client complexity and planning scope
4. Consider Naming Convention: Use consistent, descriptive names (e.g., "Base Plan 2025", "Retirement at 60")

During Scenario Creation:

1. Verify Household Data: Ensure all relevant client information is up-to-date
2. Select Correct Planner Type:
   • Full: For clients with property or complex investments
   • Lite: For renters or simple situations
   • KiwiSaver: For KiwiSaver-only analysis
3. Review Auto-Populated Values: Check that imported data is accurate
4. Use Scenario Copying Wisely: Leverage existing scenarios for consistency

After Scenario Creation:

1. Validate All Inputs: Review each tab for accuracy and completeness
2. Adjust Investment Periods: Customize fund strategies for different life stages
3. Configure Consolidation: Set KiwiSaver consolidation at retirement if applicable
4. Set Up What-If Events: Model potential life events and risks
5. Run Initial Simulation: Ensure no errors and review baseline results

Common Use Cases

Use Case 1: New Client with Full Financial Data

• Client owns property, has KiwiSaver, and investment accounts
• Choose: Full Planner
• Result: All assets, liabilities, and cash flows automatically imported and structured

Use Case 2: Young Professional Renting

• Client has employment income, basic expenses, KiwiSaver, and small investment account
• Choose: Lite Planner
• Result: Simplified plan with consolidated investment fund and KiwiSaver focus

Use Case 3: KiwiSaver Review Only

• Client wants to review KiwiSaver strategy and retirement projections
• Not concerned with property or other investments in this analysis
• Choose: KiwiSaver Planner
• Result: Clean KiwiSaver-focused analysis with retirement income projections

Use Case 4: Annual Review Update

• Existing scenario from last year needs updating with current data
• Want to maintain all previous assumptions and configurations
• Process:
  1. Enable "Use existing scenario as default"
  2. Select last year's scenario
  3. Enable "Use updated details"
  4. Create scenario
• Result: Updated balances and ages, preserved assumptions and settings

Use Case 5: What-If Comparison

• Want to compare early retirement (age 60) vs standard retirement (age 65)
• Process:
  1. Create base scenario with retirement at 65
  2. Enable "Use existing scenario as default"
  3. Select the base scenario
  4. Disable "Use updated details" (exact copy)
  5. Name it "Early Retirement at 60"
  6. Create scenario and adjust income periods to end at 60
• Result: Two scenarios with identical baseline, only retirement age differs

Use Case 6: Scenario Without Property Data

• Client owns property but adviser wants to analyze non-property wealth only
• Choose: Lite Planner or KiwiSaver Planner
• Result: Property assets and liabilities are excluded from analysis

Troubleshooting

Issue: "Unable to create scenario due to insufficient data"

• Cause: Household has no members or member names are missing
• Solution: Navigate to household setup and add member information (at minimum: name)

Issue: Scenario name already exists

• Cause: Another scenario with identical name exists for this household
• Solution: Choose a different, unique name

Issue: Investment funds not showing up in new scenario

• Cause: Planner type is set to KiwiSaver (which excludes investment funds)
• Solution: Use Full Planner or Lite Planner for investment fund inclusion

Issue: Properties not appearing in scenario

• Cause: Planner type is set to Lite or KiwiSaver (both exclude properties)
• Solution: Use Full Planner to include property assets and liabilities

Issue: Multiple investment accounts consolidated into one

• Cause: Planner type is set to Lite (consolidates all investments)
• Solution: Use Full Planner to maintain separate investment fund tracking

Issue: Default fund characteristics not applying

• Cause: Organization defaults not configured or fund ID missing
• Solution: Configure Scenario Metrics with default investment and KiwiSaver funds

Issue: "Free plan limit reached"

• Cause: User has already created 3 scenarios (free plan limit)
• Solution: Upgrade to paid plan or delete unused scenarios

Issue: Ages seem incorrect

• Cause: Date of birth not entered in household members
• Solution: Add date of birth to household members for accurate age calculation

Issue: Copied scenario not using updated data

• Cause: "Use updated details" switch is OFF
• Solution: Enable "Use updated details" when copying to pull current household data