Scheduling & Calendar

Overview

The scheduling engine is the operational core of SalonOS. It gives a location a real-time, conflict-free view of who is doing what, where, and with which resource — for any day or week. The front desk lives in this surface all day: booking, moving, cancelling, and managing walk-ins.

The calendar simultaneously enforces staff availability, physical resource allocation (rooms, chairs, equipment), and shift rules. It prevents double-booking at both the staff and resource level and stays in sync across all connected devices in real time.

Calendar Views

Day View

The primary workspace. A scrollable time grid with one column per staff member (or per resource — switchable). Time slots are coloured by appointment state. Non-bookable time (shift gaps, breaks, time-off, closures) shows as a distinct region that cannot receive drops.

Column modes:

• Per-staff: one column per bookable stylist/technician — default for booking
• Per-resource: one column per room, chair, or equipment unit — useful for resource-constrained locations

Week View

A seven-day overview showing capacity at a glance. Useful for planning and spotting gaps. Click any day to drill into the day view.

Appointment States

State	Meaning
Held/Pending	Reserved but not yet confirmed (e.g. during online booking)
Confirmed	Booked and confirmed
Checked In	Client has arrived at the location
In Service	Service actively in progress
Completed	Service finished; ready for checkout
No-show	Client did not arrive
Cancelled	Appointment cancelled (with reason captured)

Creating an Appointment

From any empty cell on the calendar:

1. Select the client (search existing or quick-create with name + phone)
2. Add one or more services; each gets a staff assignment and a resource assignment
3. System checks availability and computes the visit timeline (including service buffers)
4. If a deposit is required by the brand's policy, it is captured or noted
5. Confirm — the appointment appears on the calendar and triggers a confirmation message

Multi-Service Visits

One booking can contain multiple services:

• Sequential: services run back-to-back (same or different staff)
• Parallel: services run simultaneously (e.g. manicure during hair colour processing time) — enabled per brand

Each service leg has its own staff assignment, resource, and duration. The system keeps the visit as one logical booking for the client and for checkout, while allocating each leg independently.

Drag-to-Reschedule

Appointments can be dragged to a new time slot or to a different staff column. While dragging, the calendar previews valid (green) and invalid (blocked) drop targets. On drop, the system re-runs all availability checks and either commits or reverts with an explanation.

Walk-In Queue

A live queue board for handling walk-ins without a pre-booked appointment:

1. Front desk adds the walk-in: name/phone, requested service, optional preferred stylist
2. Walk-in enters the queue in arrival order with an estimated wait time
3. When a stylist frees up, the desk assigns the walk-in from the queue
4. Assignment converts the queue entry into an in-service appointment on the calendar

Queue and calendar stay in sync in real time: assigning from the queue updates the calendar; completing an appointment frees capacity the queue reflects immediately.

Resource Allocation

Physical resources (rooms, chairs, stations, equipment) are managed as first-class entities:

• Each service can require a specific resource type, a specific named resource, or no resource
• The system prevents two overlapping services from sharing the same resource
• Resources have their own availability windows and maintenance blocks
• When a service needs both a qualified staff member AND a resource, both must be free

Conflict and Double-Booking Prevention

The calendar blocks any action that would:

• Put the same staff member in two overlapping services
• Assign the same resource to two overlapping services
• Book a service outside a staff member's shift or into their time-off (unless an explicit override is permitted and logged)

When a conflict is detected, the system explains the exact clash and where possible offers the nearest valid alternatives.

Realtime Sync

All appointment, queue, and allocation changes propagate to every connected viewer of that location in near real time via Supabase Realtime. Two front-desk staff can run the calendar simultaneously without colliding. Concurrent edits converge to one consistent state — a user editing a record that changes under them is notified before their edit can commit.

Non-Bookable Blocks

Managers can create blocks on the calendar for:

• Cleaning and sanitisation time between appointments
• Staff breaks
• Training sessions
• Equipment maintenance
• Ad-hoc closures

Blocks consume staff and/or resource availability and are respected by all conflict checks.

Business Rules

Rule	Behaviour
Staff double-booking	Blocked by default; configurable override is audited
Resource double-booking	Always blocked; no override
Out-of-shift booking	Blocked by default; configurable override is audited and visually flagged
Staff lacks service skill	Staff not offered for that service; forced assignment requires override
Multi-service chain with one leg missing capacity	Entire visit cannot be confirmed until all legs have staff and resource
Concurrent edit collision	Last valid commit wins; losing editor is notified and shown current state
Booking same client in two overlapping visits	Warning shown; requires confirmation
Service duration changed in catalog after booking	Existing appointments keep booked duration; new bookings use updated default
Resource taken out of service mid-day	Future appointments on that resource flagged for reallocation
Time zone	All times in the location's configured time zone

Configuration Options

Setting	Scope	Default
Slot granularity (5/10/15 min)	Location	15 min
Operating hours and holidays	Location	Required at setup
Service buffer/cleanup time	Brand/service	Per service
Allow staff double-booking override	Brand/Location	Off
Allow out-of-shift override	Brand/Location	Off
Parallel services	Brand	Off
Stylist self-service edit rights	Brand	Off
No-show policy	Brand	None

Key Data Entities

• Appointment — the visit record (client, location, status, notes, deposit state)
• AppointmentService — each service leg (staff, resource, duration, service reference)
• QueueEntry — walk-in record and lifecycle
• CalendarBlock — non-bookable time block
• Shift — staff working hours for a day
• Resource — physical room, chair, station, or equipment unit