Technical contract for the deterministic financial calculation engines. Covers dual-engine architecture, pipeline stages, calc module taxonomy, return metrics, financial statements, and type contracts. Use when working on financial calculations or pro forma generation.
The technical contract for the deterministic financial calculation engines. Covers the dual-engine architecture (Property Engine + Company Engine), pipeline stages, calc module taxonomy, return metrics, financial statements, consolidated reporting, and TypeScript type contracts. Use this skill whenever working on financial calculations, engine inputs/outputs, pro forma generation, or return metric computation.
Dual-engine system producing GAAP-compliant (ASC 230, ASC 360, ASC 470) monthly/yearly projections with IRS depreciation rules.
client/src/lib/financial/property-engine.ts)Single-property monthly pro forma. Processes each month sequentially through an 8-step pipeline producing MonthlyFinancials[].
client/src/lib/financial/company-engine.ts)Management company P&L, cash flow, and balance sheet. Consumes fee linkage from all property SPVs.
server/calculationChecker.tsServer-side checker reimplements all financial math from scratch. Never imports from client engines. Both producing same results = accuracy confirmed.
gop -> agop -> noi -> anoi
Total Revenue
- Departmental Expenses (Rooms, F&B, Events, Other)
- Undistributed Operating Expenses (Admin, Marketing, Property Ops, Utilities, IT)
= GOP (Gross Operating Profit)
- Management Fees (Base Fee + Incentive Fee)
= AGOP (Adjusted Gross Operating Profit)
- Property Taxes
= NOI (Net Operating Income) [NOI = AGOP - expenseTaxes]
- FF&E Reserve
= ANOI (Adjusted Net Operating Income)
- Interest Expense
- Depreciation
- Income Tax (NOL carryforward at 80% cap per IRC section 172)
= Net Income
Room Revenue = roomCount x DAYS_PER_MONTH (30.5) x ADR x Occupancy
adrGrowthRate annually, flat within each yearstartOccupancy in steps, capped at maxOccupancyroomRevenue x eventsRevenueShare (default 30%)roomRevenue x fbRevenueShare x (1 + cateringBoostPercent) (default 18% x 1.22)roomRevenue x otherRevenueShare (default 5%)| Expense | Default Rate | Base |
|---|---|---|
| Rooms (Housekeeping) | 20% | Room Revenue |
| F&B | 9% | F&B Revenue |
| Events | 65% | Events Revenue |
| Other | 60% | Other Revenue |
| Marketing | 1% | Total Revenue |
| FF&E Reserve | 4% | Total Revenue |
| Expense | Default Rate | Base |
|---|---|---|
| Admin & General | 8% | Total Revenue |
| Property Ops | 4% | Total Revenue |
| Utilities | 5% (60% variable/40% fixed) | Total Revenue |
| IT | 0.5% | Total Revenue |
| Property Taxes | 3% | Total Property Value / 12 |
Fixed cost escalation: anchored to Year 1 base, escalated by fixedCostEscalationRate. Supports annual or monthly compounding via escalationMethod.
loanCalculations.tsbuildingValue / 27.5 / 12acquisitionDatepurchasePrice - landValue (or purchasePrice * (1 - landValuePercent))Post-processing step when willRefinance is true and refinanceDate is within projection:
stabilized NOI / capRatevaluation x refi LTVRevenue through Net Income with all USALI line items.
| Metric | Computation |
|---|---|
| IRR | Newton-Raphson on equity cash flows (initial investment + annual BTCF + exit proceeds) |
| NPV | DCF of same cash flows at discount rate |
| Equity Multiple | Total distributions / total equity invested |
| Cash-on-Cash | Annual BTCF / total equity invested |
| Cap Rate | NOI / property value |
| DSCR | NOI / annual debt service |
Portfolio aggregation with intercompany elimination per ASC 810:
calc/)76 TypeScript files across 9 subdirectories (analysis, financing, funding, refinance, research, returns, services, shared, validation). Research modules registered in calc/dispatch.ts:
calc/research/ — Deterministic Research Tools| Module | Purpose |
|---|---|
property-metrics.ts | RevPAR, revenue, GOP, NOI, margins, valuation |
depreciation-basis.ts | IRS depreciable basis, monthly/annual depreciation |
debt-capacity.ts | Max loan from NOI, DSCR target |
occupancy-ramp.ts | Occupancy ramp schedule |
adr-projection.ts | ADR growth projection |
cap-rate-valuation.ts | Property valuation from NOI and cap rate |
cost-benchmarks.ts | Dollar-amount cost benchmarks |
validate-research.ts | Post-LLM validation against deterministic math |
calc/returns/ — Return Metrics| Module | Purpose |
|---|---|
irr-vector.ts | Newton-Raphson IRR computation on equity cash flows |
dcf-npv.ts | DCF analysis, NPV at discount rate |
mirr.ts | Modified IRR (finance rate + reinvestment rate) |
equity-multiple.ts | Total distributions / total equity |
exit-valuation.ts | Terminal value via cap rate or growth models |
wacc.ts | Weighted average cost of capital |
calc/analysis/ — Scenario & Portfolio Analysis| Module | Purpose |
|---|---|
scenario-compare.ts | Side-by-side scenario comparison, working capital & day-count |
break-even.ts | Break-even occupancy/ADR analysis |
stress-test.ts | Monte Carlo stress testing |
hold-vs-sell.ts | Hold vs sell decision analysis |
consolidation.ts | Portfolio-level consolidation |
capex-reserve.ts | Capital expenditure reserve modeling |
revpar-index.ts | RevPAR index benchmarking |
waterfall.ts | Equity waterfall distribution |
calc/financing/ — Debt & Financing| Module | Purpose |
|---|---|
dscr-calculator.ts | Debt service coverage ratio |
debt-yield.ts | Debt yield computation, working capital metrics |
sizing.ts | Loan sizing from DSCR/LTV constraints |
loan-comparison.ts | Multi-loan comparison |
sensitivity.ts | Rate sensitivity analysis |
closing-costs.ts | Closing cost estimation |
prepayment.ts | Prepayment penalty modeling |
interest-rate-swap.ts | Swap analysis |
financing-calculator.ts | Composite financing analysis |
costSegEnabled boolean; split percentages costSeg5yrPct, costSeg7yrPct, costSeg15yrPct allocate building value into accelerated depreciation classes (5/7/15/27.5-year). Tracked in MonthlyFinancials, aggregated in yearly output.DAYS_PER_MONTH (30.5) used for revenue; actual-day methods available in scenario-compare.ts.parseLocalDate() to prevent timezone shiftprojectionYears >= 2 requiredincomeTax = max(0, taxableIncome x taxRate)| File | Purpose |
|---|---|
client/src/lib/financial/property-engine.ts | Property calculation engine |
client/src/lib/financial/company-engine.ts | Company calculation engine |
client/src/lib/financial/types.ts | TypeScript interfaces |
shared/constants.ts | Named constants and defaults |
calc/ | 76 files, typed dispatch across 8 subdirectories |
client/src/lib/audits/ | 9-module audit system |
server/calculationChecker.ts | Independent verification engine |
.claude/skills/finance/)| File | Coverage |
|---|---|
income-statement.md | Revenue, expenses, NOI, net income |
cash-flow-statement.md | Operating, investing, financing activities |
balance-sheet.md | Assets, liabilities, equity |
irr-analysis.md | IRR, NPV, equity multiple, sensitivity |
dcf-analysis.md | DCF, FCF, FCFE reconciliation |
fee-linkage.md | Management/incentive fee calculations |
consolidation.md | Portfolio aggregation, eliminations |
management-company-statements.md | ManCo pro forma |
centralized-services.md | Cost-plus markup, vendor costs |
calc-module-map.md | Calc module taxonomy and dispatch |
calculation-chain.md | Engine pipeline stages |
cash-line-architecture.md | Cash line item structure |
consolidated-formula-helpers.md | Consolidated report helpers |
constants-and-config.md | Constants governance |
cross-statement-reference.md | Cross-statement field mapping |
diagnostic-decision-tree.md | Debugging financial issues |
fb-revenue-costs.md | F&B revenue and cost calculations |
financial-statements-construction.md | Statement construction patterns |
statement-separation-rules.md | Statement separation logic |
timing-activation-rules.md | Temporal activation and timing rules |
validation-identities.md | GAAP identity checks |