# Use Cases — Calendar Booking Platform

**Version:** 1.0  
**Last updated:** June 25, 2026  
**Scope:** All functional use cases for the Calendly-style scheduling solution (Node.js + Angular + MySQL)

---

## Table of Contents

1. [Overview](#1-overview)
2. [Actors](#2-actors)
3. [Use Case Map](#3-use-case-map)
4. [Host Use Cases](#4-host-use-cases)
5. [Guest Use Cases](#5-guest-use-cases)
6. [Third-Party / Embed Use Cases](#6-third-party--embed-use-cases)
7. [Calendar Integration Use Cases](#7-calendar-integration-use-cases)
8. [Notification Use Cases](#8-notification-use-cases)
9. [Platform Admin Use Cases](#9-platform-admin-use-cases)
10. [System Use Cases](#10-system-use-cases)
11. [Use Case Traceability Matrix](#11-use-case-traceability-matrix)

---

## 1. Overview

This document lists **every use case** supported by the calendar booking platform. Each use case follows a standard structure:

| Field | Description |
|-------|-------------|
| **ID** | Unique identifier (e.g. UC-HOST-01) |
| **Title** | Short name |
| **Actor(s)** | Primary user or system role |
| **Priority** | Must Have (M) / Should Have (S) / Could Have (C) / Future (F) |
| **Description** | What the actor wants to achieve |
| **Preconditions** | State required before the use case starts |
| **Main Flow** | Happy-path steps |
| **Alternative Flows** | Variations and error paths |
| **Postconditions** | State after successful completion |

---

## 2. Actors

| Actor | Description |
|-------|-------------|
| **Host** | Registered user who defines availability, connects calendars, and receives bookings |
| **Guest** | Unauthenticated visitor who books time via a public or embedded link |
| **Partner Developer** | Third-party website or application owner who embeds the booking widget |
| **Platform Admin** | Internal operator managing users, abuse, and system health |
| **System** | Automated processes (background jobs, sync workers, schedulers) |
| **Calendar Provider** | External system — Google Calendar, Microsoft Graph, Apple iCloud CalDAV |

---

## 3. Use Case Map

```mermaid
flowchart TB
    subgraph Host
        H1[Register & Login]
        H2[Manage Profile]
        H3[Set Availability]
        H4[Manage Event Types]
        H5[Connect Calendars]
        H6[Manage Bookings]
        H7[Configure Embed]
        H8[View Analytics]
    end

    subgraph Guest
        G1[View Public Page]
        G2[Book Slot]
        G3[Cancel Booking]
        G4[Reschedule Booking]
    end

    subgraph Partner
        P1[Embed Widget]
        P2[Receive postMessage]
        P3[Server API Integration]
    end

    subgraph System
        S1[Sync Free/Busy]
        S2[Push Calendar Events]
        S3[Send Notifications]
        S4[Refresh OAuth Tokens]
    end

    G2 --> S2
    G2 --> S3
    H5 --> S1
    P1 --> G2
```

---

## 4. Host Use Cases

### UC-HOST-01 — Register Account

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | A new user creates an account to start offering bookable time slots. |

**Preconditions:** User is not logged in. Email is not already registered.

**Main Flow:**
1. Host navigates to the registration page.
2. Host enters email, password, full name, username, and timezone.
3. System validates input (unique email, unique username, password strength, valid IANA timezone).
4. System creates user record in MySQL.
5. System sends email verification link.
6. System displays success message and prompts login.

**Alternative Flows:**
- **A1 — Email already exists:** System shows error; host is offered login or password reset.
- **A2 — Username taken:** System suggests alternatives.
- **A3 — Invalid timezone:** System rejects with validation message.

**Postconditions:** User record exists with `email_verified = false`. Default availability schedule may be created empty.

---

### UC-HOST-02 — Verify Email

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host confirms ownership of email address. |

**Preconditions:** User registered; verification email sent.

**Main Flow:**
1. Host clicks verification link in email.
2. System validates token (not expired, matches user).
3. System sets `email_verified = true`.
4. System redirects to login or dashboard.

**Alternative Flows:**
- **A1 — Token expired:** System offers resend verification email.
- **A2 — Already verified:** System redirects to dashboard.

**Postconditions:** Email marked verified.

---

### UC-HOST-03 — Login

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host authenticates to access the dashboard. |

**Preconditions:** Account exists.

**Main Flow:**
1. Host enters email and password.
2. System validates credentials (bcrypt/argon2 compare).
3. System issues JWT access token.
4. Angular app stores token and loads user profile into NgRx auth state.
5. Host is redirected to dashboard.

**Alternative Flows:**
- **A1 — Invalid credentials:** Generic error message (no email enumeration).
- **A2 — Email not verified:** Prompt to verify; option to resend.
- **A3 — Account suspended:** Access denied with support contact.

**Postconditions:** Host session active; dashboard accessible.

---

### UC-HOST-04 — Logout

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host ends session securely. |

**Main Flow:**
1. Host clicks Logout.
2. Angular clears token from storage and NgRx auth state.
3. Host redirected to login page.

**Postconditions:** No active session on client.

---

### UC-HOST-05 — Update Profile

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host updates display name, timezone, or avatar. |

**Preconditions:** Host is logged in.

**Main Flow:**
1. Host opens Settings → Profile.
2. Host modifies full name, timezone, and/or avatar URL.
3. System validates and saves to MySQL.
4. Public booking page reflects updated name and avatar.

**Alternative Flows:**
- **A1 — Timezone changed:** Availability recalculated; existing bookings unchanged (stored in UTC).

**Postconditions:** Profile updated. Username change (if supported) updates public URL slug.

---

### UC-HOST-06 — Change Password

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host updates account password. |

**Main Flow:**
1. Host enters current password and new password.
2. System validates current password and new password policy.
3. System hashes and stores new password.

**Alternative Flows:**
- **A1 — Wrong current password:** Error shown.

**Postconditions:** New password required for next login.

---

### UC-HOST-07 — Request Password Reset

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host recovers access when password is forgotten. |

**Main Flow:**
1. Host requests reset via email.
2. System sends time-limited reset link (always returns success to prevent enumeration).
3. Host clicks link and sets new password.

**Postconditions:** Password updated; reset token invalidated.

---

### UC-HOST-08 — Configure Weekly Working Hours

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host defines recurring weekly availability in their timezone. |

**Preconditions:** Host logged in; timezone set.

**Main Flow:**
1. Host opens Settings → Availability.
2. Host sets available days with start/end times (multiple intervals per day supported).
3. Host sets minimum notice (e.g. 4 hours) and max advance days (e.g. 60).
4. System saves `weekly_rules` JSON to MySQL.
5. System invalidates availability cache in Redis.

**Alternative Flows:**
- **A1 — Day marked unavailable:** No intervals for that dayOfWeek.
- **A2 — Overlapping intervals on same day:** System merges or rejects with validation error.

**Postconditions:** Public slots reflect new working hours.

---

### UC-HOST-09 — Add Date Override (Holiday / Special Hours)

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host blocks or customizes availability for a specific date. |

**Main Flow:**
1. Host selects a date on the availability calendar.
2. Host chooses "Unavailable all day" or "Custom hours."
3. System saves row in `availability_date_overrides`.
4. Availability cache invalidated.

**Postconditions:** That date uses override instead of weekly rules.

---

### UC-HOST-10 — Remove Date Override

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host reverts a specific date to default weekly schedule. |

**Main Flow:**
1. Host deletes override for a date.
2. System removes override record.
3. Weekly rules apply again for that date.

**Postconditions:** Date follows weekly schedule.

---

### UC-HOST-11 — Create Event Type

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host defines a bookable meeting type with duration and rules. |

**Main Flow:**
1. Host opens Event Types → New.
2. Host enters title, URL slug, duration, buffers, location, description, custom questions, color.
3. System validates unique slug per user.
4. System saves to `event_types`.
5. System displays public URL: `/book/{username}/{slug}`.

**Postconditions:** Event type active; public link shareable.

---

### UC-HOST-12 — Update Event Type

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host modifies an existing event type. |

**Main Flow:**
1. Host edits event type fields.
2. System saves changes.
3. Existing confirmed bookings retain original duration; new bookings use updated settings.

**Postconditions:** Event type updated.

---

### UC-HOST-13 — Deactivate / Delete Event Type

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host stops accepting new bookings for an event type. |

**Main Flow:**
1. Host deactivates or deletes event type.
2. If future bookings exist, system soft-deletes (`is_active = false`).
3. Public page returns 404 for inactive types.

**Postconditions:** No new bookings; existing bookings preserved.

---

### UC-HOST-14 — View Public Booking Link

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host copies shareable URL for an event type. |

**Main Flow:**
1. Host opens event type detail.
2. System displays full public URL and copy button.
3. Host copies link for email, website, or social media.

**Postconditions:** Link ready to share.

---

### UC-HOST-15 — Connect Google Calendar

| Field | Value |
|-------|-------|
| **Actor** | Host, Calendar Provider |
| **Priority** | M |
| **Description** | Host links Google account for conflict detection and event creation. |

**Main Flow:**
1. Host clicks Connect Google Calendar.
2. System redirects to Google OAuth consent.
3. Host approves permissions.
4. System exchanges code for access + refresh tokens.
5. System encrypts and stores tokens in `calendar_connections`.
6. System fetches calendar list; host selects conflict calendars and write target.
7. System triggers initial free/busy sync job.

**Alternative Flows:**
- **A1 — OAuth denied:** Connection not created; host returned to settings.
- **A2 — Token refresh fails later:** UC-SYS-04 applies.

**Postconditions:** Google connection active; busy blocks imported.

---

### UC-HOST-16 — Connect Microsoft Outlook / 365 Calendar

| Field | Value |
|-------|-------|
| **Actor** | Host, Calendar Provider |
| **Priority** | M |
| **Description** | Host links Microsoft account via Graph API OAuth. |

**Main Flow:** Same as UC-HOST-15 via Microsoft identity platform.

**Postconditions:** Microsoft connection active.

---

### UC-HOST-17 — Connect Apple iCloud Calendar

| Field | Value |
|-------|-------|
| **Actor** | Host, Calendar Provider |
| **Priority** | M |
| **Description** | Host connects Apple calendar via CalDAV and app-specific password. |

**Main Flow:**
1. Host enters Apple ID and app-specific password.
2. System validates CalDAV credentials against iCloud.
3. System discovers calendars via PROPFIND.
4. Host selects conflict and write calendars.
5. System stores encrypted credentials; starts polling sync.

**Alternative Flows:**
- **A1 — Invalid credentials:** Error with link to Apple ID app-password help.

**Postconditions:** Apple connection active.

---

### UC-HOST-18 — Select Calendars for Conflict Check

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host chooses which external calendars block availability. |

**Main Flow:**
1. Host toggles `checkConflicts` per calendar in connection settings.
2. System updates `calendar_config` JSON.
3. System re-syncs free/busy for selected calendars.

**Postconditions:** Only selected calendars affect slot availability.

---

### UC-HOST-19 — Select Write-Target Calendar

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host designates one calendar where new bookings are created. |

**Main Flow:**
1. Host sets `writeTarget: true` on exactly one calendar.
2. System enforces single write target across all connections.

**Postconditions:** New bookings sync to designated calendar.

---

### UC-HOST-20 — Disconnect Calendar

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host removes a calendar connection. |

**Main Flow:**
1. Host clicks Disconnect.
2. System revokes token at provider (where supported).
3. System deletes encrypted credentials; marks connection disconnected.
4. Existing booking records and past sync IDs retained.

**Postconditions:** No further sync from that provider; availability no longer blocked by its events.

---

### UC-HOST-21 — View Upcoming Bookings

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host sees list of confirmed and pending appointments. |

**Main Flow:**
1. Host opens Dashboard → Bookings.
2. System queries MySQL for bookings in date range.
3. Angular NgRx loads data; list shows guest, time, event type, status, embed source.

**Postconditions:** Host informed of schedule.

---

### UC-HOST-22 — View Booking Detail

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host inspects full details of a single booking. |

**Main Flow:**
1. Host clicks a booking.
2. System shows guest info, custom answers, timezone, calendar sync status.

**Postconditions:** —

---

### UC-HOST-23 — Cancel Booking (Host-Initiated)

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host cancels an appointment; guest is notified. |

**Preconditions:** Booking status is `confirmed` or `pending`.

**Main Flow:**
1. Host clicks Cancel and optionally enters reason.
2. System sets booking status to `cancelled`.
3. System queues job to delete external calendar events (UC-SYS-06).
4. System sends cancellation emails to guest and host (UC-NOTIF-03).
5. Slot becomes available again.

**Postconditions:** Booking cancelled; calendars updated.

---

### UC-HOST-24 — Reschedule Booking (Host-Initiated)

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host moves a booking to a new time slot. |

**Main Flow:**
1. Host selects new available slot.
2. System validates no conflicts (same rules as new booking).
3. System updates `start_time` / `end_time` in transaction.
4. System updates external calendar events.
5. System notifies guest and host of new time.

**Alternative Flows:**
- **A1 — New slot unavailable:** 409 error; host picks another slot.

**Postconditions:** Booking at new time; calendars synced.

---

### UC-HOST-25 — Export Bookings

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | S |
| **Description** | Host downloads bookings as CSV for reporting. |

**Main Flow:**
1. Host selects date range and clicks Export.
2. System generates CSV with guest name, email, time, event type, status.

**Postconditions:** File downloaded.

---

### UC-HOST-26 — Create Embed Configuration

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host generates embed settings to place booking widget on external websites. |

**Main Flow:**
1. Host opens Embed Settings.
2. Host selects event type, display mode (inline / popup / modal), allowed origins, theme colors.
3. System creates `embed_configs` row with unique `embed_key`.
4. System displays script snippet and iframe URL.

**Postconditions:** Embed key active; partner sites can embed widget.

---

### UC-HOST-27 — Update Embed Configuration

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host modifies allowed origins, theme, or display mode. |

**Main Flow:**
1. Host edits embed config.
2. System saves changes.
3. Widget loads updated theme on next fetch.

**Postconditions:** Embed behavior updated.

---

### UC-HOST-28 — Deactivate Embed Configuration

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host disables embedding for an event type. |

**Main Flow:**
1. Host deactivates embed config.
2. API returns 404 for embed key.
3. Third-party widgets show error or fallback message.

**Postconditions:** Embedding disabled.

---

### UC-HOST-29 — Create API Key

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | S |
| **Description** | Host creates server-to-server API key for integrations. |

**Main Flow:**
1. Host creates API key with name and scopes.
2. System generates key, stores hash only, displays full key once.
3. Host copies key for partner backend use.

**Postconditions:** API key usable until revoked or expired.

---

### UC-HOST-30 — Revoke API Key

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | S |
| **Description** | Host invalidates an API key. |

**Main Flow:**
1. Host revokes key.
2. System deletes or deactivates key record.

**Postconditions:** Key no longer accepted.

---

### UC-HOST-31 — View Dashboard Analytics

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | S |
| **Description** | Host views booking metrics and trends. |

**Main Flow:**
1. Host opens Dashboard.
2. System aggregates: total bookings, upcoming count, cancellation rate, top event types, embed vs direct bookings.

**Postconditions:** —

---

### UC-HOST-32 — Reconnect Expired Calendar

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host restores calendar sync after token expiry. |

**Preconditions:** Connection status is `expired` or `error`.

**Main Flow:**
1. Host receives email alert about sync failure.
2. Host opens Calendars settings and clicks Reconnect.
3. OAuth flow repeats (or Apple credentials re-entered).
4. System resumes sync jobs.

**Postconditions:** Connection `connected`; sync resumed.

---

### UC-HOST-33 — Delete Account (GDPR)

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | S |
| **Description** | Host permanently deletes account and personal data. |

**Main Flow:**
1. Host requests account deletion.
2. System cancels future bookings and notifies guests.
3. System revokes calendar tokens.
4. System anonymizes or deletes user PII per retention policy.

**Postconditions:** Account removed; public links inactive.

---

### UC-HOST-34 — Export Personal Data (GDPR)

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | S |
| **Description** | Host downloads all stored personal data. |

**Main Flow:**
1. Host requests data export.
2. System packages profile, bookings, calendar connection metadata (no raw tokens).
3. System delivers JSON/ZIP download or email link.

**Postconditions:** Export delivered.

---

## 5. Guest Use Cases

### UC-GUEST-01 — Open Public Booking Page

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest accesses host's booking page via shared link. |

**Preconditions:** Event type is active; host account exists.

**Main Flow:**
1. Guest opens `https://book.example.com/book/{username}/{event-slug}`.
2. Angular public-booking app dispatches `loadEventPage`.
3. Node API returns host name, avatar, event title, duration, description, custom questions.
4. Page renders with timezone selector defaulting to browser timezone.

**Alternative Flows:**
- **A1 — Invalid username or slug:** 404 page.
- **A2 — Inactive event type:** 404 or "not available" message.

**Postconditions:** Guest sees booking UI.

---

### UC-GUEST-02 — Select Timezone

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest views available slots in their local timezone. |

**Main Flow:**
1. Guest selects timezone from dropdown.
2. NgRx updates `guestTimezone` state.
3. System re-fetches or reformats displayed slots.

**Postconditions:** All times labeled with selected timezone.

---

### UC-GUEST-03 — Browse Available Dates

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest picks a date that has at least one free slot. |

**Main Flow:**
1. Guest views calendar month view.
2. System loads slots for date range via `GET /public/.../slots`.
3. Dates with zero slots appear disabled or hidden.

**Postconditions:** Guest selects a valid date.

---

### UC-GUEST-04 — View Available Time Slots

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest sees free times for selected date. |

**Main Flow:**
1. Guest selects date.
2. System computes availability: working hours − bookings − external busy − buffers − min notice.
3. Slot list displayed in guest timezone.

**Alternative Flows:**
- **A1 — No slots:** Message "No times available"; suggest another date.

**Postconditions:** Guest can select a slot.

---

### UC-GUEST-05 — Book a Time Slot

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest confirms appointment with contact details. |

**Preconditions:** Slot selected; slot still available.

**Main Flow:**
1. Guest enters name, email, optional phone, custom question answers.
2. Guest submits form.
3. Angular dispatches `submitBooking` with `Idempotency-Key`.
4. Node validates slot in DB transaction (pessimistic lock).
5. System creates booking record with status `confirmed`.
6. System queues calendar event creation and confirmation email.
7. Guest sees confirmation page with meeting details.

**Alternative Flows:**
- **A1 — Slot taken (race):** 409 error; guest prompted to pick another slot.
- **A2 — Validation error:** Inline field errors shown.
- **A3 — Rate limited:** 429; retry after cooldown.

**Postconditions:** Booking confirmed; host calendar updated; emails sent.

---

### UC-GUEST-06 — Download Calendar Invite (.ics)

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest adds meeting to personal calendar. |

**Main Flow:**
1. On confirmation page or email, guest clicks Download .ics or Add to Calendar.
2. System serves ICS file with UTC times, organizer, attendee, location.

**Postconditions:** Guest can import into Google, Outlook, or Apple Calendar.

---

### UC-GUEST-07 — Receive Booking Confirmation Email

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest gets email proof of booking. |

**Main Flow:**
1. System sends email with date/time, timezone, location, host name, cancel link, .ics attachment.

**Postconditions:** Guest has record of appointment.

---

### UC-GUEST-08 — Cancel Booking (Guest-Initiated)

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest cancels via link in confirmation email. |

**Preconditions:** Booking confirmed; within host cancellation policy (if enforced).

**Main Flow:**
1. Guest opens `/cancel/{token}`.
2. System validates signed cancel token.
3. Guest confirms cancellation.
4. System sets status `cancelled`; frees slot; deletes calendar events; sends emails.

**Alternative Flows:**
- **A1 — Past cancellation deadline:** Error with host contact info.
- **A2 — Already cancelled:** Informational message.

**Postconditions:** Booking cancelled.

---

### UC-GUEST-09 — Reschedule Booking (Guest-Initiated)

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | S |
| **Description** | Guest moves appointment to another available slot. |

**Main Flow:**
1. Guest opens reschedule link from email.
2. Guest picks new slot (same flow as UC-GUEST-04/05).
3. System updates booking; syncs calendars; notifies host.

**Alternative Flows:**
- **A1 — Reschedule not allowed by policy:** Error shown.

**Postconditions:** Booking at new time.

---

### UC-GUEST-10 — Receive Reminder Email

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | S |
| **Description** | Guest gets reminder before meeting (24h / 1h). |

**Main Flow:**
1. System cron finds upcoming bookings.
2. System sends reminder email with time and location.

**Postconditions:** Guest reminded.

---

### UC-GUEST-11 — Book on Mobile Device

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest completes booking on phone or tablet. |

**Main Flow:**
1. Guest opens public or embed link on mobile browser.
2. Responsive Angular UI adapts layout.
3. Full booking flow completes without horizontal scroll or broken controls.

**Postconditions:** Same as UC-GUEST-05.

---

### UC-GUEST-12 — Complete Booking with Custom Questions

| Field | Value |
|-------|-------|
| **Actor** | Guest |
| **Priority** | M |
| **Description** | Guest answers host-defined intake questions during booking. |

**Main Flow:**
1. Booking form renders text, select, or checkbox questions from event type config.
2. Guest fills required fields.
3. Answers stored in `bookings.custom_answers` JSON.
4. Host sees answers in booking detail.

**Postconditions:** Custom answers persisted.

---

## 6. Third-Party / Embed Use Cases

### UC-EMBED-01 — Load Embed Widget via Script Tag

| Field | Value |
|-------|-------|
| **Actor** | Partner Developer, Guest |
| **Priority** | M |
| **Description** | Partner site embeds booking widget with one script tag. |

**Main Flow:**
1. Partner adds `<script src=".../embed/loader.js" data-embed-key="...">` to their HTML.
2. Loader fetches embed config from Node API.
3. Node validates request origin against `allowed_origins`.
4. Loader injects iframe pointing to Angular embed-widget app.
5. Guest completes booking inside iframe.

**Alternative Flows:**
- **A1 — Origin not allowed:** 403; widget does not load.
- **A2 — Invalid embed key:** 404.

**Postconditions:** Booking possible on partner site without leaving page.

---

### UC-EMBED-02 — Load Embed Widget via Direct Iframe

| Field | Value |
|-------|-------|
| **Actor** | Partner Developer |
| **Priority** | M |
| **Description** | Partner embeds iframe URL directly without loader script. |

**Main Flow:**
1. Partner adds iframe with `src="/embed/widget/{embedKey}"`.
2. Angular embed app bootstraps; same booking flow as UC-EMBED-01.

**Postconditions:** Widget displayed inline.

---

### UC-EMBED-03 — Popup / Modal Embed Mode

| Field | Value |
|-------|-------|
| **Actor** | Partner Developer, Guest |
| **Priority** | S |
| **Description** | Booking opens in popup button or modal overlay on partner site. |

**Main Flow:**
1. Loader script renders floating "Book Now" button.
2. Guest clicks button; modal or popup opens with embed iframe.
3. Guest books; modal closes on completion.

**Postconditions:** Non-intrusive embed experience.

---

### UC-EMBED-04 — Receive postMessage on Booking Complete

| Field | Value |
|-------|-------|
| **Actor** | Partner Developer |
| **Priority** | M |
| **Description** | Partner page reacts when guest finishes booking. |

**Main Flow:**
1. Angular embed widget dispatches `calendar.embed.bookingComplete` via `postMessage`.
2. Partner's JavaScript listener receives event with `bookingId`.
3. Partner redirects to thank-you page, updates CRM, or shows custom UI.

**Postconditions:** Partner system aware of new booking.

---

### UC-EMBED-05 — Apply Custom Theme in Embed

| Field | Value |
|-------|-------|
| **Actor** | Host, Guest |
| **Priority** | S |
| **Description** | Embedded widget matches partner or host branding. |

**Main Flow:**
1. Host configures primary color, background, font, border radius in embed settings.
2. Widget applies CSS custom properties from theme JSON.

**Postconditions:** Branded embed experience.

---

### UC-EMBED-06 — Track Embed-Source Bookings

| Field | Value |
|-------|-------|
| **Actor** | Host, System |
| **Priority** | M |
| **Description** | System records which embed key produced each booking. |

**Main Flow:**
1. Embed widget sends `X-Embed-Key` header on booking POST.
2. System stores value in `bookings.embed_source`.
3. Host filters analytics by embed source.

**Postconditions:** Attribution available for reporting.

---

### UC-EMBED-07 — Integrate via Angular NPM Package

| Field | Value |
|-------|-------|
| **Actor** | Partner Developer |
| **Priority** | C |
| **Description** | Angular partner app uses `@calendar/booking-ui` component directly. |

**Main Flow:**
1. Partner installs npm package.
2. Partner adds `<calendar-embed-booking [embedKey]="key">` to template.
3. Component handles NgRx state and API calls internally.

**Postconditions:** Native Angular integration without iframe.

---

### UC-EMBED-08 — Server-to-Server API Access

| Field | Value |
|-------|-------|
| **Actor** | Partner Developer |
| **Priority** | S |
| **Description** | Partner backend reads bookings or triggers actions via API key. |

**Main Flow:**
1. Partner sends request with `Authorization: Bearer cal_live_xxx`.
2. Node validates key hash and scopes in MySQL.
3. API returns data or performs scoped action.

**Alternative Flows:**
- **A1 — Invalid or expired key:** 401.
- **A2 — Insufficient scope:** 403.

**Postconditions:** Partner system integrated programmatically.

---

### UC-EMBED-09 — Whitelist Partner Domains

| Field | Value |
|-------|-------|
| **Actor** | Host |
| **Priority** | M |
| **Description** | Host restricts embed to approved website origins. |

**Main Flow:**
1. Host adds `https://partner.com` to allowed origins.
2. Node CORS and embed middleware reject other origins.

**Postconditions:** Widget only loads on approved sites.

---

## 7. Calendar Integration Use Cases

### UC-CAL-01 — Import Free/Busy from Google

| Field | Value |
|-------|-------|
| **Actor** | System, Calendar Provider |
| **Priority** | M |
| **Description** | System reads busy intervals from Google Calendar. |

**Main Flow:**
1. Sync job calls Google `freeBusy.query` for selected calendars.
2. Busy intervals stored in Redis cache (and optionally `busy_blocks`).
3. Availability engine excludes overlapping slots.

**Postconditions:** Google events block booking slots.

---

### UC-CAL-02 — Import Free/Busy from Microsoft

| Field | Value |
|-------|-------|
| **Actor** | System, Calendar Provider |
| **Priority** | M |
| **Description** | System reads schedule via Microsoft Graph `getSchedule`. |

**Main Flow:** Same pattern as UC-CAL-01 via Graph API.

**Postconditions:** Outlook/365 events block slots.

---

### UC-CAL-03 — Import Free/Busy from Apple iCloud

| Field | Value |
|-------|-------|
| **Actor** | System, Calendar Provider |
| **Priority** | M |
| **Description** | System polls CalDAV for VEVENT busy times. |

**Main Flow:**
1. Sync job sends CalDAV REPORT for date range.
2. Parses VEVENT DTSTART/DTEND into busy blocks.

**Postconditions:** iCloud events block slots.

---

### UC-CAL-04 — Create Event on Host Calendar

| Field | Value |
|-------|-------|
| **Actor** | System, Calendar Provider |
| **Priority** | M |
| **Description** | New booking creates event on host's write-target calendar. |

**Main Flow:**
1. Booking confirmed in MySQL.
2. Job calls provider API (Google insert / Graph POST / CalDAV PUT).
3. External event ID stored in `calendar_event_syncs`.

**Alternative Flows:**
- **A1 — API failure:** Retry up to 5 times; status `failed`; host notified.

**Postconditions:** Host calendar shows new appointment.

---

### UC-CAL-05 — Add Guest as Calendar Attendee

| Field | Value |
|-------|-------|
| **Actor** | System, Calendar Provider |
| **Priority** | S |
| **Description** | Guest receives native calendar invite from Google/Microsoft. |

**Main Flow:**
1. Event creation includes guest email in attendees array.
2. Provider sends invite email to guest.

**Postconditions:** Guest has provider-native invite (in addition to .ics).

---

### UC-CAL-06 — Update Event on Reschedule

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |
| **Description** | Rescheduled booking updates external calendar event time. |

**Main Flow:**
1. Booking times updated in MySQL.
2. Job PATCHes/updates event at provider using stored `external_event_id`.

**Postconditions:** Calendar event reflects new time.

---

### UC-CAL-07 — Delete Event on Cancellation

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |
| **Description** | Cancelled booking removes external calendar event. |

**Main Flow:**
1. Booking status set to `cancelled`.
2. Job DELETEs event at provider.
3. Sync record marked `deleted`.

**Postconditions:** Calendar event removed.

---

### UC-CAL-08 — Sync Multiple Calendars per Host

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |
| **Description** | Host connects Google + Microsoft + Apple simultaneously. |

**Main Flow:**
1. Each connection syncs independently.
2. Availability engine merges all busy blocks from all `checkConflicts` calendars.

**Postconditions:** No double-booking across any connected calendar.

---

### UC-CAL-09 — Handle Duplicate External Events

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |
| **Description** | Same meeting on two synced calendars does not double-block. |

**Main Flow:**
1. System deduplicates overlapping busy intervals from same time window before slot calculation.

**Postconditions:** Accurate availability with multi-calendar setup.

---

## 8. Notification Use Cases

### UC-NOTIF-01 — Send Booking Confirmation to Guest

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** Email with details, cancel link, .ics attachment.

---

### UC-NOTIF-02 — Send Booking Notification to Host

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** Email with guest name, email, custom answers, time, calendar attachment.

---

### UC-NOTIF-03 — Send Cancellation Notification

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** Both parties notified who cancelled and original meeting time.

---

### UC-NOTIF-04 — Send Reschedule Notification

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** Both parties notified of old and new times.

---

### UC-NOTIF-05 — Send Reminder Before Meeting

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | S |

**Main Flow:** Cron sends 24h and/or 1h reminders to guest and host.

---

### UC-NOTIF-06 — Alert Host of Calendar Sync Failure

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Token refresh or event push fails after retries.
2. Email sent with reconnect link.

**Postconditions:** Host can restore sync (UC-HOST-32).

---

### UC-NOTIF-07 — Send Email Verification

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** Verification link sent on registration.

---

## 9. Platform Admin Use Cases

### UC-ADMIN-01 — View All Users

| Field | Value |
|-------|-------|
| **Actor** | Platform Admin |
| **Priority** | S |

**Main Flow:** Admin searches and lists host accounts.

---

### UC-ADMIN-02 — Suspend User Account

| Field | Value |
|-------|-------|
| **Actor** | Platform Admin |
| **Priority** | S |

**Main Flow:**
1. Admin suspends abusive account.
2. Login blocked; public links return unavailable.

**Postconditions:** Account inactive.

---

### UC-ADMIN-03 — Monitor Failed Sync Queue

| Field | Value |
|-------|-------|
| **Actor** | Platform Admin |
| **Priority** | S |

**Main Flow:** Admin dashboard shows failed calendar sync and notification jobs.

---

### UC-ADMIN-04 — Configure Rate Limits

| Field | Value |
|-------|-------|
| **Actor** | Platform Admin |
| **Priority** | C |

**Main Flow:** Admin adjusts IP and email rate limits for public booking endpoints.

---

### UC-ADMIN-05 — View System Health

| Field | Value |
|-------|-------|
| **Actor** | Platform Admin |
| **Priority** | S |

**Main Flow:** Admin checks `/health`, DB, Redis, queue depth, error rates.

---

### UC-ADMIN-06 — Review Audit Logs

| Field | Value |
|-------|-------|
| **Actor** | Platform Admin |
| **Priority** | S |

**Main Flow:** Admin searches `audit_logs` for booking, login, and cancel events.

---

## 10. System Use Cases

### UC-SYS-01 — Compute Available Slots

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Load weekly rules + date overrides for host timezone.
2. Generate candidate slots at configured interval.
3. Subtract bookings, busy blocks, buffers, min notice, max advance.
4. Return slots in guest timezone.

---

### UC-SYS-02 — Prevent Double Booking (Race Condition)

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Two guests submit same slot simultaneously.
2. Transaction with pessimistic lock on overlapping bookings.
3. First commit succeeds; second receives 409 Conflict.

**Postconditions:** Exactly one booking for slot.

---

### UC-SYS-03 — Idempotent Booking Request

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Client retries POST with same `Idempotency-Key`.
2. System returns existing booking instead of creating duplicate.

**Postconditions:** Single booking per idempotency key.

---

### UC-SYS-04 — Refresh OAuth Tokens

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Cron finds tokens expiring within 10 minutes.
2. Refreshes via Google/Microsoft token endpoint.
3. Updates encrypted tokens in MySQL.

**Alternative Flows:**
- **A1 — Refresh fails:** Mark connection `expired`; trigger UC-NOTIF-06.

---

### UC-SYS-05 — Periodic Free/Busy Sync

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Cron every 5–15 minutes enqueues sync per active connection.
2. Busy cache in Redis updated with 90-day rolling window.

---

### UC-SYS-06 — Push Calendar Event on Booking

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** BullMQ worker executes UC-CAL-04 asynchronously after booking create.

---

### UC-SYS-07 — Invalidate Availability Cache

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Triggers:** Working hours change, new/cancelled booking, calendar reconnect, override added.

**Main Flow:** Redis keys `busy:{userId}:*` deleted.

---

### UC-SYS-08 — Generate ICS File

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** Build VCALENDAR/VEVENT with UID, UTC times, organizer, attendee, cancel URL.

---

### UC-SYS-09 — Validate Embed Origin (CORS)

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Request includes `Origin` header.
2. Middleware checks against `embed_configs.allowed_origins`.
3. Allow or deny with 403.

---

### UC-SYS-10 — Rate Limit Public Endpoints

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:**
1. Redis tracks requests per IP and per guest email.
2. Exceeding limit returns 429 with `Retry-After`.

---

### UC-SYS-11 — Encrypt OAuth Tokens at Rest

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | M |

**Main Flow:** AES-256-GCM encrypt before MySQL write; decrypt only in calendar service.

---

### UC-SYS-12 — Write Audit Log Entry

| Field | Value |
|-------|-------|
| **Actor** | System |
| **Priority** | S |

**Main Flow:** Log booking create/cancel, login, embed config change with IP and timestamp.

---

## 11. Use Case Traceability Matrix

| Use Case ID | Feature Area | API / Component | Priority |
|-------------|--------------|-----------------|----------|
| UC-HOST-01–07 | Authentication | `POST /auth/*`, Angular auth store | M |
| UC-HOST-08–10 | Availability | `PUT /me/availability`, AvailabilityService | M |
| UC-HOST-11–14 | Event Types | `POST /me/event-types`, EventTypes NgRx | M |
| UC-HOST-15–20 | Calendars | OAuth routes, CalendarSyncService | M |
| UC-HOST-21–25 | Bookings | `GET /me/bookings`, Bookings NgRx | M |
| UC-HOST-26–28 | Embed Config | `embed_configs`, EmbedSettings | M |
| UC-HOST-29–30 | API Keys | `api_keys`, auth middleware | S |
| UC-HOST-31 | Analytics | Dashboard aggregations | S |
| UC-HOST-32–34 | Account / GDPR | Profile, delete, export | S |
| UC-GUEST-01–12 | Public Booking | `GET/POST /public/*`, public-booking app | M |
| UC-EMBED-01–09 | Third-Party Embed | loader.js, embed-widget, postMessage | M |
| UC-CAL-01–09 | Calendar Sync | Provider services, BullMQ jobs | M |
| UC-NOTIF-01–07 | Notifications | NotificationService, SMTP | M |
| UC-ADMIN-01–06 | Platform Admin | Admin routes (future) | S |
| UC-SYS-01–12 | System Automation | Workers, Redis, middleware | M |

---

## Summary Count

| Category | Count |
|----------|-------|
| Host | 34 |
| Guest | 12 |
| Third-Party / Embed | 9 |
| Calendar Integration | 9 |
| Notifications | 7 |
| Platform Admin | 6 |
| System | 12 |
| **Total** | **89** |

---

## Related Documents

- [Complete Documentation](./COMPLETE_DOCUMENTATION.md)
- [User Guide](./USER_GUIDE.md)
- [API Reference](./API_REFERENCE.md)
- [Node.js Developer Guide](./node.md)
- [Angular Developer Guide](./angular.md)
- [MySQL Developer Guide](./mysql.md)