Module: HomeAssist / Services (homeassist / services)
Status: 🟢 Production (best-documented escrow flow; 0 live bookings currently) · Last validated: 2026-09-06 · Priority: P0
On-demand local services with an escrow-protected booking lifecycle. Validated against classs/ServiceModule.php (7,542 lines, re-measured 2026-09-06 — an earlier pass of this page said "~3,700 lines"; the file has grown since, code wins) + schema.
A. Purpose
Customers hire service providers (individual or company); money is held in escrow and released on completion. Revenue = 5% commission (platform_commission_settings.setting_key='service_booking', platform_commission_percent=5.00, is_active=1, checked 2026-09-06). Not hardcoded: at release time releaseEscrowForBooking (:2432) resolves the rate through CommissionEngineModule in order — plan-based rule (resolveCommission, :2596-2604) → sr_service_categories.commission_percent (:2606-2616) → this 5% platform default (:2618-2625) — so a specific category/plan can override the headline 5%. One historical commission txn exists for services (commission_transactions order_type='service', order_table='sr_service_escrow_orders, 1 row, 2026-09-06) even though sr_service_escrow_orders` itself is empty now (data since cleared/reset).
B. Actors
Customer; individual provider; company provider + staff; admin (escalation). Enrollment services.
C. Entry points
Consumer: /services.php, /topservices.php. Provider: management onboarding. All actions route through ServiceModule::handleRequest($action, $payload, $userId) (:83) — an in-class dispatcher.
D. Onboarding
createOrUpdateIndividualProvider (:1020) or createOrUpdateCompanyProvider (:1224). KYC via sr_service_provider_kyc_docs. Categories from sr_service_categories (120).
E. Feature registry (prefix SVC-)
| ID | Feature | Actor | Method | Tables | Status |
|---|---|---|---|---|---|
| SVC-001 | Provider onboarding | provider | createOrUpdateIndividual/CompanyProvider :1020/:1224 | sr_service_providers | 🟢 |
| SVC-002 | Create booking | customer | createBooking :1402 | sr_service_bookings | 🟢 (money) |
| SVC-003 | Init escrow | system | initEscrowForBooking :2021 | sr_service_escrow_orders | 🟢 |
| SVC-004 | Update booking status | provider/customer | updateBookingStatus :3078 | sr_service_bookings | 🟢 |
| SVC-005 | Customer confirm completion | customer | customerConfirmCompletion :3698 | booking | 🟢 |
| SVC-006 | Release escrow | system/actor | releaseEscrowForBooking :2432 | escrow, wallet, commission | 🟢 |
| SVC-007 | Refund escrow (cancel) | actor | refundEscrowForCancelledBooking :2302 | escrow, wallet | 🟢 |
| SVC-008 | Escalation / dispute | actor | openEscalation :2785 | escalation | 🟢 |
| SVC-009 | Invoice | provider | upsertInvoiceForBooking :3460, markInvoiceSent :3613 | invoice | 🟢 |
F. Escrow booking lifecycle (the archetype for escrow flows)
services.php → createBooking(userId, payload) :1402 → sr_service_bookings (status=requested)
→ initEscrowForBooking(bookingId, userId) :2021 → wallet debit → escrow HOLD (sr_service_escrow_orders)
→ provider accepts → updateBookingStatus(...) :3078
→ work done → customerConfirmCompletion(userId, bookingId) :3698
→ releaseEscrowForBooking(bookingId, actor) :2432 → escrow → provider wallet, commission recorded,
central finance ledger (module_key='homeassist'/'services', order_table='sr_service_bookings')
cancel path → refundEscrowForCancelledBooking :2302 → escrow → customer wallet
dispute → openEscalation :2785 → admin resolves → release or refundG. Data model (2026-09-06)
| Table | Rows | Role |
|---|---|---|
sr_service_categories | 120 | service taxonomy |
sr_service_providers | 0 | providers (unexercised currently) |
sr_service_bookings | 0 | bookings (unexercised currently) |
sr_service_escrow_orders | 0 | escrow holds |
H. Financial impact
Escrow-first: money held on booking, released on completion (→ provider) or refunded on cancel (→ customer), 5% commission on release. This is the reference escrow pattern — mirror it for Freelancer and Classifieds. See ../../40-financial/central-finance-ledger.md.
K. State machine (sr_service_bookings)
requested → accepted → in_progress → completed (customer-confirmed) → released with cancelled (refund) / escalated (dispute → resolved). Escrow: held → released | held → refunded.
L. Errors (prefix SVC-E)
SVC-E001escrow not released — completion not customer-confirmed; check booking status.SVC-E002dispute open —openEscalationcreated; funds stay held until admin resolves.
M / N. Dependencies & change-impact
Wallet (escrow hold/release), commission, invoicing, logistics (materials), notifications. Changing the escrow path affects held funds — re-test hold→release and hold→refund with correct commission.