ATLAS
Contractor Region & Territory Setup

Service area management with zip code territories, team assignments, coverage analysis, and performance analytics. Inspired by Salesforce Territories, DoorDash Zones, ServiceTitan, and Google Maps.

1 Define Regions
2 Assign Zips
3 Map & Assign
4 Analyze Coverage
1 Regions & Map
2 Coverage & Analytics
1 Territory Manager
2 Coverage Analytics
Setup
Regions List
9:41
Service Regions
4
Regions
47
Zip Codes
3
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
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
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
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
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
9:41
Team Territories
By Team
By Region
Team A
3 members · 2 regions
MJ
Mike Johnson
Lead Technician
Downtown Cuyahoga
SR
Sarah Rodriguez
HVAC Specialist
Downtown Cuyahoga
KW
Kevin Williams
Apprentice
Downtown
Team B
2 members · 1 region
AC
Alex Chen
Senior Plumber
Suburbs
LP
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

Analytics
Coverage Analysis
9:41
Coverage Analysis
82%
Area Covered
47
Active Zip Codes
5
Gap Areas
3
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
9:41
Region Analytics
7D 30D 90D YTD
$24.8K
Total Revenue
+12% vs last month
68
Jobs Completed
+8 vs last month
$365
Avg Job Value
+4%
22 min
Avg Travel Time
+3 min
Jobs by Region
28
Downtown
22
Suburbs
12
Cuyahoga
6
Rural
Revenue by Territory
Downtown Akron
$10,240
Summit Suburbs
$8,120
Cuyahoga Falls
$4,380
Rural Summit
$2,060
Team Utilization by Region
MJ
Mike Johnson 92%
SR
Sarah Rodriguez 78%
AC
Alex Chen 64%
KW
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)

Data Architecture

Schema tables, hooks, queries, and mutations that power the region & territory system.

Schema Tables

pricebookServiceRegions
Geographic pricing zones. contractorId, name, description, regionType (urban/suburban/rural/premium/custom), laborMultiplier, materialMultiplier, travelFeeFlat, travelFeePerMile, minimumOrderCents, color, displayOrder, isDefault, isActive, createdAt, updatedAt.
schema
pricebookZipcodeRegions
Zip code to region mapping. contractorId, regionId (ref), zipcode string, overrideLaborMultiplier, overrideMaterialMultiplier, overrideTravelFeeFlat, overrideMinimumOrderCents, notes, isActive, createdAt. Indexed by contractor+zipcode and by region.
schema
pricebookRegionServicePricing
Per-service pricing overrides by region. contractorId, regionId, tradeType, laborMultiplier, materialMultiplier, flatAdjustmentCents, minimumOrderCents, isActive, createdAt. Indexed by contractor+region and contractor+trade.
schema

React Hooks

useQuery(listRegions)
Returns all regions with zip counts, sorted by displayOrder. Supports includeInactive filter. Each region includes zipcodeCount aggregate.
hook
useQuery(getRegion)
Single region detail with full zipcode list and servicePricing array. Used by Edit Region and Zip Code Management screens.
hook
useQuery(listZipcodes)
All zipcodes for a region or contractor. Includes regionName join. Used by Zip Code Management screen chip grid.
hook
useQuery(getPricingForZipcode)
Resolved pricing for a single zipcode. Cascades: region default → zipcode override → service-specific override. Returns final multipliers, travel fee, minimum order.
hook

Mutations

createRegion
Creates a service region. Validates name length (2–100), multiplier range (0.5–3.0), region limit (max 50). Handles isDefault toggling across regions.
mutation
updateRegion
Updates region fields with explicit field mapping (no spread). Supports partial updates for name, description, multipliers, travel fees, color, displayOrder, isDefault, isActive.
mutation
deleteRegion
Deletes a region. Fails if region has linked zipcodes or service pricing rules. Requires removal of dependencies first.
mutation
addZipcode
Adds a single zipcode to a region. Validates 5-digit format, checks for contractor-wide duplicates, enforces 1000 zipcode limit. Supports per-zipcode overrides.
mutation
addZipcodesBulk
Bulk adds up to 100 zipcodes. Validates all formats, deduplicates, skips existing. Returns added/skipped/skippedZips counts.
mutation
removeZipcode
Removes a zipcode mapping. Validates contractor ownership before deletion.
mutation
setServicePricing
Upserts per-service pricing overrides for a region. Validates multiplier ranges. Creates or updates based on existing region+trade combo.
mutation

Utilities & Components

convex/lib/geo.ts
Haversine distance calculation, bounding box queries, geohash encoding/decoding, neighbor cell computation, radius prefix generation for spatial queries.
utility
CreateRegionScreen
app/(contractor)/(tabs)/settings/company/create-region.tsx — Form with name, description, multiplier input, region type chips. Uses ScreenLayout with terracotta title.
component
EditRegionScreen
app/(contractor)/(tabs)/settings/company/edit-region.tsx — Pre-filled form with active toggle, manage zipcodes nav link. Uses useLocalSearchParams for regionId.
component
RegionZipcodesScreen
app/(contractor)/(tabs)/settings/company/region-zipcodes.tsx — Add/remove zipcodes with bulk paste, removable chip grid, multiplier info card. RefreshControl enabled.
component
RegionalPricingScreen
app/(contractor)/(tabs)/settings/company/regional-pricing.tsx — Companion screen for per-service pricing overrides by region.
component
Regions & Map
Regions & Map
9:41
Regions
Service Regions
North Hill District
7 zip codes • 3 techs
Active
West Side
5 zip codes • 2 techs
Active
South Summit
4 zip codes • 1 tech
Low Coverage
Territory Map
Color-coded zone overlays with overlap detection
Coverage & Analytics
Coverage & Analytics
9:41
Coverage & Analytics
Coverage Stats
16
Zip Codes
92%
Coverage
Team Assignment
Jake M.
North Hill • 7 zips
Sarah L.
West Side • 5 zips
Tom R.
South Summit • 4 zips
Region Performance
$24K
North Hill
$18K
West Side
$8K
South
Territory Manager
Territory Manager
https://app.3bids.io/contractor/regions
3Bids
Territory
Regions ⌘1
Map ⌘2
Zip Codes ⌘3
Assignments ⌘4
Analytics ⌘5
MK
Mike Kowalski
Contractor

Territory Manager

3
Regions
16
Zip Codes
92%
Coverage
6
Technicians
Territory Overview Map
Interactive territory map with color-coded zones and overlap detection
Coverage Analytics
Coverage Analytics
https://app.3bids.io/contractor/regions/analytics
3Bids
Territory
Regions ⌘1
Map ⌘2
Zip Codes ⌘3
Assignments ⌘4
Analytics ⌘5
MK
Mike Kowalski
Contractor

Coverage Analytics

Revenue by Region
Coverage Heatmap