united-tattoo/docs/BOOKING-WORKFLOW-RISKS.md

Risk Assessment & Known Issues - Booking Workflow Plan

Document Version: 1.0
Date: January 9, 2025
Status: Pre-Implementation Review

---

🔴 Critical Risks

1. Race Conditions & Concurrency

Risk Level: HIGH - Could cause double bookings or data loss

Issues:

• User books appointment while background sync is running → duplicate or conflicting data
• Two admins approve same booking simultaneously → status conflicts
• Nextcloud event modified during sync → data inconsistency
• No database transaction handling in appointments API

Mitigation Required:

• Add database transaction locks for booking creation
• Implement optimistic locking with ETags for updates
• Add conflict resolution logic with "last write wins" or manual reconciliation
• Add unique constraints to prevent duplicates

Missing from Plan: Transaction handling completely absent

---

2. Authentication & Authorization Gaps

Risk Level: HIGH - Security vulnerability

Issues:

• Assumption that session.user.id exists and matches appointments.client_id format
• Admin role checking duplicated in every page - error-prone
• No middleware protecting admin routes - easy to miss a check
• User table schema not verified in plan

Mitigation Required:

• Create authentication middleware for all admin routes
• Verify user schema has compatible id field
• Add comprehensive auth tests
• Use Next.js middleware for route protection

Missing from Plan: No middleware implementation, schema verification

---

3. Background Sync Reliability

Risk Level: HIGH - Core functionality breaks

Issues:

• Worker failures are only logged - no alerts or retries
• Nextcloud down = all syncs fail with no recovery
• Network timeouts cause partial syncs
• 5-minute sync interval = 5-minute lag for critical status changes
• No queue for failed operations

Mitigation Required:

• Implement retry queue with exponential backoff
• Add Cloudflare Workers monitoring/alerting
• Create health check endpoint
• Consider webhook alternative to reduce lag
• Add dead letter queue for permanent failures

Missing from Plan: Retry mechanism, monitoring, alerting

---

4. Email Notification Dependency

Risk Level: HIGH - User communication breaks

Issues:

• Entire workflow depends on email but marked as "TODO"
• Users/artists never know about status changes without email
• SMTP configuration might not be set
• No email templates defined
• No fallback if email fails

Mitigation Required:

• Implement email system BEFORE other phases
• Choose email provider (SendGrid, Postmark, AWS SES)
• Create email templates
• Add in-app notifications as backup
• Queue failed emails for retry

Missing from Plan: Email is Phase 3+ but should be Phase 1

---

🟡 Medium Risks

5. Status Detection Brittleness

Risk Level: MEDIUM - Incorrect status updates

Issues:

• Relies on "REQUEST:" prefix - artist could manually edit title
• External calendar events could be misidentified as bookings
• ical.js might not parse STATUS field correctly
• No validation that event belongs to booking system
• Magic string "REQUEST:" is hardcoded everywhere

Mitigation Required:

• Add unique identifier (UUID) in event description
• Validate event source before processing
• Add manual reconciliation UI for admins
• Move magic strings to constants
• Add event ownership verification

Missing from Plan: Event validation, reconciliation UI

---

6. CalDAV/Nextcloud Availability

Risk Level: MEDIUM - Degrades user experience

Issues:

• Nextcloud down = slow booking submission (waits for timeout)
• CalDAV credentials could expire without notice
• Network latency makes availability checks slow (300ms debounce helps but not enough)
• Multiple calendars per artist not supported
• Calendar URL format might vary by Nextcloud version

Mitigation Required:

• Add CalDAV health check endpoint
• Implement credential rotation monitoring
• Add faster timeout for availability checks (2-3 seconds max)
• Cache availability results briefly
• Test with different Nextcloud versions

Missing from Plan: Health checks, caching, timeout limits

---

7. Performance & Scalability

Risk Level: MEDIUM - Won't scale beyond ~50 artists

Issues:

• Background worker syncs ALL artists every 5 minutes (expensive)
• Fetches 90-day event range every sync (slow with many bookings)
• No pagination on bookings DataTable (breaks with 1000+ bookings)
• Availability check fires on every form field change
• No incremental sync using sync-token

Mitigation Required:

• Implement incremental sync with sync-token (CalDAV supports this)
• Add pagination to bookings table
• Limit event range to 30 days with on-demand expansion
• Implement smarter caching for availability
• Consider sync only changed calendars

Missing from Plan: Incremental sync, pagination, performance testing

---

8. Timezone Edge Cases

Risk Level: MEDIUM - Wrong-time bookings

Issues:

• Hardcoded America/Denver prevents expansion
• Daylight Saving Time transitions not tested
• Date comparison between systems has timezone bugs potential
• User browser timezone vs server vs Nextcloud timezone
• No verification that times are displayed correctly

Mitigation Required:

• Store all times in UTC internally
• Use date-fns-tz for ALL timezone operations
• Test DST transitions (spring forward, fall back)
• Add timezone to user preferences if expanding
• Display timezone clearly in UI

Missing from Plan: DST testing, UTC storage verification

---

9. Data Consistency & Integrity

Risk Level: MEDIUM - Data quality degrades

Issues:

• ETag conflicts if event updated simultaneously
• No global unique constraint on caldav_uid (only per artist)
• calendar_sync_logs will grow unbounded
• No validation on calendar URL format
• No cascade delete handling documented

Mitigation Required:

• Add global unique constraint on caldav_uid
• Implement log rotation (keep last 90 days)
• Validate calendar URLs with regex
• Add ETag conflict resolution
• Document cascade delete behavior

Missing from Plan: Constraints, log rotation, URL validation

---

🟢 Low Risks (Nice to Have)

10. User Experience Gaps

Issues:

• No way to edit booking after submission
• No user-facing cancellation flow
• Confirmation page doesn't show sync status
• No booking history for users
• No real-time updates (5-min lag)

Mitigation: Add these as Phase 2 features post-launch

---

11. Admin Experience Gaps

Issues:

• No bulk operations in dashboard
• No manual reconciliation UI for conflicts
• No artist notification preferences
• No test connection button (only validates on save)

Mitigation: Add as Phase 3 enhancements

---

12. Testing Coverage

Issues:

• No automated tests (marked TODO)
• Manual checklist not integrated into CI/CD
• No load testing
• No concurrent booking tests

Mitigation: Add comprehensive test suite before production

---

13. Monitoring & Observability

Issues:

• No monitoring for worker failures
• Toast errors disappear on navigation
• No dashboard for sync health
• No Sentry or error tracking

Mitigation: Add monitoring in Phase 4

---

14. Deployment & Operations

Issues:

• Workers cron needs separate deployment
• No staging strategy
• No migration rollback plan
• Environment variables not documented

Mitigation: Create deployment runbook

---

🔧 Technical Debt & Limitations

15. Architecture Limitations

• Single Nextcloud credentials (no per-artist OAuth)
• One calendar per artist only
• No recurring appointments
• No multi-day appointments
• No support for artist breaks/vacations

16. Code Quality Issues

• Admin role checks duplicated (should be middleware)
• Magic strings not in constants
• No API versioning
• No TypeScript strict mode mentioned

17. Missing Features (Known)

• Email notifications (CRITICAL)
• Automated tests (CRITICAL)
• Background worker deployment (CRITICAL)
• Booking edit flow
• User cancellation
• Webhook support
• In-app notifications
• SMS option

---

🚨 Showstopper Scenarios

Scenario 1: Nextcloud Down During Peak Hours

Impact: Users book but syncs fail → artists don't see bookings
Current Plan: Fallback to DB-only
Gap: No retry queue when Nextcloud returns
Required: Implement sync queue

Scenario 2: Background Worker Stops

Impact: No Nextcloud→Web sync, status changes invisible
Current Plan: Worker runs but no monitoring
Gap: No alerts if worker dies
Required: Health monitoring + alerting

Scenario 3: Double Booking

Impact: Two users book same slot simultaneously
Current Plan: Availability check before booking
Gap: Race condition between check and create
Required: Transaction locks

Scenario 4: Email System Down

Impact: Zero user/artist communication
Current Plan: Email marked as TODO
Gap: No fallback communication method
Required: Email + in-app notifications

Scenario 5: DST Transition Bug

Impact: Appointments booked 1 hour off
Current Plan: Use date-fns-tz
Gap: No DST testing mentioned
Required: DST test suite

---

📋 Pre-Launch Checklist

✅ Must-Have (Blocking)

1. Implement email notification system with templates
2. Add authentication middleware for admin routes
3. Implement retry queue for failed syncs
4. Add transaction handling to appointments API
5. Deploy and test background worker
6. Verify timezone handling with DST tests
7. Add monitoring and alerting (Cloudflare Workers analytics + Sentry)
8. Write critical path tests (booking flow, sync flow)
9. Create deployment runbook
10. Set up staging environment with test Nextcloud

⚠️ Should-Have (Important)

• Rate limiting on booking endpoint
• CSRF protection verification
• Calendar URL validation with regex
• Sync log rotation (90-day retention)
• Admin reconciliation UI for conflicts
• User booking history page
• Load test background worker (100+ artists)
• Global unique constraint on caldav_uid

💚 Nice-to-Have (Post-Launch)

• Webhook support for instant sync (eliminate 5-min lag)
• In-app real-time notifications (WebSockets)
• User edit/cancel flows
• Bulk admin operations
• Multiple calendars per artist
• SMS notification option
• Recurring appointment support

---

🎯 Revised Implementation Order

Phase 0: Critical Foundation (NEW - REQUIRED FIRST)

Duration: 2-3 days
Blockers: Authentication, email, transactions

1. Add authentication middleware to protect admin routes
2. Verify user schema matches appointments.client_id
3. Add transaction handling to appointments API
4. Choose and set up email provider (SendGrid recommended)
5. Create basic email templates
6. Add error tracking (Sentry)

Acceptance Criteria:

• Admin routes redirect unauthorized users
• Email sends successfully in dev
• Transaction prevents double bookings
• Errors logged to Sentry

---

Phase 1: Core Booking Flow ✅ (As Planned)

Duration: 3-4 days
Dependencies: Phase 0 complete

1. Booking form submission with React Query
2. Confirmation page with timezone display
3. CalDAV sync on booking creation
4. Email notification on booking submission

Acceptance Criteria:

• User can submit booking
• Booking appears in Nextcloud with REQUEST: prefix
• User receives confirmation email
• Toast shows success/error

---

Phase 2: Admin Infrastructure ✅ (As Planned)

Duration: 3-4 days
Dependencies: Phase 1 complete

1. Calendar configuration UI
2. Bookings DataTable with filters
3. Approve/reject actions
4. Status sync to Nextcloud

Acceptance Criteria:

• Admin can link calendars
• Admin sees pending bookings
• Approve updates status + Nextcloud
• Email sent on status change

---

Phase 3: Background Sync ⚠️ (Enhanced)

Duration: 4-5 days
Dependencies: Phase 2 complete

1. Smart status detection logic
2. Background worker implementation
3. NEW: Retry queue for failed syncs
4. NEW: Health check endpoint
5. NEW: Cloudflare Workers monitoring

Acceptance Criteria:

• Worker runs every 5 minutes
• Status changes detected from Nextcloud
• Failed syncs retry 3 times
• Alerts sent on persistent failures
• Health check returns sync status

---

Phase 4: Production Hardening (NEW - CRITICAL)

Duration: 3-4 days
Dependencies: Phase 3 complete

1. Comprehensive error handling
2. Rate limiting (10 bookings/user/hour)
3. DST timezone testing
4. Load testing (100 artists, 1000 bookings)
5. Monitoring dashboard
6. Sync log rotation
7. Admin reconciliation UI

Acceptance Criteria:

• All errors handled gracefully
• Rate limits prevent abuse
• DST transitions work correctly
• Worker handles load without issues
• Admins can see sync health
• Logs don't grow unbounded

---

Phase 5: Staging & Launch 🚀

Duration: 2-3 days
Dependencies: Phase 4 complete

1. Deploy to staging with test Nextcloud
2. Run full test suite
3. Load test in staging
4. Security review
5. Deploy to production
6. Monitor for 48 hours

Acceptance Criteria:

• All tests pass in staging
• No critical errors in 24h staging run
• Security review approved
• Production deploy successful
• Zero critical issues in first 48h

---

💡 Recommendations

Before Starting Implementation

Critical Decisions Needed:

1. ✅ Which email provider? (Recommend: SendGrid or Postmark)
2. ✅ Confirm user schema structure
3. ✅ Set up staging Nextcloud instance
4. ✅ Choose error tracking (Sentry vs Cloudflare Logs)
5. ✅ Define rate limits for bookings

Infrastructure Setup:

1. Create staging environment
2. Set up Nextcloud test instance
3. Configure email provider
4. Set up error tracking
5. Document all environment variables

---

During Implementation

Code Quality:

1. Add TypeScript strict mode
2. Create constants file for magic strings
3. Write tests alongside features
4. Add comprehensive JSDoc comments
5. Use auth middleware everywhere

Testing Strategy:

1. Unit tests for sync logic
2. Integration tests for booking flow
3. E2E tests for critical paths
4. Load tests for background worker
5. DST timezone tests

---

After Implementation

Operations:

1. Create runbook for common issues
2. Train staff on admin dashboards
3. Set up monitoring alerts (PagerDuty/Slack)
4. Document troubleshooting steps
5. Plan for scaling (if needed)

Monitoring:

1. Track booking success rate (target: >99%)
2. Track sync success rate (target: >95%)
3. Track email delivery rate (target: >98%)
4. Monitor worker execution time (target: <30s)
5. Alert on 3 consecutive sync failures

---

📊 Risk Summary

Category	Critical	Medium	Low	Total
Bugs/Issues	4	5	5	14
Missing Features	3	2	8	13
Technical Debt	2	3	5	10
TOTAL	9	10	18	37

Showstoppers: 5 scenarios requiring mitigation
Blocking Issues: 9 must-fix before production
Estimated Additional Work: 8-10 days (new Phase 0 + Phase 4)

---

✅ Next Steps

1. Review this document with team - Discuss acceptable risks
2. Prioritize Phase 0 items - Authentication + email are blocking
3. Set up infrastructure - Staging env, email provider, monitoring
4. Revise timeline - Add 8-10 days for hardening phases
5. Get approval - Confirm scope changes are acceptable
6. Begin Phase 0 - Don't skip the foundation!

---

Document Status: Ready for Review
Requires Action: Team discussion and approval before proceeding