Contractor Region & Territory Setup

1 Define Regions

2 Map & Assign

3 Regional Pricing

4 Coverage & Analytics

5 Conflicts

Setup

Regions List Live

9:41

Service Regions

Regions

Zip Codes

Active

Downtown Akron

12 zips Team A

Active

1.15x

Summit County Suburbs

18 zips Team B

Active

1.0x

Cuyahoga Falls

9 zips Team A

Active

1.10x

Rural Summit West

8 zips Unassigned

Inactive

0.90x

RegionListScreen — Contractor-scoped region list with active toggle, zip count summaries, and team assignments.

useQuery(api.pricebook.regionalPricing.listRegions)

Create Region Live

9:41

Create Region

Region Information

Region Name *

Description

Region Type

Urban Suburban Rural Premium Custom

Region Color

Used on maps and region cards for quick identification.

Boundary Preview

Draw boundary on map or add zip codes

Boundaries auto-calculate from assigned zip codes.

Assigned Team

Team A Team B Team C All Teams

CreateRegionScreen — Multi-section form with type selector, color picker, boundary preview, and team assignment.

useMutation(api.pricebook.regionalPricing.createRegion)

Zip Code Management Live

9:41

Downtown Akron Zips

Add Zip Code

Bulk Add Zip Codes

Current Zip Codes

12 total

44301

44302

44303

44304

44305

44306

44307

44308

44309

44310

44311

44312

Coverage Estimate

~38 mi²

Total Area

~142K

Population

1.15x

Multiplier

Pricing Adjustment Jobs in these zip codes will have a 1.15x pricing multiplier applied to labor costs.

RegionZipcodesScreen — Search + add, bulk paste, removable chip grid, coverage area estimate.

useMutation(api.pricebook.regionalPricing.addZipcode, removeZipcode)

Territory

Region Map View Live

9:41

Territory Map

Downtown

Suburbs

Cuyahoga

Rural

Overlap Detected

Downtown and Cuyahoga Falls share 3 zip codes (44310, 44311, 44312). Resolve to avoid pricing conflicts.

Region Legend

Downtown Akron

12 zips38 mi²

Active

Summit Suburbs

18 zips67 mi²

Active

Cuyahoga Falls

9 zips24 mi²

Active

Rural Summit

8 zips52 mi²

Inactive

RegionMapScreen — Map placeholder with colored zone overlays, overlap detection alerts, region legend, and zoom controls.

useQuery(api.pricebook.regionalPricing.listRegions) + geo.ts utilities

Edit Region Live

9:41

Edit Region

Region Details

Region Name *

Description

Region Type

Urban Suburban Rural Premium Custom

Base Multiplier *

+15% premium pricing

Active

Zip Codes

12 assigned

44301

44302

44303

44304

44305

+7 more

Region Color

Assigned Team

Team A Team B Team C

EditRegionScreen — Pre-filled form with all region details, zip summary, boundary adjustment, rename, and team reassignment.

useMutation(api.pricebook.regionalPricing.updateRegion)

Territory Assignment Live

9:41

Team Territories

By Team

By Region

Team A

3 members · 2 regions

Mike Johnson

Lead Technician

Downtown Cuyahoga

Sarah Rodriguez

HVAC Specialist

Downtown Cuyahoga

Kevin Williams

Apprentice

Downtown

Team B

2 members · 1 region

Alex Chen

Senior Plumber

Suburbs

Lisa Park

Electrician

Suburbs

Assignment Guide = Primary coverage. Drag to reorder priority. Members without a star badge are backup.

Unassigned Region Rural Summit West has no team assigned. Assign a team to receive job leads in this area.

TerritoryAssignmentScreen — Drag-assign interface with primary/backup designation, team grouping, and unassigned alerts.

useMutation(api.teams.assignTerritory) · Segmented By Team / By Region

Regional Pricing

Per-Service Regional Pricing Live

9:41

Regional Pricing

Downtown

Suburbs

Cuyahoga

Rural

Downtown Akron

Base multiplier: 1.15x · 12 zips

Active

Service Overrides

5 overrides

HVAC Install

Labor: 1.20x · Material: 1.05x

Override 1.20x

Plumbing Repair

Labor: 1.15x · Material: 1.00x

Base 1.15x

Electrical

Labor: 1.30x · Material: 1.10x

Override 1.30x

Water Damage

Labor: 1.25x · Material: 1.15x

Override 1.25x

General Maintenance

Labor: 1.15x · Material: 1.00x

Base 1.15x

HVAC Install — Cross-Region

Downtown

1.20x

Suburbs

1.00x

Cuyahoga Falls

1.10x

Rural Summit

0.80x

Pro Tip Set per-service overrides to fine-tune pricing beyond the base region multiplier. Overrides cascade: region base → service override → zipcode override.

RegionalPricingScreen — Per-service multiplier overrides by region, cross-region comparison, cascade logic.

useQuery(api.pricebook.regionalPricing.getRegion) · useMutation(api.pricebook.regionalPricing.setServicePricing)

Travel Fee Overrides Live

9:41

Travel Fees

Travel Fee Schedule

Downtown Akron

Flat: $0 · Per-mile: $0

Free

Summit Suburbs

Flat: $15 · Per-mile: $1.50

$15+

Cuyahoga Falls

Flat: $25 · Per-mile: $1.50

$25+

Rural Summit West

Flat: $45 · Per-mile: $2.00

$45+

Edit — Rural Summit West

Flat Fee ($)

Per-Mile Rate ($)

Minimum Order ($)

Jobs under this amount won’t be dispatched to this region.

Travel Fee Impact Higher travel fees reduce bid competitiveness. Rural regions with $45+ flat fees see 23% fewer accepted bids.

TravelFeeScreen — Per-region flat fee + per-mile rate, minimum order threshold.

useMutation(api.pricebook.regionalPricing.updateRegion) · travelFeeFlat, travelFeePerMile, minimumOrderCents

Analytics

Coverage Analysis Live

9:41

Coverage Analysis

82%

Area Covered

Active Zip Codes

Gap Areas

Overlapping Zips

Job Density vs Coverage

Darker = more job requests. Red = uncovered demand.

44301

44302

44303

44304

44305

44306

44307

44308

44313

44314

44309

44310

44315

44316

44311

44312

44317

44320

Covered

Uncovered demand

Low coverage

Coverage Gaps

44313

Firestone Park — 23 requests/mo

44314

Kenmore — 18 requests/mo

44316

Lakemore — 11 requests/mo

Expansion Suggestions

44313 — High ROI Potential

23 uncaptured requests/mo with 2 competitors. Estimated revenue: $4,200/mo.

Stow/Hudson Corridor

Adjacent to your Suburbs region. 14 requests/mo with low competition.

Competition Density

Downtown Akron

8 competitors

Summit Suburbs

5 competitors

Cuyahoga Falls

3 competitors

Rural Summit

1 competitor

CoverageAnalysisScreen — Heat map of job density vs coverage, gap detection, expansion suggestions, and competition density.

useQuery(api.analytics.regionCoverage) · getPricingForZipcode

Region Analytics Live

9:41

Region Analytics

7D 30D 90D YTD

$24.8K

Total Revenue

+12% vs last month

Jobs Completed

+8 vs last month

$365

Avg Job Value

+4%

22 min

Avg Travel Time

+3 min

Jobs by Region

Downtown

Suburbs

Cuyahoga

Rural

Revenue by Territory

Downtown Akron

$10,240

Summit Suburbs

$8,120

Cuyahoga Falls

$4,380

Rural Summit

$2,060

Team Utilization by Region

Mike Johnson 92%

Sarah Rodriguez 78%

Alex Chen 64%

Kevin Williams 41%

Travel Time Analysis

Downtown

12 min avg

Suburbs

18 min avg

Cuyahoga

24 min avg

Rural

38 min avg

Underserved Areas

Rural Summit West

6 jobs last month but no dedicated team. 38 min avg travel.

West Akron (44320)

Adjacent to Downtown but not in any region. 9 missed leads.

RegionAnalyticsScreen — Jobs per region chart, revenue by territory, team utilization, travel time analysis, and underserved areas.

useQuery(api.analytics.regionPerformance) · usePricingAnalytics(timeRange)

Conflict Resolution

Territory Conflicts Planned

9:41

Conflict Resolution

2 Territory Overlaps Detected

Resolve overlaps to avoid assignment conflicts

Downtown Akron × West Side

Overlap

4.2 sq mi

Affected Zips

44302, 44313

North Canton × Green

Overlap

1.8 sq mi

Affected Zips

44720

Resolution History

East Akron & University merged

Mar 12, 2026 · 2 zips reassigned

44305 assigned to South Akron

Mar 8, 2026 · Boundary adjusted

Premium zone boundary redefined

Feb 28, 2026 · 3 zips moved

TerritoryConflictScreen — Overlap detection with map preview, resolution actions, and history log.

useQuery(api.regions.detectOverlaps) · useMutation(api.regions.resolveConflict)

Data Architecture

Schema tables, queries, mutations, and source files powering the Region & Territory system.

Source Files

create-region.tsx

Create Region — name, description, multipliers, region type chips, color

screen

edit-region.tsx

Edit Region — pre-filled form, active toggle, manage zipcodes nav

screen

regional-pricing.tsx

Regional Pricing — per-service pricing overrides by region

screen

region-zipcodes.tsx

Zip Code Management — add/remove, bulk paste, chip grid, override multipliers

screen

Convex Queries

listRegions

All regions with zip counts, sorted by displayOrder. Supports includeInactive filter. Each region includes zipcodeCount aggregate.

query

getRegion

Single region detail with full zipcode list and servicePricing array. Used by Edit Region and Zip Code Management.

query

getRegionalPricing

Per-service pricing overrides for a region. Returns multipliers, flat adjustments, and minimum order values.

query

getZipcodes

All zipcodes for a region or contractor. Includes regionName join and per-zipcode override values.

query

Convex Mutations

createRegion

Creates a service region. Validates name (2–100 chars), multiplier range (0.5–3.0), region limit (max 50). Handles isDefault toggling.

mutation

updateRegion

Updates region fields with explicit field mapping. Supports partial updates for name, multipliers, travel fees, color, displayOrder, isActive.

mutation

addZipcode

Adds a single zipcode to a region. Validates 5-digit format, checks for duplicates, enforces 1000 limit. Supports per-zipcode overrides.

mutation

removeZipcode

Removes a zipcode mapping. Validates contractor ownership before deletion.

mutation

setRegionalPricing

Upserts per-service pricing overrides for a region. Validates multiplier ranges. Creates or updates based on region+trade combo.

mutation

Schema — pricebook/regionalPricing

pricebookServiceRegions

Geographic pricing zones — regionType (urban/suburban/rural/premium/custom), laborMultiplier, materialMultiplier, travelFee, minimumOrder, color, displayOrder.

schema

pricebookZipcodeRegions

Zip code to region mapping — zipcode string, override multipliers, override travel fee, notes. Indexed by contractor+zipcode and by region.

schema

pricebookRegionServicePricing

Per-service pricing overrides by region — tradeType, multipliers, flatAdjustmentCents, minimumOrderCents. Indexed by contractor+region and contractor+trade.

schema

Region Status Flow

draft → active → inactive

Key Design Decisions

Pricing Cascade

Region default → zipcode override → service-specific override resolution chain

Territory Map

Color-coded zone overlays with overlap detection and coverage analytics

Bulk Zip Import

Paste up to 100 zipcodes with validation, deduplication, and skip reporting

Service	North Hill	West Side	South	Premium
HVAC Repair	1.2x	1.0x	0.9x	1.5x
HVAC Install	1.3x	1.0x	0.85x	1.6x
Ductwork	1.2x	1.0x	0.9x	1.4x
Maintenance	1.0x	1.0x	0.95x	1.2x
Emergency Call	1.5x	1.3x	1.1x	1.8x

Data Architecture

Source Files

Convex Queries

Convex Mutations

Schema — pricebook/regionalPricing

Region Status Flow

Key Design Decisions

Territory Manager

Coverage Analytics

Regional Pricing

Territory Map & Conflicts