Core Services

8 service areas that encapsulate all business logic. Every controller — web admin and mobile API — delegates to these services. Never duplicate logic.

Shared Service Layer: All three clients (web admin, FM app, customer app) must use the same service layer. Web admin controllers and mobile API controllers both call the same underlying business logic. Never duplicate booking logic across different entry points.

Service Catalog

1. BookingService High Priority

The central service for creating and managing bookings across all channels.

  • Create bookings from 4 channels: admin, field manager, customer, contract generator
  • Enforce status machine: booked → confirmed → completed (normal path), cancelled (anytime), no_show
  • Slot hold management — 5-minute reservation during form completion
  • Conflict detection backed by DB UNIQUE index + serializable transaction constraint
  • Source and creator attribution on every booking
  • Price is mandatory and > 0

2. AuthService High Priority

Handles authentication for all user roles with dual strategies for web and mobile.

  • Customers: Phone OTP (6-digit, 5-minute expiry) → PIN setup for returning users
  • Admin / FM: Email + password
  • Rate limiting: 3 OTP sends per 15 min per phone, 10 globally per minute
  • PIN lockout: 10 failed attempts, reset via OTP
  • Dual token strategy: Session cookies (web), JWT (mobile)

3. ContractService Medium Priority

Manages recurring booking agreements that auto-generate bookings on a schedule.

  • Create recurring booking agreements (day-of-week + time + field)
  • Preview generated bookings with conflict highlighting before confirmation
  • Auto-generate bookings for active contracts
  • Toggle individual days on/off without recreating the contract

4. NotificationService — WhatsApp High Priority

WhatsApp is the primary communication channel. 98% of customer interactions happen here.

  • 4 core templates: booking_created, booking_confirmed, 24h_reminder, booking_cancelled
  • WAHA as primary channel (HTTP API, self-hosted)
  • Twilio as automatic fallback when WAHA fails
  • Delivery status tracking with retry logic
  • Incoming message webhook processing

5. PaymentService Medium Priority

Records payments against bookings. Cash-only at launch; online gateway deferred.

  • Record cash payments against bookings (online gateway deferred)
  • Partial payment tracking
  • First payment auto-confirms booking: booked → confirmed
  • Refund recording linked to original payments
  • VAT calculation: all prices VAT-inclusive at 15% (vat_amount = price / 1.15 * 0.15)

6. ScheduleService Medium Priority

Template-based scheduling system that resolves available slots from prioritized rules.

  • Template-based: profiles contain rules with numeric priority
  • Rule types: add_slots, remove_slots, modify_price, modify_time
  • Rules filter by date range + day of week
  • Prayer time integration — rules reference prayer times with offsets
  • Single query + application-level rule evaluation

7. AuditService High Priority

Immutable append-only log of every data mutation. The #1 lesson from v2's "disappearing bookings" problem.

  • Append-only log of every data mutation
  • Fields: who (user_id), what (entity + field), when (timestamp), old value, new value, reason
  • Immutable — no updates or deletes on audit_logs table

8. Background Jobs Normal Priority

Scheduled tasks that maintain data integrity and automate lifecycle transitions.

  • Hold cleanup — every 30 seconds, expire booking holds past 5 minutes
  • Auto-complete — bookings past session end time → completed
  • Auto-cancel — bookings still booked 24h after session date → cancelled
  • 24h reminders — send WhatsApp reminder for confirmed bookings
  • Contract generation — batch-create bookings for active contracts