docs/APIs.md

# Quran App API Reference

This document describes the backend API endpoints for the Quran learning platform. It covers authentication, student flows, sheikh flows, admin management, payments, session workflows, reviews, availability, and real-time signaling.

> Base URL: `http://localhost:8080` (default local backend)
> Protected endpoints require `Authorization: Bearer <JWT>`.

---

## 1. Root / Health

### `GET /`
- Description: Simple root response for backend availability.
- Response: `Welcome to Quran App Backend! API endpoints: /api/auth, /api/admin, /api/sheikh, /api/student, /api/common`

---

## 2. Authentication & User Onboarding

### `POST /api/auth/register/student`
- Description: Register a new student account.
- Body:
  - `fullName` (string)
  - `email` (string)
  - `password` (string)
  - `phone` (string)
  - `gender` (string)
  - `birthDate` (date)
  - `country` (string)
- Response: `AuthResponse` with JWT token and user info.

### `POST /api/auth/register/sheikh`
- Description: Register a new sheikh account.
- Body: same as student registration.
- Response: `AuthResponse` with JWT token and user info.

### `POST /api/auth/login`
- Description: Login using email and password.
- Body:
  - `email` (string)
  - `password` (string)
- Response: `AuthResponse` with JWT token.

### `POST /api/auth/forgot-password`
- Description: Request a password reset OTP.
- Body:
  - `email` (string)
- Response: success message.

### `POST /api/auth/verify-otp`
- Description: Verify the OTP sent for password reset.
- Body:
  - `email` (string)
  - `otp` (string)
- Response: success message.

### `POST /api/auth/reset-password`
- Description: Reset a password after OTP verification.
- Body:
  - `email` (string)
  - `otp` (string)
  - `newPassword` (string)
  - `confirmNewPassword` (string)
- Response: success message.

### `POST /api/auth/logout`
- Description: Logout current authenticated user.
- Requires: JWT.
- Response: success message.

### `POST /api/auth/google`
- Description: Authenticate using Google Sign-In.
- Body:
  - `idToken` (string)
  - `role` (string) — `STUDENT` or `SHEIKH`
- Response: `AuthResponse` with JWT token.

### `POST /api/auth/complete-google-profile`
- Description: Complete the student profile for a Google-authenticated student.
- Requires: JWT.
- Body:
  - `birthDateTime` (datetime)
  - `country` (string)
  - `gender` (string)
  - `phone` (string)
  - `quranLevel` (string)
  - `preferredLanguage` (string)
  - `preferredAccent` (string)
  - `profilePhotoUrl` (string)
- Response: success message.

### `POST /api/auth/complete-google-profile/sheikh`
- Description: Complete the sheikh profile for a Google-authenticated sheikh.
- Requires: JWT.
- Body:
  - `birthDateTime` (datetime)
  - `country` (string)
  - `gender` (string)
  - `phone` (string)
  - `bio` (string)
  - `specialization` (string)
  - `yearsOfExperience` (integer)
  - `hourlyRate` (decimal)
  - `certificateUrl` (string)
  - `profilePhotoUrl` (string)
- Response: success message.

### `GET /api/auth/verify-profile`
- Description: Verify the currently authenticated user profile status.
- Requires: JWT.
- Response: `ProfileCheckDto`.

---

## 3. Dashboard Endpoints

### `GET /api/dashboard/student`
- Description: Fetch student dashboard data.
- Requires: role `STUDENT`.
- Response: `StudentDashboardDto`.

### `GET /api/dashboard/sheikh`
- Description: Fetch sheikh dashboard data.
- Requires: role `SHEIKH`.
- Response: `SheikhDashboardDto`.

### `GET /api/dashboard/admin`
- Description: Fetch admin dashboard data.
- Requires: role `ADMIN`.
- Response: `AdminDashboardDto`.

### `GET /api/admin/dashboard/pending-sheikhs`
- Description: Get pending sheikh approvals for admin.
- Requires: role `ADMIN`.
- Response: list of pending sheikhs.

### `GET /api/admin/dashboard/platform-analytics-and-stats`
- Description: Get platform analytics and admin statistics.
- Requires: role `ADMIN`.
- Response: `statsForAdminDto`.

---

## 4. Student Profile & Student Data

### `POST /api/student/profile/complete`
- Description: Complete the student onboarding profile.
- Requires: JWT.
- Body:
  - `quranLevel` (string)
  - `preferredLanguage` (string)
  - `preferredAccent` (string)
  - `profilePhotoUrl` (string)
- Response: success message.

### `GET /api/student/profile/me`
- Description: Fetch the authenticated student’s profile.
- Requires: JWT.
- Response: `StudentProfileDto`.

### `GET /api/student/profile/{id}`
- Description: Get a student profile by ID.
- Response: `StudentProfileDto`.

### `GET /api/student/profile/all`
- Description: List all student profiles.
- Requires: role `ADMIN`.
- Query:
  - `page` (int, default `0`)
  - `size` (int, default `50`)
- Response: paged list of `StudentProfileDto`.

### `GET /api/student/streak`
- Description: Get the authenticated student’s Quran practice streak.
- Requires: JWT.
- Response: `StreakDto`.

### `GET /api/student/practice/stats`
- Description: Get student recitation practice statistics.
- Requires: JWT.
- Response: `RecitationStatsDto`.

### `GET /api/student/practice/month-count`
- Description: Get the count of recitations completed this month.
- Requires: JWT.
- Response: numeric count.

---

## 5. Student Recitation Endpoints

### `GET /api/student/recitations`
- Description: Get all recitations for the authenticated student.
- Requires: JWT.
- Response: list of `StudentRecitationDto`.

### `GET /api/student/recitations/recent`
- Description: Get the top 5 most recent recitations.
- Requires: JWT.
- Response: list of `StudentRecitationDto`.

### `GET /api/student/recitations/stats`
- Description: Get summary statistics for student recitations.
- Requires: JWT.
- Response: `RecitationStatsDto`.

### `POST /api/student/recitations`
- Description: Submit recitation audio for AI evaluation.
- Requires: JWT.
- Consumes: `multipart/form-data`
- Form fields:
  - `surahNumber` (int)
  - `audio` (file)
- Response: `RecitationDetailsDto`.

### `GET /api/student/recitations/{id}`
- Description: Get detailed recitation result by ID.
- Requires: JWT.
- Response: `RecitationDetailsDto`.

---

## 6. Sheikh Discovery & Availability

### `GET /api/sheikhs/allSheikhsToStudents`
- Description: Get a paged list of sheikhs for student search.
- Query:
  - `page` (int, default `0`)
  - `size` (int, default `20`)
- Response: list of `ShiekhProfileResponse`.

### `POST /api/sheikhs/filter`
- Description: Filter sheikhs by search criteria.
- Body:
  - `name` (string)
  - `country` (string)
  - `ratingAsc` (boolean)
  - `priceAsc` (boolean)
- Response: filtered list of `ShiekhProfileResponse`.

### `GET /api/sheikhs/{sheikhId}/available-dates`
- Description: Get available booking dates for a sheikh.
- Query:
  - `from` (date, optional)
  - `days` (int, default `30`, max `90`)
- Response: list of available dates.

### `GET /api/sheikhs/{sheikhId}/available-slots/day`
- Description: Get available slots on a specific date.
- Query:
  - `date` (date, required)
- Response: list of `AvailableSlotDto`.

### `GET /api/sheikhs/{sheikhId}/available-slots`
- Description: Get available slots across a date range.
- Query:
  - `from` (date, optional)
  - `days` (int, default `30`, max `90`)
- Response: list of `AvailableSlotDto`.

### `GET /api/sheikhs/{sheikhId}/profile`
- Description: Get a detailed sheikh public profile.
- Response: `sheikhProfileResponseComposed`.

### `GET /api/sheikhs/{sheikhId}/Top-Reviews`
- Description: Get top reviews for a sheikh.
- Response: list of `ReviewDto`.

---

## 7. Sheikh Profile Management

### `POST /api/sheikh/profile/complete`
- Description: Complete the sheikh onboarding profile.
- Requires: JWT.
- Body:
  - `bio` (string)
  - `specialization` (string)
  - `yearsOfExperience` (integer)
  - `hourlyRate` (decimal)
  - `certificateUrl` (string)
  - `profilePhotoUrl` (string)
  - `payoutMethod` (enum)
  - `fullNameOnAccount` (string)
  - `vodafoneCashNumber` (string)
  - `bankCardNumber` (string)
  - `bankCode` (string)
- Response: success message.

### `GET /api/sheikh/profile/me`
- Description: Get the authenticated sheikh’s own profile.
- Requires: JWT.
- Response: `SheikhProfileDto`.

### `GET /api/sheikh/profile/{id}`
- Description: Get a sheikh profile by ID.
- Response: `SheikhProfileDto`.

### `GET /api/sheikh/profile/all`
- Description: Get all approved sheikh profiles.
- Query:
  - `page` (int, default `0`)
  - `size` (int, default `20`)
- Response: list of `SheikhProfileDto`.

### `GET /api/sheikh/profile/approved`
- Description: Get all approved sheikhs, ordered by rating.
- Query:
  - `page` (int, default `0`)
  - `size` (int, default `20`)
- Response: list of `SheikhProfileDto`.

---

## 8. Session Booking & Live Session Lifecycle

### `GET /api/student/sessions`
- Description: List student sessions.
- Query:
  - `sessionStatus` (optional enum)
- Requires: JWT.
- Response: list of `StudentSessionDto`.

### `GET /api/student/sessions/{sessionId}`
- Description: Get a specific student session.
- Requires: JWT.
- Response: `StudentSessionDto`.

### `POST /api/student/sessions`
- Description: Book a new session with a sheikh.
- Requires: JWT.
- Body:
  - `sheikhId` (long)
  - `startDateTime` (datetime)
  - `sessionDescription` (string)
- Response: `StudentSessionDto`.

### `POST /api/student/sessions/{sessionId}/join`
- Description: Mark the student as joined for the session.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/student/sessions/{sessionId}/leave`
- Description: Mark the student as left from the session.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/student/sessions/{sessionId}/end`
- Description: Students are not allowed to end sessions.
- Requires: JWT.
- Response: 403 error.

---

## 9. Sheikh Session Management

### `GET /api/sheikh/sessions`
- Description: List sheikh sessions.
- Query:
  - `sessionStatus` (optional enum)
- Requires: JWT.
- Response: list of `SessionDTO`.

### `GET /api/sheikh/sessions/{sessionId}`
- Description: Get a specific sheikh session.
- Requires: JWT.
- Response: `SessionDTO`.

### `POST /api/sheikh/sessions/{sessionId}/accept`
- Description: Accept a requested session and move it to payment.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/join`
- Description: Mark the sheikh as joined.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/leave`
- Description: Mark the sheikh as left.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/process-missed`
- Description: Trigger missed-session processing on demand.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/force-missed`
- Description: Force a session into MISSED state and trigger refund.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/reject`
- Description: Reject a session request.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/start`
- Description: Mark a session as started.
- Requires: JWT.
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/end`
- Description: End a session and save sheikh notes.
- Requires: JWT.
- Body:
  - `notes` (string)
- Response: confirmation message.

### `POST /api/sheikh/sessions/{sessionId}/notes`
- Description: Update session notes.
- Requires: JWT.
- Body:
  - `notes` (string)
- Response: confirmation message.

---

## 10. Sheikh Availability

### `GET /api/sheikh/availability`
- Description: Fetch authenticated sheikh availability slots.
- Requires: JWT.
- Response: list of `AvailabilitySlotDto`.

### `PUT /api/sheikh/availability`
- Description: Set availability for a sheikh.
- Requires: JWT.
- Body:
  - `slots` (array of objects):
    - `dayOfWeek` (enum)
    - `startTime` (time)
    - `endTime` (time)
- Response: success.

---

## 11. Payments & Payouts

### `POST /api/payments/initiate/card`
- Description: Create a Stripe PaymentIntent for card payment.
- Body:
  - `sessionId` (long)
  - `amount` (double)
  - `mobileNumber` (string, optional for Vodafone Cash)
- Response: `StripePaymentResponse` with `clientSecret`.

### `POST /api/payments/confirm-payment/{paymentIntentId}`
- Description: Confirm the payment after Stripe.js completion.
- Path:
  - `paymentIntentId` (string)
- Response: `StripePaymentResponse`.

### `POST /api/payments/confirm-session/{sessionId}`
- Description: Confirm a session after payment has completed and the sheikh accepts.
- Path:
  - `sessionId` (long)
- Response: void.

### `POST /api/payments/payout/{sessionId}`
- Description: Transfer funds to the sheikh after session completion.
- Path:
  - `sessionId` (long)
- Response: `StripeRefundResponse`.

### `POST /api/payments/refund/{sessionId}`
- Description: Issue a refund for a cancelled or missed session.
- Path:
  - `sessionId` (long)
- Query:
  - `reason` (string, optional)
- Response: `StripeRefundResponse`.

### `POST /api/payments/connect/sheikh/{sheikhId}`
- Description: Create or refresh a Stripe connected account for a sheikh.
- Path:
  - `sheikhId` (long)
- Response: map with Stripe account info.

---

## 12. Reviews & Notes

### `GET /api/reviews/student/session/{sessionId}/details`
- Description: Student fetches session details and own review.
- Requires: role `STUDENT`.
- Response: `SessionDetailsDto`.

### `POST /api/reviews/session/{sessionId}`
- Description: Student submits or updates a review.
- Requires: role `STUDENT`.
- Body:
  - `reviews` (string)
  - `rate` (integer)
- Response: `NotesAndReviewsDto`.

### `PUT /api/reviews/sheikh/session/{sessionId}/notes`
- Description: Sheikh saves private session notes.
- Requires: role `SHEIKH`.
- Body:
  - `notes` (string)
- Response: `NotesAndReviewsDto`.

### `GET /api/reviews/sheikh/session/{sessionId}/details`
- Description: Sheikh fetches completed session details.
- Requires: role `SHEIKH`.
- Response: `SessionDetailsDto`.

### `DELETE /api/reviews/{reviewId}`
- Description: Admin deletes a review.
- Requires: role `ADMIN`.
- Path:
  - `reviewId` (long)
- Response: `204 No Content`.

---

## 13. Admin User Management

### `GET /api/admin/user-management/stats`
- Description: Get user management statistics.
- Requires: role `ADMIN`.
- Response: `userManagementStatsAdmin`.

### `GET /api/admin/user-management/students`
- Description: List all student users.
- Requires: role `ADMIN`.
- Response: list of `studentDtoAdmin`.

### `GET /api/admin/user-management/sheikhs`
- Description: List all sheikh users.
- Requires: role `ADMIN`.
- Response: list of `sheikhDtoAdmin`.

### `GET /api/admin/user-management/users`
- Description: List all users.
- Requires: role `ADMIN`.
- Response: list of user summaries.

### `POST /api/admin/user-management/block-user`
- Description: Block a user account.
- Requires: role `ADMIN`.
- Query:
  - `userId` (long)
- Response: success.

### `POST /api/admin/user-management/unblock-user`
- Description: Unblock a user account.
- Requires: role `ADMIN`.
- Query:
  - `userId` (long)
- Response: success.

### `GET /api/admin/user-management/sheikh-profile`
- Description: Get detailed sheikh profile by user ID.
- Requires: role `ADMIN`.
- Query:
  - `userId` (long)
- Response: `viewSheikhProfile`.

### `GET /api/admin/user-management/student-profile`
- Description: Get detailed student profile by user ID.
- Requires: role `ADMIN`.
- Query:
  - `userId` (long)
- Response: `viewStudentProfile`.

---

## 14. Admin Sheikh Approval

### `GET /api/admin/pending-sheikhs`
- Description: Get pending sheikh approvals.
- Requires: role `ADMIN`.
- Response: list of pending sheikh profiles.

### `POST /api/admin/sheikh/{id}/approve`
- Description: Approve a pending sheikh.
- Requires: role `ADMIN`.
- Path:
  - `id` (long)
- Response: success message.

### `POST /api/admin/sheikh/{id}/reject`
- Description: Reject a pending sheikh.
- Requires: role `ADMIN`.
- Path:
  - `id` (long)
- Response: success message.

---

## 15. Sheikh Dashboard APIs

### `PUT /api/sheikh/sheikh-dashboard-view/update-price`
- Description: Update the authenticated sheikh’s hourly rate.
- Requires: JWT.
- Body:
  - `newPrice` (decimal)
- Response: success message.

### `GET /api/sheikh/sheikh-dashboard-view/stats`
- Description: Get widget stats for the sheikh dashboard.
- Requires: JWT.
- Response: `sheikhdashboardResponse`.

### `GET /api/sheikh/sheikh-dashboard-view/upcoming-classes`
- Description: Get upcoming session list for sheikh.
- Requires: JWT.
- Response: list of `SessionDTO`.

### `GET /api/sheikh/sheikh-dashboard-view/Two-reviews`
- Description: Get two most recent reviews.
- Requires: JWT.
- Response: list of `ReviewDto`.

### `GET /api/sheikh/sheikh-dashboard-view/reviews`
- Description: Get sheikh review history.
- Requires: JWT.
- Response: list of `ReviewDto`.

---

## 16. Pending Sheikh Onboarding

### `GET /api/sheikh/pending`
- Description: Get the authenticated pending sheikh onboarding details.
- Requires: JWT.
- Response: `pendingSheikhDatailsdto`.

---

## 17. Real-Time Signaling

### WebSocket endpoint: `/ws`
- Description: SockJS / STOMP endpoint for WebRTC signaling.
- Frontend connects using SockJS and STOMP.
- Application destination prefix: `/app`
- Message mapping: `/app/signal`
- Broadcast topic: `/topic/session/{sessionId}`

### STOMP signaling message payload
- `type` — `join`, `offer`, `answer`, `ice-candidate`, `chat`
- `sender` — user ID or display name
- `sessionId` — live session ID
- Any additional SDP or ICE payload fields required for P2P negotiation.

---

## 18. Notes

- All protected endpoints require JWT authentication in the `Authorization` header.
- Admin routes require `hasRole('ADMIN')`.
- Sheikh-specific routes require sheikh authentication.
- Student-specific routes require student authentication.
- `multipart/form-data` is used only for `POST /api/student/recitations`.
- The Stripe payment endpoints are split into initiation, confirmation, payout, and refund flows.

---

## 19. Recommended Usage Flow

1. Register/Login via `/api/auth/login` or `/api/auth/register/*`.
2. Complete profile using `/api/student/profile/complete` or `/api/sheikh/profile/complete`.
3. Students browse sheikhs via `/api/sheikhs/*`.
4. Book session with `/api/student/sessions`.
5. Confirm payment through `/api/payments/initiate/card` and `/api/payments/confirm-payment/{paymentIntentId}`.
6. Sheikh accepts session via `/api/sheikh/sessions/{sessionId}/accept`.
7. Start the session through `/api/sheikh/sessions/{sessionId}/start` and join via `/api/*/sessions/{sessionId}/join`.
8. End session notes via `/api/sheikh/sessions/{sessionId}/end`.
9. Student submits review via `/api/reviews/session/{sessionId}`.
10. Admin manages users through `/api/admin/*`.