# Epic 11: Guest Booking

## Epic Goal

Enable website visitors to request consultation bookings without requiring a user account, expanding accessibility while maintaining system integrity and admin control over the booking approval process.

## Epic Description

### Existing System Context

- **Current functionality:** Booking system fully implemented for authenticated clients at `/client/consultations/book`
- **Technology stack:** Laravel 12, Livewire 3/Volt, Flux UI, existing AvailabilityService
- **Integration points:** Consultation model, email notifications, admin booking review workflow
- **Current constraint:** `consultations.user_id` is a required foreign key to `users` table

### Enhancement Details

**What's being added:**
- Public booking form at `/booking` for unauthenticated visitors
- Guest contact information capture (name, email, phone)
- Custom captcha system (no third-party services)
- 1-per-day booking limit for guests (enforced by email)
- Guest-specific email notifications
- Admin visibility of guest bookings in existing workflow

**How it integrates:**
- Reuses existing `AvailabilityService` and `availability-calendar` component
- Extends `Consultation` model to support nullable `user_id` with guest fields
- Fits into existing admin booking review workflow
- Uses existing email infrastructure

**Success criteria:**
- Guests can submit booking requests from public `/booking` page
- Guests limited to 1 booking request per day (by email)
- Custom captcha prevents automated spam
- Admin sees guest bookings in pending queue with contact info
- Guests receive email confirmations
- Existing client booking flow unchanged

---

## Stories

### Story 11.1: Database Schema & Model Updates
Extend consultation system to support guest bookings with new database fields and model logic.

### Story 11.2: Public Booking Form with Custom Captcha
Create guest booking interface at `/booking` with availability calendar, contact form, custom captcha, and 1-per-day limit.

### Story 11.3: Guest Email Notifications & Admin Integration
Implement guest email notifications and update admin interface to handle guest bookings.

### Story 11.4: Documentation Updates
Update PRD and other documentation files to reflect guest booking functionality.

---

## Compatibility Requirements

- [x] Existing client booking flow remains unchanged
- [x] Existing APIs remain unchanged
- [x] Database schema changes are backward compatible (nullable field, new columns)
- [x] UI changes follow existing patterns (Flux UI, Volt components)
- [x] Admin workflow enhanced, not replaced

## Technical Considerations

### Database Changes
```
consultations table:
- user_id: bigint -> bigint NULLABLE
- guest_name: varchar(255) NULLABLE
- guest_email: varchar(255) NULLABLE
- guest_phone: varchar(50) NULLABLE
```

### Validation Rules
- Either `user_id` OR (`guest_name` + `guest_email` + `guest_phone`) required
- Guest email format validation
- Guest phone format validation
- 1 booking request per guest email per day

### Custom Captcha System
- Simple math-based or image-based captcha
- No external services (no Google reCAPTCHA, no Cloudflare Turnstile)
- Server-side validation with session-stored answer
- Accessible design with refresh option

### Spam Protection
- **1-per-day limit:** Maximum 1 booking request per email address per 24 hours
- **Rate limit:** 5 booking requests per IP per 24 hours (backup protection)
- **Custom captcha:** Required for all guest submissions

### Email Templates
- Reuse existing email layout/branding
- Guest emails use provided email address
- Include all booking details + contact instructions

---

## Risk Mitigation

- **Primary Risk:** Spam/abuse from anonymous submissions
- **Mitigation:** Custom captcha + 1-per-day email limit + IP rate limiting + admin approval required
- **Rollback Plan:** Revert migration, restore placeholder page

## Definition of Done

- [x] All stories completed with acceptance criteria met
- [x] Existing client booking tests still pass
- [x] New tests cover guest booking scenarios
- [x] Admin can manage guest bookings through existing interface
- [x] Guest receives appropriate email notifications
- [x] Custom captcha working correctly
- [x] 1-per-day limit enforced
- [x] No regression in existing features
- [x] Bilingual support (Arabic/English) for guest form and emails
- [x] PRD and documentation updated