Skip to main content
If you’re new to this codebase, read these five files first — in this order. They’ll give you a mental model of how everything fits together.

​
The essential five

User model

app/Models/v1/User.phpThe central model — every feature touches it. Understand:
  • All 30+ relationships (hasMany, belongsTo, hasOne, belongsToMany)
  • The extensive query scopes (withBasicInfo, isAvailableOnDate, isVisible, whoTeaches, withDistance, etc.)
  • Profile completion logic: getProfileCompletionPercentage(), isVerified(), isProfileComplete()
  • Verification checks: hasPassedVerification(), hasValidQualification(), hasValidDBS()
  • The Tutor model (app/Models/Tutor.php) extends User via HasParent trait with a TutorScope global scope
The v1/ directory contains ~107 models — this is where the real domain logic lives, not the root Models/ directory.

Lesson + Booking models

app/Models/v1/Lesson.php + app/Models/v1/Booking.phpThe core domain pair. Understand:
  • Lesson states: ACTIVE (1), RESCHEDULE (2), CANCELLED (0)
  • Booking states: AWAITING_PAYMENT (3) → REQUIRES_CAPTURE (5) → PAYED (1) → REFUNDED (0) / PARTIAL_REFUNDED (4)
  • The store(), reschedule(), approveRescheduledLesson(), cancel() methods on Lesson
  • How Booking links a Lesson to a User with a PaymentReceipt
  • The 72-hour reschedule rule
  • Soft deletes on both models

StripeService

app/Models/Services/Payments/StripeService.phpThe payment engine. Trace the flow:
  1. createCustomer() — creates Stripe customer, links to PaymentAccount
  2. createCard() — validates and attaches payment method
  3. createCharge() — creates PaymentIntent with manual capture, handles 3D Secure
  4. createReceipt() — records payment receipt with commission breakdown
  5. createPayout() — transfers funds to tutor via Stripe Connect
  6. refund() — full or partial refund
Also: handleSubscriptionWebhook() for processing Stripe webhook events.

Routes + WebAPI middleware

routes/api.php + app/Http/Middleware/WebAPI.phpHow requests flow in:
  • routes/api.php — current API routes under /api/*
  • routes/legacy-api.php — v1 routes under /api/v1/*
  • The WebAPI middleware is critical — it implements hybrid auth: existing Auth::user() OR signed URL OR encrypted user ID as “secret”
  • Understand which endpoints use auth:api vs web.api vs internal vs public access

RegistrationService

app/Models/Services/RegistrationService.phpThe complete registration flow. Shows how all pieces wire together:
  • User creation with role, country
  • DOB, profile picture, address, mobile number setup
  • For tutors: DBS association, payment card, Stripe subscription
  • File handling: moves from temp storage to permanent
  • Fires Registered event → triggers email verification + internal notifications

​
After the essentials

Once you’ve read the five above, explore these next:

SearchService

app/Models/Services/v1/SearchService.php — complex tutor search with multiple filter scopes

AvailabilityService

app/Models/Services/v1/AvailabilityService.php — availability calculation with calendar conflicts and travel time

Scheduled jobs

app/Console/Kernel.php — 9 scheduled jobs that run the background operations

Transformers

app/Models/Transformers/v1/ — 15 transformer classes that format API responses