Lego Block

Scheduling & Booking

Calendar management and appointment booking system with availability management, buffer time rules, conflict detection, and automated notifications.

Smart Availability
Multi-Resource
Auto Notifications
Get This BlockView All Blocks

Overview & Scope

A production-ready appointment scheduling system that handles availability management, conflict detection, and customer notifications with buffer time enforcement and resource allocation.

Must-Have Features

  • Create appointment types with duration, buffer times, and resource requirements
  • Define provider availability with recurring schedules and time-off overrides
  • Search available time slots with conflict detection and buffer enforcement
  • Book appointments with customer details and automated confirmation
  • Send email/SMS notifications for confirmations, reminders, and cancellations
  • Handle cancellations and rescheduling with conflict checks

Nice-to-Have Features

  • Multi-resource booking (e.g., room + equipment + staff)
  • Recurring appointment series with exception handling
  • Waitlist management for fully booked time slots
  • Calendar sync integration (Google Calendar, Outlook)
  • Timezone-aware scheduling for distributed teams
  • Analytics dashboard for booking metrics and utilization

Three-Tier Architecture

A scalable architecture with React frontend for booking UI, Spring Boot backend for business logic, and PostgreSQL for reliable data persistence with timezone support.

Frontend Layer

  • •React calendar UI with month/week/day views
  • •Time slot picker with availability visualization
  • •Booking form with customer information
  • •Appointment management dashboard
  • •Responsive design for mobile booking

Backend Layer

  • •Spring Boot REST API with JPA/Hibernate
  • •Availability calculation engine
  • •Conflict detection and buffer time validation
  • •Notification service (email/SMS via SendGrid/Twilio)
  • •Timezone conversion utilities

Data Layer

  • •PostgreSQL for appointment and availability data
  • •Indexed queries for slot search performance
  • •Transactional booking with optimistic locking
  • •Audit trail for booking history
  • •Notification queue table for async delivery

Core Concepts

Understanding appointment types, availability schedules, time-off management, and conflict detection rules that power the booking engine.

Appointment Types

  • name: String (e.g., 'Initial Consultation', 'Follow-up Visit')
  • duration: Integer (minutes, e.g., 30, 60)
  • bufferBefore: Integer (minutes before appointment, default 0)
  • bufferAfter: Integer (minutes after appointment, default 0)
  • resourceRequirements: List<String> (e.g., ['room', 'equipment'])
  • price: Decimal (optional for paid appointments)

Provider Availability

  • providerId: UUID (doctor, consultant, resource)
  • dayOfWeek: Enum (MONDAY-SUNDAY)
  • startTime: Time (e.g., '09:00')
  • endTime: Time (e.g., '17:00')
  • timezone: String (e.g., 'America/New_York')
  • effectiveFrom/Until: Date (optional recurring schedule bounds)

Time-Off Overrides

  • providerId: UUID
  • date: Date (specific day unavailable)
  • startTime/endTime: Time (optional partial day off)
  • reason: String (e.g., 'Vacation', 'Conference')
  • These override recurring availability for specific dates

Conflict Detection

  • Check overlapping appointments for same provider/resource
  • Enforce buffer time before and after appointments
  • Validate against time-off overrides
  • Ensure booking falls within availability hours
  • Handle timezone conversions for distributed teams
  • Use database constraints + optimistic locking for concurrency
PostgreSQL Schema

Database Schema

Five core tables for managing appointment types, availability schedules, time-off, bookings, and notification delivery with proper indexes for performance.

appointment_types

Service definitions with duration and buffer settings

id: UUID PRIMARY KEY
organization_id: UUID (multi-tenant support)
name: VARCHAR(255) NOT NULL
description: TEXT
duration_minutes: INTEGER NOT NULL
buffer_before_minutes: INTEGER DEFAULT 0
buffer_after_minutes: INTEGER DEFAULT 0
price: DECIMAL(10,2)
is_active: BOOLEAN DEFAULT true
created_at: TIMESTAMP

provider_availability

Recurring weekly schedules for providers

id: UUID PRIMARY KEY
provider_id: UUID NOT NULL
day_of_week: VARCHAR(10) NOT NULL (MONDAY-SUNDAY)
start_time: TIME NOT NULL
end_time: TIME NOT NULL
timezone: VARCHAR(50) NOT NULL
effective_from: DATE
effective_until: DATE
created_at: TIMESTAMP
INDEX idx_provider_day (provider_id, day_of_week)

time_off

Specific date/time overrides for unavailability

id: UUID PRIMARY KEY
provider_id: UUID NOT NULL
date: DATE NOT NULL
start_time: TIME (null = all day)
end_time: TIME (null = all day)
reason: VARCHAR(255)
created_at: TIMESTAMP
INDEX idx_provider_date (provider_id, date)

appointments

Booked appointments with customer details

id: UUID PRIMARY KEY
appointment_type_id: UUID NOT NULL
provider_id: UUID NOT NULL
customer_name: VARCHAR(255) NOT NULL
customer_email: VARCHAR(255) NOT NULL
customer_phone: VARCHAR(50)
start_time: TIMESTAMP NOT NULL
end_time: TIMESTAMP NOT NULL
timezone: VARCHAR(50) NOT NULL
status: VARCHAR(20) (CONFIRMED, CANCELLED, COMPLETED)
notes: TEXT
created_at: TIMESTAMP
version: INTEGER (optimistic locking)
INDEX idx_provider_time (provider_id, start_time, end_time)

notifications

Queue for email/SMS notifications

id: UUID PRIMARY KEY
appointment_id: UUID NOT NULL
type: VARCHAR(20) (CONFIRMATION, REMINDER, CANCELLATION)
recipient: VARCHAR(255) NOT NULL
channel: VARCHAR(10) (EMAIL, SMS)
status: VARCHAR(20) (PENDING, SENT, FAILED)
sent_at: TIMESTAMP
error_message: TEXT
created_at: TIMESTAMP

Availability Calculation

Four-step algorithm for finding available time slots that respects recurring schedules, time-off, existing appointments, and buffer time requirements.

Step 1

Load Recurring Schedule

Query provider_availability for the requested date's day of week and timezone

Step 2

Apply Time-Off Overrides

Check time_off table for any blocks on the specific date and exclude those time ranges

Step 3

Fetch Existing Appointments

Query appointments table for all bookings on that date, including buffer time before/after each appointment

Step 4

Generate Available Slots

Create time slots based on appointment_type duration, then filter out conflicts with existing bookings and buffer times

Example Calculation


// Example: Find available slots for 30-min appointment on Jan 15, 2025
// Provider works 9:00 AM - 5:00 PM
// Has appointments: 10:00-10:30 (buffer: 0), 2:00-3:00 (buffer: 15 min after)

Available Slots:
  9:00 AM, 9:30 AM,         // Morning slots
  10:30 AM, 11:00 AM, ...,  // After first appointment
  12:30 PM, 1:00 PM, 1:30 PM, // Lunch slots
  3:15 PM, 3:45 PM, 4:15 PM  // After second appointment + buffer

Unavailable:
  10:00 AM (existing appointment)
  2:00 PM - 3:15 PM (appointment + 15 min buffer)
  4:45 PM (would end at 5:15 PM, past end time)

Booking & Cancellation Logic

Four-step transactional booking flow with optimistic locking, notification queueing, and cancellation handling with business rule enforcement.

Step 1

Validate & Lock

Check slot availability, validate no conflicts, and use optimistic locking (version field) to prevent double-booking during concurrent requests

Step 2

Create Appointment

Insert appointment record with customer details, calculate end_time from start_time + duration, set status to CONFIRMED

Step 3

Queue Notifications

Insert notification records for confirmation email/SMS, schedule reminder notifications for 24 hours before appointment

Step 4

Handle Cancellations

Update appointment status to CANCELLED, queue cancellation notifications, free up the time slot for rebooking

Business Rules

  • No double-booking: Use database unique constraint on (provider_id, start_time) and version field for optimistic locking
  • Buffer enforcement: Validate requested time doesn't violate buffer_before/buffer_after of adjacent appointments
  • Timezone handling: Store all times in UTC, convert to provider/customer timezone for display
  • Cancellation policy: Allow cancellations up to X hours before appointment (configurable)
  • Rescheduling: Treat as cancel + new booking with conflict checks
  • Waitlist: If slot full, optionally add to waitlist table and notify when slot opens
REST API

API Endpoints

Seven REST endpoints for managing appointment types, availability, time-off, slot search, booking, and cancellation operations.

POST
/api/appointment-types

Create appointment type with duration and buffer settings

{
  "name": "Initial Consultation",
  "duration_minutes": 60,
  "buffer_before_minutes": 0,
  "buffer_after_minutes": 15,
  "price": 150.00
}
POST
/api/providers/{id}/availability

Set recurring availability schedule for provider

{
  "day_of_week": "MONDAY",
  "start_time": "09:00",
  "end_time": "17:00",
  "timezone": "America/New_York"
}
POST
/api/providers/{id}/time-off

Block specific date/time for provider unavailability

{
  "date": "2025-01-20",
  "start_time": "14:00",
  "end_time": "17:00",
  "reason": "Conference"
}
GET
/api/appointments/available-slots

Search available time slots for booking

?provider_id=uuid&appointment_type_id=uuid&date=2025-01-15&timezone=America/New_York
POST
/api/appointments

Book appointment with customer details

{
  "appointment_type_id": "uuid",
  "provider_id": "uuid",
  "start_time": "2025-01-15T10:00:00Z",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "customer_phone": "+1234567890"
}
PUT
/api/appointments/{id}/cancel

Cancel appointment and send notifications

{
  "reason": "Customer request"
}
GET
/api/appointments/{id}

Get appointment details

Returns appointment with customer info, provider, type

Optional React UI

Four primary UI components for calendar viewing, customer booking, provider management, and admin configuration with responsive design.

Calendar View

Month/week/day calendar display showing all appointments with color coding by status

  • •Interactive calendar with date picker
  • •Filter by provider and appointment type
  • •Click appointment to view details
  • •Drag-and-drop for rescheduling (optional)

Booking Widget

Public-facing booking form for customers to schedule appointments

  • •Select appointment type and provider
  • •Choose date and view available time slots
  • •Enter customer information
  • •Confirm booking and receive confirmation email

Provider Management

Admin interface for managing providers and their availability

  • •Add/edit provider profiles
  • •Set recurring availability schedules
  • •Block time-off dates
  • •View provider utilization metrics

Admin Dashboard

Configuration interface for appointment types and system settings

  • •Create/edit appointment types
  • •Configure buffer times and pricing
  • •View booking analytics and reports
  • •Manage notification templates

Production Benefits

A battle-tested scheduling system with conflict prevention, automated notifications, and timezone support ready for production deployment.

Key Benefits

  • No double-booking conflicts with optimistic locking and database constraints
  • Buffer time enforcement prevents back-to-back scheduling issues
  • Timezone-aware scheduling for distributed teams and global customers
  • Automated email/SMS notifications for confirmations, reminders, and cancellations
  • Flexible availability management with recurring schedules and time-off overrides
  • Fast slot search with indexed queries and efficient conflict detection
  • Multi-tenant ready with organization_id isolation
  • Audit trail for booking history and cancellation reasons

Done Criteria

  • Appointment types created with duration, buffer times, and pricing
  • Provider availability schedules configured with timezone support
  • Time-off blocking working for specific dates and times
  • Slot search API returns accurate available times with conflict checking
  • Booking API validates conflicts, creates appointment, and queues notifications
  • Cancellation API updates status and sends notifications
  • Email/SMS notifications sent via SendGrid/Twilio integration
  • React UI (optional) for calendar view, booking widget, and admin management

Build Your Next Product With AI Expertise

Experience the future of software development. Let our GenAI platform accelerate your next project.

Schedule a Free AI Blueprint Session