Cash Projection

Cash Projection

Component File: src/features/reports/components/CashProjectionReport.tsx Data Layer: src/lib/db/cash-projections.ts Route / navigation: Path /reports/cash-projection, Zustand reportTool = cash-projection. See 00-REPORTS-HUB.md. Access Level: Pro+ report users, including parent-org users and fund users scoped to their allowed funds. Last Updated: April 29, 2026 Status: Implemented as read-only forecast/planning report

Purpose

Cash Projection estimates future monthly cash balances from existing books and operational commitments. It is a planning report, not a formal Cash Flow Statement, Statement of Financial Position, or Balance Sheet surface.

V1 is read-only. It does not create, edit, void, or post accounting records.

Access

• Tool id: cash-projection
• Route: /reports/cash-projection
• Tier gate: TOOL_MINIMUM_TIER['cash-projection'] = 'pro'
• Free and Plus users see the standard HubGrid paywall badge and PaywallModal.
• Pro, Enterprise, Demo, and Internal users pass through by rank comparison.
• Custom-position users need the Reports hub grant and the cash-projection tool grant.
• Parent-org users see parent scope plus child funds. Fund users remain scoped to their assigned fund visibility.

Inputs

The data module composes existing read paths:

• Starting cash: cash/bank asset ledger balances as of the selected as-of date, using the deterministic bank_accounts account classification and 10xx asset-code convention rather than account-name matching.
• Historical actuals: posted revenue and expenses from the existing Income Statement fetcher over the selected lookback window.
• Recurring giving signals: recurring donor amount/frequency where available.
• Committed inflows: open pledges, grants receivable, and reliable scheduled deposit memorized transactions.
• Committed outflows: open bills, pending/approved expenses, and reliable scheduled payment memorized transactions.
• Budget inputs: approved annual budget revenue and expense months where available.

Projection Behavior

• Default projection: monthly, 12 months.
• Default lookback: 6 completed months before the as-of month.
• Default method: Actuals + Commitments.
• The first forecast period starts on the first full month after the as-of date.
• Each row rolls forward: starting cash + inflows - outflows = ending cash.

Available methods:

| Method | Behavior |

|--------|----------|

| Actuals + Commitments | Uses historical averages, recurring donor signals, known commitments, and budget top-ups only where the approved monthly budget exceeds the actual run-rate baseline. Budgets are not added on top of averages when the run-rate already covers the budgeted amount. |

| Actuals Only | Uses historical averages and recurring donor signal adjustment, excluding explicit commitments and budgets. |

| Budget Only | Uses approved budget revenue and expenses only. |

UI

The report uses shared report patterns:

• Breadcrumb
• PageHeader
• ReportDateRangeSelector in as-of mode
• shared Select, Card, Table, Badge, Alert
• ContentSkeleton
• shared ExportButton for CSV, XLSX, and PDF exports
• semantic badge variants for assumption labels
• hardcoded financial green/red classes via accountingAmountColors
• DesktopOnlyWarning for the dense monthly projection and assumption tables

Displayed metrics:

• Starting Cash
• Projected Ending Cash
• Lowest Month
• Net Change
• Monthly projection rows: starting cash, inflows, outflows, net change, ending cash
• Assumption badges: Actual, Average, Committed, Budget, Manual

Exports include both projection rows and assumption details.

The data layer returns stable warning and assumption codes. The React report translates those codes in the UI and exports so forecast labels remain locale-aware.

Guardrails

Cash Projection must not modify Balance Sheet RPCs or related migrations. Any future attempt to reuse or change Balance Sheet RPCs still requires the existing triple-confirmation and explicit Steve sign-off process documented in `../../contracts/BALANCE-SHEET-PARITY.md`.

If performance later requires a dedicated RPC, it must follow report-grade SECURITY DEFINER, JWT org-tree guards, void exclusion, effective-fund scoping, and fund-user scope contracts.

Tests

Current coverage includes pure projection math in src/lib/db/cash-projections.test.ts:

• lookback range
• projection periods
• starting cash roll-forward
• revenue and expense averages
• commitments
• budget inputs
• negative cash scenarios

Access and routing are covered by the shared tier, permission, search parity, and navigation surfaces that consume ReportTool, REPORT_REGISTRY, TOOL_MINIMUM_TIER, and PERMISSION_TREE.

Synced from IFMmvp-Frontend documentation: pages/reports/25-CASH-PROJECTION.md