Simulation Procedure

Given a project budget, spending profile, available cash and financing options, RevIQ simulates the monthly cash position across three standard financing scenarios (100% cash, 100% debt, 50/50 mixed), computes interest costs, applies straight-line revenue recognition to advance payments, performs sensitivity and scenario analysis, and returns a fully labelled SIMULATED ESTIMATE with exceptions and a plain-language recommendation.

1. 1

   Parse and validate the simulation request payload

   Parse and Validate

   Parses the simulation_data JSON string and extracts spending_profile, available_cash, minimum_cash_reserve, financing_options, revenue_items, interest_rate_changes, custom_scenarios and sensitivity_parameters. Safe defaults are applied where optional fields are absent.

   • Malformed or empty JSON returns safe defaults and sets a parse_error flag so the run continues on project_cost and duration.
   • base_rate defaults to 0.065 (6.5%) when not supplied.
   • Financial inputs are never fabricated — missing required fields are surfaced as exceptions.
2. 2

   Build the monthly project spending profile

   Build Profiles and Schedules

   Uses the supplied spending_profile array, padding shorter arrays with an even share of the remaining months, and falls back to an even distribution when no profile is given.

   • Under even distribution the sum of monthly spend equals project_cost.
   • An explicit profile is used as-is — the caller owns the total.
   • All output values are labelled SIMULATED ESTIMATE.
3. 3

   Compute the available cash position and project cash

   Build Profiles and Schedules

   Deducts minimum_cash_reserve from available_cash to determine cash_available_for_project.

   • cash_available_for_project is floored at zero — never negative.
   • The minimum cash reserve is always preserved; not all bank cash is usable.
4. 4

   Build the monthly revenue recognition schedule

   Build Profiles and Schedules

   Divides each revenue item by its recognition_period_months to compute the straight-line monthly recognised amount, tracking cash received separately from recognised revenue with a running deferred balance.

   • Cash received is NOT revenue recognised — advance payments are spread across the service period.
   • Reconciliation holds: total_cash_received = total_recognized_in_period + total_deferred_end_of_period.
   • The schedule extends 24 months past project end to capture deferred balances.
5. 5

   Build the monthly interest rate schedule

   Build Profiles and Schedules

   Starts from base_rate + spread and applies rate_changes at the specified months, returning one annual rate (decimal) per project month.

   • Where multiple rate changes apply, the latest one by from_month takes effect.
   • Exactly one annual rate is returned per project month.
6. 6

   Compare financing scenarios and generate the scenario summary

   Run Financing Simulations

   Always produces 100% Internal Cash, 100% Bank Financing and 50% Cash + 50% Debt, plus any custom scenarios, running a monthly cash-flow simulation for each.

   • The three standard scenarios are always generated regardless of custom scenarios.
   • 100% Cash: opening_cash = cash_available_for_project + minimum_reserve; no financing.
   • 100% Debt: opening_cash = available bank cash; financing = project_cost × 1.1.
   • 50/50: opening_cash = cash_available_for_project × 0.5 + minimum_reserve; financing = project_cost × 0.6.
   • Revenue cash reduces financing need in every scenario.
7. 7

   Run sensitivity analysis across key interest rate variables

   Run Financing Simulations

   Re-runs the 50/50 scenario across a range of interest rates (default 5%, 6%, 7%, 8%, 9%) and reports total_interest and estimated_project_cost for each.

   • The 50/50 opening cash and financing structure are held constant so the rate is the only variable.
   • A custom interest_rates list in sensitivity_parameters overrides the default range.
8. 8

   Evaluate the simulation against review conditions

   Analysis and Exceptions

   Checks five conditions per scenario and globally: cash below minimum reserve (HIGH), financing above the configured limit (HIGH), interest rate above threshold (HIGH), financing cost increasing project cost by more than 5% (MEDIUM) and revenue items missing a recognition period (HIGH).

   • Any triggered condition sets status = REVIEW_REQUIRED.
   • Exceptions are decision-support flags for the finance team.
   • No condition is ever auto-resolved.
9. 9

   Compute the project cost forecast and net funding requirement

   Analysis and Exceptions

   Uses the 50/50 scenario as primary and separates original_project_cost, financing_cost, revenue_offset, net_funding_requirement and estimated_final_project_cost.

   • estimated_final_project_cost = project_cost + total_financing_cost.
   • net_funding_requirement = project_cost − revenue_received (before financing cost).
   • Project cost and financing cost are reported separately, never combined silently.
10. 10

    Generate the plain-language AI financial explanation

    Assemble Output

    Produces a multi-sentence summary referencing the cash position versus project need, per-scenario financing cost, minimum cash balance, revenue recognition timing and any triggered exceptions.

    • Every figure comes from the simulation results — no fabricated numbers.
    • Cash-only and 50/50 are compared to show the cost-versus-liquidity tradeoff.
    • A SIMULATED ESTIMATE disclaimer is appended.
11. 11

    Assemble the dashboard KPI snapshot

    Assemble Output

    Derives eight KPIs from the primary scenario and the cost forecast: project cost, financing required, financing cost, total estimated cost, revenue received, revenue recognised, deferred revenue and minimum cash balance.

    • KPIs come from the 50/50 scenario, falling back to the first available scenario.
    • All values labelled SIMULATED ESTIMATE.
12. 12

    Assemble the full structured API response

    Assemble Output

    Combines all computed sections into the normalised response, derives the overall status and a plain-language recommendation comparing the three standard scenarios.

    • Status is REVIEW_REQUIRED whenever a HIGH-severity exception is present.
    • The recommendation is derived from scenario comparison — never fabricated.
    • The entire response is labelled SIMULATED ESTIMATE — NOT ACTUAL FINANCIAL RESULTS.
13. 13

    Persist the simulation to the RevIQ FC Simulations audit collection

    Persist Simulation

    Generates a unique simulation_id, inserts one record into the audit collection and returns the simulation_id and server-assigned row_id.

    • One insert per simulation run — prior simulations are never overwritten.
    • full_response_json is set at insert time.
    • simulation_id format: SIM_<project>_<timestamp>.