Scheduling and Availability

Zone scheduling determines when a zone is open for business and when staff are available to work within that zone. The scheduling system uses a layered approach where zone-level operating hours intersect with staff-level availability to produce bookable time slots for customers.

Zone Operating Hours

A zone's operating hours are defined by assigning one or more schedules to it. Each schedule defines a recurring weekly pattern — for example, Monday through Friday from 8:00 AM to 6:00 PM, Saturday from 9:00 AM to 3:00 PM, and Sunday closed. Schedules are linked to zones through the schedule assignment table with an entity type of "zone."

A zone can have multiple schedule assignments to handle seasonal or contextual operating hours. The system determines which schedule is active based on effective date ranges, priority values, and the primary schedule flag.

Schedule Resolution

When determining a zone's operating hours for a specific date, the system follows this algorithm. First, it gathers all schedule assignments for the zone. Then it filters to assignments whose effective dates contain the target date. Among those, it selects the assignment with the highest priority value, using the primary flag as a tiebreaker. The winning schedule's day availability, date exceptions, and override rules define the zone's hours for that date.

Seasonal Schedules

Both schedules and their assignments support effective date ranges for seasonal patterns. A schedule might define "Summer Extended Hours" with a range from June 1 to August 31, offering longer operating hours. A "Holiday Season Hours" schedule might cover November 15 through December 31 with extended weekend availability.

The effective window is the intersection of the schedule's own dates and the assignment's dates. Both must be active for the schedule to apply. This means you can assign the same schedule to different zones with different effective periods.

Date Exceptions

Date exceptions are one-off overrides for specific dates. They take the highest precedence in schedule resolution — a date exception completely replaces the regular weekly pattern for that day. Common exception types include holiday closures (zone is unavailable all day), reduced hours (shorter operating window), extended hours (longer window, such as Black Friday), and custom availability for special events.

Date exceptions follow a strict precedence hierarchy: date exceptions override conditional override rules, which override the regular weekly pattern.

Master Schedule Inheritance

Zones inherit company-wide defaults from the Master Schedule. This includes default operating hours, holiday calendars with mandatory holidays that cannot be overridden, standard date exceptions, and default booking rules. Zones can override optional holidays and set their own booking constraints, but mandatory holidays from the Master Schedule always apply.

Staff Zone-Scoped Schedules

Staff members can have different availability depending on which zone they are working in. This is achieved through zone-scoped schedule assignments. A staff member might work Monday through Wednesday from 8:00 AM to 5:00 PM in the Eugene zone and Thursday through Friday from 9:00 AM to 4:00 PM in the Springfield zone.

Zone-scoped schedules always take precedence over the staff member's global schedule for that zone. If a staff member has no zone-specific schedule, their global schedule applies across all zones.

Resolution Order

When determining a staff member's availability for a specific zone on a specific date, the system first checks for zone-scoped schedule assignments. If zone-scoped schedules exist, those are used exclusively. If no zone-scoped schedules exist, the system falls back to the staff member's global schedule. Among matching assignments, the standard priority and effective date resolution applies.

Booking Flow Integration

When a customer books a service, the scheduling system determines available time slots through an intersection process. First, the system resolves the zone from the customer's address. Then it gets the zone's active schedule for the requested date. If the zone is closed on that date, the system suggests the next available date.

For open dates, the system identifies the zone's operating hours and queries all staff assigned to the zone. For each staff member, it resolves their availability using zone-scoped schedules when available or global schedules as a fallback. Available slots are the intersection of zone operating hours and at least one staff member being available. Finally, existing bookings and blocked time are subtracted from available slots.

Edge Cases

If a zone has no schedule assigned, it is treated as always open (24/7), with staff availability being the limiting factor. If the zone schedule says open but no staff are available, no time slots are shown. If a staff member's global schedule says available but their zone-scoped schedule says unavailable, the zone-scoped schedule wins. Zone holiday exceptions override all availability, regardless of individual staff schedules.