Specialist Schedule Management on Website

Implementing Specialist Schedule Management on a Website

Schedule management is a tool for specialists and administrators: set working hours, add a day off, block time for a meeting, see who booked next week. Schedule must be flexible and not require developer involvement for each change.

Schedule Levels

Schedule is built from three layers, each overriding the previous:

1. Base Template — standard working hours by day of week:

Mon–Fri: 09:00–18:00, 60 min slots, 0 min break
Sat: 10:00–14:00, 30 min slots
Sun: off

2. Date Overrides — specific date works differently:

2025-05-09: day off (holiday)
2025-06-01: 10:00–16:00 (short day)
2025-07-01–2025-07-14: vacation

3. Blocks — closed intervals within working hours:

2025-04-15 12:00–13:00: lunch
2025-04-16 14:00–15:00: meeting

Specialist Management Interface

Specialist manages schedule through personal account. Key operations:

API Endpoints

GET  /api/specialists/{id}/schedule?date=2025-04-15
     → { slots: [...], overrides: [...], blocks: [...] }

GET  /api/specialists/{id}/available-slots?from=2025-04-15&to=2025-04-21
     → { "2025-04-15": [{ start, end }], ... }

POST /api/specialists/{id}/overrides
     { override_date: "2025-05-01", type: "day_off" }

POST /api/specialists/{id}/blocks
     { starts_at: "2025-04-16T14:00", ends_at: "2025-04-16T15:00", reason: "Meeting" }

DELETE /api/specialists/{id}/overrides/{override_id}
DELETE /api/specialists/{id}/blocks/{block_id}

PATCH /api/specialists/{id}/schedule/{weekday}
      { start_time: "10:00", end_time: "18:00", slot_duration: 45 }

Mass Changes (Vacation, Holidays)

Two-week vacation — not 14 separate records, but one with date range:

CREATE TABLE specialist_overrides (
    id              SERIAL PRIMARY KEY,
    specialist_id   INTEGER NOT NULL,
    date_from       DATE NOT NULL,
    date_until      DATE NOT NULL,   -- inclusive
    override_type   VARCHAR(20) NOT NULL,  -- 'day_off' | 'vacation' | 'custom_hours'
    start_time      TIME,            -- only for custom_hours
    end_time        TIME,
    created_by      INTEGER,         -- who created: specialist or admin
    reason          VARCHAR(255)
);

When generating slots, ranges are expanded into separate days in code, not in DB.

Automatic Holidays

Setting: when creating a schedule, enable "auto-close state holidays". Holiday list loads via API (e.g., calendarific.com) or stored in settings table with annual update:

def populate_holidays(country: str, year: int):
    resp = requests.get(
        'https://calendarific.com/api/v2/holidays',
        params={'api_key': API_KEY, 'country': country, 'year': year, 'type': 'national'}
    )
    holidays = resp.json()['response']['holidays']
    for h in holidays:
        db.execute("""
            INSERT INTO public_holidays (country, date, name)
            VALUES (%s, %s, %s)
            ON CONFLICT DO NOTHING
        """, [country, h['date']['iso'], h['name']])

Change Notifications

When specialist closes a date with existing bookings — system automatically:

1. Finds all active bookings for closed period
2. Sends clients apology email with rescheduling offer
3. Moves bookings to needs_reschedule status
4. Notifies admin

def close_date(specialist_id: int, date: date, reason: str):
    affected_bookings = get_bookings_for_date(specialist_id, date)

    with db.transaction():
        create_override(specialist_id, date, 'day_off', reason=reason)
        for booking in affected_bookings:
            update_booking_status(booking.id, 'needs_reschedule')
            send_reschedule_request_email(booking, specialist_id, reason)
            notify_admin(specialist_id, booking, 'date_closed')

Export to External Calendars

Specialist can sync schedule with Google Calendar or Outlook via iCal feed:

GET /api/specialists/{id}/calendar.ics?token={private_token}

This URL is added to Google Calendar as subscription — updates every 15 minutes automatically.

Implementation Timeline

Basic template schedule and block management, no external integrations — 5–7 business days. Range overrides, auto-holidays, client notifications on close, iCal export, role-based access (specialist vs admin) — 9–12 business days.