Financial Calculations
Financial logic for Quotes, Invoices, funding, and commissions across the renovation project lifecycle.
Architecture
| Layer | Location |
|---|---|
| Quote finance service | backend/src/services/quote-finance-service.ts |
| General finance service | backend/src/services/finance-service.ts |
| Commission calculator | backend/src/services/commission-calculator.ts |
| Funding calculator | backend/src/lib/funding-calculator.ts |
| Amount calculation hook | frontend/src/hooks/useAmountCalculation.ts |
| Financial document service | frontend/src/lib/services/financialDocumentService.ts |
| Contractor commission rates | backend/src/lib/contractor-commission.ts |
| Admin finance routes | backend/src/routes/admin/finance/ (contact-capacity-targets, contact-commissions, contact-cost-rates, partner-agreements) |
| Admin finance pages | frontend/src/pages/admin/ (TeamAdmin tabs: commissions, targets) |
Database Tables
| Table | Purpose |
|---|---|
costBreakdowns | Cost breakdowns per scenario measure |
costRates | Hourly cost rates per contact |
commissionAgreements | Commission terms per contact (EB/KOP rates, validity periods) |
commissionBookings | Monthly commission bookings (types: eb, kop, correction, bonus) |
capacityTargets | Capacity/hours/revenue targets per contact (renamed from targets) |
periodSettlements | Monthly commission settlement tracking |
billingInvoices | Unified invoice table — direction expressed via sellerId/contactId, dealType enum (EB/KOP); no separate incoming/outgoing tables |
Money Arithmetic (Big.js)
All money math goes through shared/money.ts (Big.js-backed): decimal(p, s) columns leave Drizzle as strings, are parsed with fromString(...), computed via add/sub/mul/div + round(m, 2) (HALF_UP), and stay decimal strings on the wire. Native Number()/parseFloat()/+ - * / on money values is forbidden and lint-enforced.
Calculation Areas
Quote Calculations
quote-finance-service.ts handles:
- Line item totals from Products pricing
- Tax calculations (VAT rates)
- Discount application
- Net/gross amounts
Funding Calculations
backend/src/lib/funding-calculator.ts computes:
- Eligible funding amounts per program
- Stacking rules (which programs can combine)
- Maximum funding caps
- Customer co-payment after funding
Commission Calculations
commission-calculator.ts computes monthly commissions per contact:
- Commissions based on agreement terms (
commissionAgreements) - Period-based settlement amounts (
periodSettlements)
Contractor-side commission rates are driven by the project’s engagement type via effectiveCommissionRate() in backend/src/lib/contractor-commission.ts: energy_consulting → 100% (RENEWA-direct), internal_contractor → the agreed rate, external_contractor → 0% (the contractor invoices the customer directly). See KOP Integration for the engagement-type model.
Frontend Amount Hook
frontend/src/hooks/useAmountCalculation.ts provides reactive calculation of totals, taxes, and discounts as users edit financial documents.
Admin Configuration
Finance administration is available through the Admin Dashboard:
- Cost rates — configure standard rates for labor and materials
- Commissions — manage commission agreements and view bookings
- Capacity targets — set revenue and capacity goals per period
Related
- Quotes — quote entity with financial data
- Invoices — invoice entity with payment tracking
- Funding Applications — funding calculations per application
- Funding Programs — funding program rules and limits
- Products — product pricing used in calculations
- Admin Dashboard — finance configuration UI
- Scenario Planning — cost comparison across scenarios