first commit

about/booking_fow.md

@@ -0,0 +1,368 @@
+# Spanglish Website – Booking & Payment Flow
+
+## 1. Purpose
+
+This document defines the complete booking and payment flow for Spanglish events.
+
+It ensures a fast, reliable, and user-friendly process for participants and a clear management workflow for organizers.
+
+The system supports the following payment methods:
+
+* TPago / Bancard (Credit & Debit Cards)
+* Bitcoin Lightning (BTCPay)
+* Cash at Event
+
+---
+
+## 2. Core Objectives
+
+The booking system must:
+
+* Allow users to reserve a seat in under 60 seconds
+* Minimize drop-off during payment
+* Provide clear confirmation
+* Support mobile-first usage
+* Reduce manual coordination
+* Integrate cleanly with the admin dashboard
+
+---
+
+## 3. High-Level Booking Flow
+
+1. User visits an event page
+2. User clicks "Join Event"
+3. Booking page opens
+4. User enters personal details
+5. User selects payment method
+6. Payment or reservation is processed
+7. Ticket is generated
+8. Confirmation is sent
+9. User appears in admin dashboard
+
+---
+
+## 4. Booking Page Structure
+
+The booking page is available at:
+
+/book/{event-id}
+
+It consists of a single vertical flow optimized for mobile devices.
+
+### 4.1 Event Summary Section
+
+Displayed at the top and always visible:
+
+* Event title
+* Date and time
+* Location
+* Remaining seats
+* Price
+
+This section helps users verify they selected the correct event.
+
+---
+
+### 4.2 User Information Section
+
+The booking form collects:
+
+* Full name (required)
+* Email address (required)
+* Phone / WhatsApp number (required)
+* Preferred language (optional)
+
+Validation rules:
+
+* All required fields must be filled
+* Email format validation
+* Phone number format validation
+* Duplicate booking prevention
+
+---
+
+### 4.3 Payment Selection Section
+
+Users choose one of the following payment methods using selectable cards.
+
+Each option is presented as a large, tap-friendly card with icon and description.
+
+Available options:
+
+1. TPago / Bancard
+2. Bitcoin Lightning
+3. Cash at Event
+
+Only one option may be selected.
+
+---
+
+## 5. Payment Methods
+
+### 5.1 TPago / Bancard (Credit & Debit Card)
+
+#### User Flow
+
+1. User selects "TPago / Bancard"
+2. User clicks "Pay with Card"
+3. User is redirected to Bancard checkout
+4. User completes payment
+5. User is redirected back to Spanglish
+6. Payment is verified via webhook
+7. Ticket is confirmed
+
+#### System Behavior
+
+* Payment intent is created before redirect
+* Payment reference is stored
+* Webhook validation is mandatory
+* Only verified payments mark tickets as paid
+
+Status: Paid
+
+---
+
+### 5.2 Bitcoin Lightning (BTCPay)
+
+#### User Flow
+
+1. User selects "Bitcoin Lightning"
+2. Invoice is generated
+3. QR code and invoice string are displayed
+4. User pays with Lightning wallet
+5. Payment is detected via webhook
+6. Ticket is confirmed automatically
+
+#### Display Requirements
+
+* QR code
+* Amount in sats
+* Expiry countdown
+* Copy invoice button
+
+#### System Behavior
+
+* Invoice created via BTCPay API
+* Webhook confirmation required
+* Automatic ticket confirmation
+
+Status: Paid
+
+---
+
+### 5.3 Cash at Event
+
+#### User Flow
+
+1. User selects "Cash at Event"
+2. User confirms reservation
+3. Booking is created
+4. Ticket is generated
+5. User receives confirmation
+6. User pays in cash at the event entrance
+
+#### System Behavior
+
+* Booking is stored as unpaid
+* Seat is reserved immediately
+* No automatic expiration is applied
+* Admin marks payment as received manually
+
+Status: Pending (until marked Paid by staff)
+
+---
+
+## 6. Ticket Generation
+
+After successful booking:
+
+* A unique ticket ID is generated
+* Ticket is linked to user and event
+* Ticket status is assigned
+* QR code may be generated
+* Ticket is stored permanently
+
+Ticket statuses:
+
+* Pending
+* Paid
+* Cancelled
+* Refunded
+
+---
+
+## 7. Confirmation & Notifications
+
+### 7.1 Booking Confirmation
+
+Sent immediately after booking.
+
+Channels:
+
+* Email
+* Optional WhatsApp integration
+
+Content includes:
+
+* Event details
+* Payment method
+* Ticket ID
+* Check-in instructions
+  n
+
+---
+
+### 7.2 Payment Confirmation
+
+Sent when payment is completed (Card / Lightning).
+
+Includes:
+
+* Payment receipt
+* Ticket confirmation
+* Calendar link
+
+---
+
+### 7.3 Event Reminder
+
+Sent automatically before the event.
+
+Includes:
+
+* Date and time
+* Location map
+* Payment reminder for cash users
+
+---
+
+## 8. Admin Management Flow
+
+### 8.1 Admin View
+
+Admins can view all bookings with:
+
+* Name
+* Event
+* Payment method
+* Status
+* Contact info
+* Check-in status
+
+Color coding:
+
+* Green: Paid
+* Yellow: Pending
+* Red: Cancelled
+
+---
+
+### 8.2 Manual Payment Processing
+
+For cash payments:
+
+* Admin locates ticket
+* Marks as Paid
+* Timestamp is recorded
+* Receipt may be attached
+
+---
+
+### 8.3 Refund Handling
+
+Admins may:
+
+* Mark tickets as Refunded
+* Trigger payment provider refunds
+* Send notification to user
+
+---
+
+## 9. Capacity Management
+
+* Each event has a fixed capacity
+* Seats are reserved immediately on booking
+* Overbooking is prevented
+* Sold-out events disable booking
+
+---
+
+## 10. Anti-Abuse Measures
+
+The system must implement:
+
+* Duplicate booking detection
+* Rate limiting on bookings
+* Email verification (optional)
+* Admin override tools
+
+---
+
+## 11. Error Handling
+
+The system must handle:
+
+* Failed payments
+* Interrupted redirects
+* Invoice expiration
+* Network issues
+* Invalid input
+
+Behavior:
+
+* Clear user-facing messages
+* Automatic retry options
+* Error logging
+
+---
+
+## 12. Audit Logging
+
+All booking-related actions must be logged:
+
+* Ticket creation
+* Payment updates
+* Manual status changes
+* Refunds
+* Cancellations
+
+Each log entry includes:
+
+* User ID
+* Admin ID (if applicable)
+* Timestamp
+* Action type
+  n
+
+---
+
+## 13. Security Requirements
+
+* Secure payment redirects
+* Webhook signature verification
+* Encrypted data storage
+* PCI compliance via provider
+* No sensitive card data stored
+
+---
+
+## 14. Future Extensions
+
+The booking system is designed to support:
+
+* Subscriptions
+* Membership passes
+* Promo codes
+* Group bookings
+* Lightning Address payments
+* Cashu payments
+
+---
+
+## 15. Summary
+
+This booking and payment flow is designed to be fast, reliable, and scalable.
+
+It supports local payment methods, Bitcoin Lightning, and cash while maintaining professional standards.
+
+All implementations must follow this document to ensure consistency and trust.