Booking Flow

The booking flow is the customer-facing journey from entering an address to confirming a service booking. Behind the scenes, the system resolves geographic boundaries to zones, applies zone-specific business rules, and determines available services, pricing, and time slots. This document covers every step of that resolution process.

Step 1: Address Entry

The customer provides a location in the booking widget. This can be a full address like "123 Main St, Eugene, OR 97401," a zip code only like "97401," or geographic coordinates. The system geocodes the input to produce latitude and longitude coordinates for boundary evaluation. If geocoding fails, the customer is asked to verify their address or enter a zip code.

Step 2: Boundary Resolution

Using the coordinates, the system evaluates all active boundaries to find which ones contain the point. Different boundary types use different resolution methods. Polygons use point-in-polygon checks against GeoJSON geometry. Radius boundaries use haversine distance calculations from the center point. Postal code sets match the customer's postal code against the set. Composite boundaries evaluate child boundaries using set operations (union, intersect, exclude) in sort order.

All boundaries are filtered to active, non-deleted records within their effective date ranges. The output is a set of matching boundary IDs.

Step 3: Boundary-to-Zone Mapping

Matching boundaries are mapped to zones through the zone-boundary junction table. The system joins to the zone table and filters to active, non-deleted zones. A point in any of a zone's boundaries means the zone matches (union logic). Duplicate zone IDs are deduplicated — a zone with multiple matching boundaries still appears once in the candidate list.

Step 4: Negative Zone Check

All candidate zones are evaluated for negative (exclusion) zones. If any matching zone has the negative flag enabled, the booking is blocked entirely. The customer sees "We don't currently service your area." Negative zones always win regardless of priority rating. If no negative zones match, the flow continues to priority resolution.

This is a critical safety check. It ensures that explicitly excluded areas — dangerous neighborhoods, restricted facilities, competitor territories — are never accidentally booked.

Step 5: Priority Resolution

Among remaining positive zones, the system determines the winning zone by sorting candidates by priority rating in descending order. The highest priority zone wins. When multiple zones tie on priority, the system may use additional context: customer tier, requested service type, staff availability in each zone, or the default zone flag as a final tiebreaker.

If no zones match at all (zero candidates), the default zone is used as a fallback. However, the default zone does not override negative zones — if boundaries matched but all resolved zones are negative, the booking is blocked.

Step 6: Industry Selection

With the resolved zone, the system retrieves available industries by querying the zone-industry table for active links. Industries are sorted by their zone-specific sort order and displayed to the customer. If the zone has no active industries, the customer sees "Services not available in your area."

The customer selects one industry from the displayed list to continue.

Step 7: Product Display and Zone Pricing

After industry selection, the system shows products for that industry with zone-specific pricing applied. For each product, it checks whether a zone-product override record exists. If an override exists and its flag is enabled, the zone-specific price is used. Otherwise, the product's default price applies.

The override flag pattern means zone pricing is granular — you can override the price without overriding the time estimate, or override the description without touching the price. Each field is independently controllable.

Step 8: Schedule and Time Slot Resolution

The system determines available booking time slots based on the zone's schedule. It resolves the zone's active schedule for the requested date using priority and effective date logic, then generates available windows based on the schedule's day availability pattern, adjusted for any date exceptions.

Step 9: Staff Availability Filtering

Time slots are further filtered by staff availability. The system queries all staff assigned to the resolved zone, resolves each staff member's schedule (zone-scoped or global), and removes time slots where no qualified staff are available.

Step 10: Booking Confirmation

The customer selects a time slot and confirms the booking. The system creates a booking record linked to the resolved zone with zone-specific pricing, assigned to the zone's schedule, with staff assignment handled either automatically via the dispatch engine or manually by an administrator.

Step 11: Manual Zone Override

After a booking is created, authorized staff can manually override the zone assignment. The override is logged in the audit trail with the original zone, new zone, reason, and who made the change. Pricing may be recalculated based on the new zone's overrides.