Feature: Regional Pricing Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Regional Pricing Engine is a core service within the Driveway Estimator Pro platform designed to provide accurate material cost estimations based on geographical location (ZIP code), material type, and project dimensions. By integrating localized pricing data, the engine allows homeowners and contractors to move beyond generic estimates to precise, market-reflective financial planning for driveway projects.
The engine handles the full lifecycle of a price request: from detecting user location and retrieving cached or mock regional rates to calculating exact material volumes (in tons) and final total project costs. It acts as the financial backbone for the Estimator workflow.
Sources: README.md:8-10, server/services/pricing.ts:41-45
Architecture and Data Flow
The pricing engine operates as a backend service exposed via tRPC procedures. It interacts with a MySQL/TiDB database for caching and localized lookups.
Pricing Request Lifecycle
When a user selects a material in the frontend, the system initiates a request that flows through the following stages:
- Location Acquisition: The client retrieves GPS coordinates or ZIP code.
- tRPC Invocation: The
getPricingprocedure is called with dimensions and location. - Cache Verification: The engine checks the
materialPricestable for a non-expired entry for that ZIP and material. - Pricing Retrieval: If no cache exists, it retrieves data from a regional provider (mocked in current implementation).
- Quantity Calculation: The engine converts square footage and depth into tons.
- Final Computation: Total cost is calculated by multiplying tonnage by regional rates.
Sources: server/routers/projects.ts:98-115, client/src/pages/Estimator.tsx:93-107
The diagram above illustrates the sequence of operations from the initial UI interaction to the database-backed calculation logic.
Sources: server/services/pricing.ts:41-75, server/routers/projects.ts:93-125
Core Logic and Calculations
Material Volume Calculation
The engine converts architectural dimensions into physical mass. It first converts depth from inches to feet to calculate cubic feet, then to cubic yards, and finally to tons based on specific material density constants.
| Material | Density (Tons/Cubic Yard) | Description |
|---|---|---|
| Hot Mix Asphalt | 1.5 | Professional durable surface; highest density |
| Asphalt Millings | 1.3 | Recycled asphalt; medium density |
| Tar & Chip | 1.2 | Rustic appearance; standard density |
| Gravel | 1.0 | Most economical; lowest density |
Sources: server/services/pricing.ts:98-110, README.md:21-24
Cost Computation Formula
The final cost is derived using the following implementation logic:
// From server/services/pricing.ts
const cubicFeet = squareFeet * (depthInches / 12);
const cubicYards = cubicFeet / 27;
const tons = cubicYards * densityPerCubicYard[material];
const totalCost = tons * pricePerTon;
Sources: server/services/pricing.ts:98-124
Data Models and Schema
The engine relies on the materialPrices table to manage localized data and reduce external API latency.
The materialPrices Schema
| Field | Type | Description |
|---|---|---|
zipCode | varchar(10) | The primary geographical key for regional pricing. |
material | varchar(50) | Material identifier (hotmix, millings, etc.). |
pricePerTon | varchar(50) | The localized rate per ton. |
pricePerSquareFoot | varchar(50) | The localized rate per sq ft for quick reference. |
expiresAt | timestamp | Cache TTL (currently set to 24 hours). |
Sources: drizzle/schema.ts:100-112, server/services/pricing.ts:70-75
API Implementation (tRPC)
The projects.getPricing procedure serves as the primary interface for the engine.
Procedure Definition: getPricing
- Access Level: Protected (requires authentication)
- Inputs:
zipCode: stringmaterial: "hotmix" | "millings" | "tar_and_chip" | "gravel"squareFeet: numberdepthInches: number
- Outputs:
pricePerTon: string (formatted)pricePerSquareFoot: string (formatted)quantityNeeded: string (e.g., "2.50 tons")totalCost: string (formatted)
Sources: server/routers/projects.ts:93-125
Sequence of Service Calls
The following sequence diagram demonstrates how the tRPC router orchestrates multiple internal services to fulfill a pricing request.
Implementation Details
Mock Data Structure
For regions without live supplier integrations, the engine falls back to a structured mock dictionary.
- ZIP 10001: High-range pricing (e.g., Hotmix @ $85/ton)
- ZIP 90210: Premium-range pricing (e.g., Hotmix @ $95/ton)
- Default: Standard rates (e.g., Hotmix @ $75/ton)
Sources: server/services/pricing.ts:13-35
Precision and Formatting
The engine maintains strict formatting for financial and material data to ensure consistency in the UI and PDF exports.
- Tonnage: Rounded to 2 decimal places using
Math.round(tons * 100) / 100. - Currency: Parsed and returned as strings (e.g.,
$112.50) viatoFixed(2).
Sources: server/services/pricing.ts:114-117, server/services/pricing.ts:140-142
Summary
The Regional Pricing Engine transforms raw driveway dimensions and location data into actionable financial estimates. By utilizing a combination of material density constants, localized price caching in the materialPrices table, and a structured tRPC API, it provides the necessary precision for professional-grade driveway estimation. Future iterations are planned to replace the mockPricingByZip with real-time supplier API integrations.
Sources: todo.md:14, todo.md:46-48