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 |