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/*.