docs/session-workflow.md

Session Workflow

Session Status Lifecycle

                    ┌─────────────┐
                    │  REQUESTED  │  ← Student books session
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │ Sheikh Accept           │ Sheikh Reject
              ▼                         ▼
        ┌──────────┐             ┌───────────┐
        │  TOPAY   │             │ CANCELLED │
        └────┬─────┘             └───────────┘
             │
             │ Student pays via Stripe
             │ (auto-cancel if unpaid 5min before start)
             ▼
        ┌──────────────┐
        │  SCHEDULED   │
        └──────┬───────┘
               │
               │ Both parties join
               │ (auto-MISSED if no-show 10min after start)
               ▼
         ┌───────────┐
         │ ON_GOING  │
         └─────┬─────┘
               │ Sheikh ends session
               ▼
         ┌───────────┐
         │ COMPLETED │ → Payout triggered to Sheikh
         └───────────┘

---

Step-by-Step Flow

1. Student Discovers & Books

Components: FindSheikh.tsx → SheikhProfile.tsx

Student browses sheikhs
        │
        ▼
GET /api/sheikhs/{id}/available-dates?from=...&days=30
        │
        ▼
Student picks a date
        │
        ▼
GET /api/sheikhs/{id}/available-slots/day?date=...
        │
        ▼
Student picks a time slot + writes session description
        │
        ▼
POST /api/student/sessions
{ sheikhId, startDateTime, sessionDescription }
        │
        ▼
Session created → status: REQUESTED

---

2. Sheikh Reviews & Accepts/Rejects

Component: SheikhSessionRequests.tsx → Pending Requests tab

Sheikh sees new session request
        │
        ├── Accept → POST /api/sheikh/sessions/{id}/accept
        │              │
        │              ▼
        │         Status → TOPAY
        │         ┌─ schedules: auto-cancel task (5min before start)
        │         └─ schedules: missed-check task (10min after start)
        │
        └── Reject → POST /api/sheikh/sessions/{id}/reject
                       │
                       ▼
                  Status → CANCELLED

---

3. Student Pays

Components: MySessions.tsx → StripePaymentModal.tsx

Student sees session in TOPAY state → clicks "Pay Now"
        │
        ▼
POST /api/payments/initiate/card
{ sessionId, studentId, sheikhId, amount }
        │
        ▼
Backend creates Stripe PaymentIntent
Returns: { clientSecret, publishableKey, paymentIntentId }
        │
        ▼
Frontend: Stripe.js collects card details
        │
        ▼
stripe.confirmCardPayment(clientSecret)
        │
        ▼
POST /api/payments/confirm-payment/{paymentIntentId}
        │
        ▼
Backend verifies PaymentIntent → status: PAID
Session status → SCHEDULED

If student doesn't pay: auto-cancel task fires 5 min before start → status: CANCELLED

---

4. Waiting Room

Component: WaitingRoom.tsx
Route: /waiting-room/{sessionId}

Both parties navigate to waiting room
        │
        ▼
Polls GET /api/{role}/sessions/{id} every 5 seconds
        │
        ├── countdown > 5 min  → Button disabled, show timer
        ├── countdown ≤ 5 min  → "Enter Session" button enabled
        ├── session = ON_GOING → Auto-redirect to /session/{id}
        ├── session = MISSED   → Redirect to session report
        └── session = CANCELLED → Redirect to sessions list

---

5. Live Session

Component: LiveSession.tsx
Route: /session/{sessionId}

Party joins
        │
        ▼
POST /api/{role}/sessions/{id}/join  → records joinedAt timestamp
        │
        ▼
WebRTC peer-to-peer connection established
        │
        ├── Video / Audio controls (mute, camera toggle)
        ├── Chat sidebar (both parties)
        ├── Notes sidebar (Sheikh only — auto-saved every 60s)
        └── Connection quality indicator

When BOTH have joined:
        │
        ▼
Status auto-transitions → ON_GOING

> If sheikh doesn't join within 10 min after start:
> Missed-check task fires → status: MISSED → refund issued to student

---

6. Ending the Session

Only the Sheikh can end the session.

Sheikh clicks "End Session"
        │
        ▼
Confirmation dialog
        │
        ▼
POST /api/sheikh/sessions/{id}/end
{ sessionNotes }
        │
        ▼
Backend:
  - Records actualEnd = now
  - Saves session notes
  - Status → COMPLETED
  - Triggers payout to Sheikh (85% of payment)
        │
        ▼
Sheikh: stays on session page / redirected to sessions list
Student: redirected to SessionReport.tsx for review & rating

---

7. Auto-Safety Nets (Backend Scheduled Tasks)

Trigger	When	Action
Unpaid session	5 min before scheduled start	Status → CANCELLED
No-show (either party)	10 min after scheduled start	Status → MISSED, refund to student
Sheikh no-show	10 min after scheduled start	Status → MISSED, refund to student
Server restart	On startup	All SCHEDULED/TOPAY tasks re-queued

---

Key Components Map

Component	Role
FindSheikh.tsx	Browse & search sheikhs
SheikhProfile.tsx	Pick availability slot, initiate booking
SheikhSessionRequests.tsx	Sheikh reviews/accepts/rejects requests
SheikhAvailabilityForm.tsx	Sheikh sets weekly availability
MySessions.tsx	Session list with status tabs & Pay Now
StripePaymentModal.tsx	Stripe card payment UI
WaitingRoom.tsx	Pre-session countdown & status polling
LiveSession.tsx	WebRTC video, chat, notes
SessionReport.tsx	Post-session review & rating

---

API Endpoints Reference

Student

Method	Endpoint	Description
POST	/api/student/sessions	Book session
GET	/api/student/sessions	List sessions
GET	/api/student/sessions/{id}	Get session details
POST	/api/student/sessions/{id}/join	Record student joined
POST	/api/student/sessions/{id}/leave	Record student left

Sheikh

Method	Endpoint	Description
GET	/api/sheikh/sessions	List sessions
POST	/api/sheikh/sessions/{id}/accept	Accept → TOPAY
POST	/api/sheikh/sessions/{id}/reject	Reject → CANCELLED
POST	/api/sheikh/sessions/{id}/join	Record sheikh joined
POST	/api/sheikh/sessions/{id}/end	End session → COMPLETED
POST	/api/sheikh/sessions/{id}/notes	Save session notes

Availability

Method	Endpoint	Description
GET	/api/sheikh/availability	Get sheikh's weekly slots
PUT	/api/sheikh/availability	Update weekly slots
GET	/api/sheikhs/{id}/available-dates	List available dates (student view)
GET	/api/sheikhs/{id}/available-slots/day	List slots for a date