Design Calendly: System Design & Architecture

PostgreSQL tables

- Users
  user_id UUID PRIMARY KEY,
  username VARCHAR(50) UNIQUE NOT NULL, -- public handle, e.g. calendly.com/jane
  email VARCHAR(255) UNIQUE NOT NULL,
  time_zone VARCHAR(50) DEFAULT 'UTC',
  availability_rules JSONB, -- the host's available time blocks
  calendar_connections JSONB, -- encrypted Google/Outlook OAuth tokens
  booking_preferences JSONB, -- min notice, max future booking
  created_at TIMESTAMP DEFAULT NOW()
  -- username & email are UNIQUE, so Postgres already indexes them

- Bookings
  booking_id UUID PRIMARY KEY,
  host_id UUID REFERENCES users(user_id),
  guest_email VARCHAR(255) NOT NULL,
  guest_name VARCHAR(255),
  guest_timezone VARCHAR(50),
  guest_answers JSONB, -- responses to the host's intake questions
  start_time TIMESTAMP WITH TIME ZONE,
  end_time TIMESTAMP WITH TIME ZONE,
  status booking_status_enum DEFAULT 'confirmed', -- confirmed, cancelled
  calendar_event_ids JSONB, -- external calendar event references
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(), -- updated on cancel

  INDEX idx_host_bookings ON (host_id, start_time)
  -- DB-level safety net: two CONFIRMED bookings for the same host
  -- can never overlap in time, even if the Redis hold check is bypassed
  EXCLUDE USING gist (
    host_id WITH =,
    tstzrange(start_time, end_time) WITH &&
  ) WHERE (status = 'confirmed')

- Calendar Events  -- external busy times imported for conflict checks
  event_id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(user_id),
  external_event_id VARCHAR(255), -- Google/Outlook event ID
  provider calendar_provider_enum, -- google, outlook, apple
  start_time TIMESTAMP WITH TIME ZONE, -- busy block start
  end_time TIMESTAMP WITH TIME ZONE,   -- busy block end
  last_synced TIMESTAMP DEFAULT NOW(),

  UNIQUE(user_id, external_event_id, provider)
  INDEX idx_busy_times ON (user_id, start_time, end_time)

- Sync Jobs (pending calendar syncs)
  job_id UUID PRIMARY KEY,
  booking_id UUID REFERENCES bookings(booking_id),
  job_type VARCHAR(20), -- push_event, cancel_event
  status VARCHAR(20) DEFAULT 'pending', -- pending, done, failed
  attempts INT DEFAULT 0,
  next_attempt_at TIMESTAMP, -- backoff schedule for retries
  created_at TIMESTAMP DEFAULT NOW(),

  INDEX idx_pending_jobs ON (status, next_attempt_at) -- workers poll this

Redis keys

- Availability Cache
  Key: "avail:{user_id}:{date}"
  Value: ["09:00-09:30", "10:00-10:30", "14:00-14:30"]
  TTL: 24 hours

- Booking Holds
  Key: "hold:{host_id}:{start_time}" -- keyed by host so the host can't be double-booked for that slot
  Value: {"hold_id": "hold_8f3e2d1c", "guest_email": "client@example.com"}
  TTL: 2 minutes (auto-expires if the guest does not confirm)