# PRD — caredirect

Evidence date: 2026-10-19. Source: `git@bitbucket.org:overdrive/caredirect.git` at `5721fda` (`master`, 2020-01-09).

There is no prior PRD in the repository or in Silicon Ark. Requirements below were recovered from code, config, and git history. Provenance is marked on each item.

CMS content (pages, menus, published caregivers, form definitions) lives in the database and is not in git. Requirements that depend on that content are marked **Unknown / Requires Confirmation**.

## Product purpose

CareDirect is a WordPress-based care marketplace for South Africa. Public visitors can become CareGivers or CareSeekers. CareSeekers search activated CareGivers by care category, region, city, languages, and optional date/time, then book and pay via PayGate. CareGivers complete a multi-step profile and are gated until activated for public search.

Provenance: **Documented** (root `README.md`: caredirect.co.za; CareGivers/CareSeekers; search) and **Implemented** (theme + `caredirect` plugin).

Locale signals: PayGate checkout uses `LOCALE=en-za`, `COUNTRY=ZAF`, `CURRENCY=ZAR`. Cellphone validation assumes South African numbers. Provenance: **Implemented**.

## Users and roles

### WordPress user roles

| Role | What they can do | Evidence | Provenance |
|---|---|---|---|
| Public visitor | Browse public pages; open signup/login/search templates if assigned to pages | Theme + page templates | Inferred for content; templates **Implemented** |
| `caregiver` | Access caregiver profile tabs; manage availability/experience/banking; appear in search when activated | `themes/caredirect/inc/custom-roles.php`; capability checks | Implemented |
| `careseeker` | Search and book caregivers; careseeker-oriented profile areas | Same custom-roles file; seeker signup | Implemented |
| `administrator` | Full admin; receive caregiver application emails; approve/reject care roles | Standard WP + `update_approval` / REST role edit | Implemented |
| Facebook-linked user | Register/login via Facebook OAuth when `CC_FB_LOGIN` is 1 | `facebook/sdk/init.php` | Implemented |

The theme `add_new_roles()` also **removes** WordPress roles `contributor`, `author`, and `editor`. Provenance: **Implemented**.

### Care service roles (database, not WP roles)

Job types (Nanny, Au Pair, Babysitter, Tutor, and others from seed JSON) live in `{prefix}cc_care_roles`, linked to users via `{prefix}cc_user_care_roles` with status Pending / Under Review / Approved / Declined / Cancelled. Provenance: **Implemented** (`class.CC_Roles.php`).

## Main workflows

### W1 — Sign up as CareGiver

Trigger: visitor opens the Become a Caregiver page template.

Behaviour in code:

1. Template `become-a-caregiver.php` posts AJAX `ajaxregister` with nonce `registersecurity`.
2. If referer is `/become-a-caregiver/`, user role is set to `caregiver`.
3. Validation filter `validate_user_data` checks terms, names, at least one contact method, SA cellphone rules, password rules, uniqueness.
4. User is inserted; activation key stored in `{prefix}cc_user_activations`; key sent by email or SMS based on preferred contact method (max 3 sends).
5. On successful verify, user is signed in and redirected to `/me/` (or `returnurl`).

Provenance: **Implemented**. Live page slug and menu labels are **Unknown** (DB).

### W2 — Sign up as CareSeeker

Trigger: visitor opens the Become a CareSeeker page template.

Behaviour: AJAX `ajaxregisterseeker`; role set when referer is `/become-a-seeker/`. Same activation pattern as caregiver.

**Requires Confirmation:** template/page branding uses “become-a-careseeker” while role assignment checks `/become-a-seeker/`. If the live slug does not match, seeker role may not be applied. Provenance: **Implemented** discrepancy.

### W3 — Login / password reset / Facebook

- Login template → AJAX `ajaxlogin`. Username may be email or SA cellphone. Inactive users are prompted to verify.
- Forgot-password template → AJAX `ajaxreset` (email, SA ID, or passport); new password emailed or SMS’d; max 3 resets/day.
- Facebook: `?loginFacebook=1` → OAuth → `admin-ajax.php?action=cc_facebook`. Creates or links users; can assign caregiver/careseeker from redirect URL substrings.

Provenance: **Implemented**. Whether Facebook app credentials are configured in production is **Unknown**.

### W4 — CareGiver profile completion and approval

Trigger: logged-in caregiver visits profile (`/me/` pattern).

Steps driven by user meta `registration_step`:

1. Personal details → advances to `experience`
2. Experience → advances to `banking`
3. Banking → advances to `approval` (OTP required for sensitive banking/contact changes)
4. Submit approval → emails administrators; sets `caregiver_activated` and `approval_sent`; clears `registration_step`

Public search requires `caregiver_activated = 1`. Provenance: **Implemented**.

Per care-job-role approve/reject is available to admins via REST `edit_item_role` and approval UI. Provenance: **Implemented**.

### W5 — Find a CareGiver

Trigger: visitor opens Search page template (`find-a-caregiver.php`).

Filters in UI: keyword, care category (child/adult/home/pet), region, city (AJAX by region), date, start/end time, languages.

Backend AJAX `search_caregivers` restricts to users with caregiver capability and `caregiver_activated = 1`, then applies keyword, `work_region`, `work_city`, `dates_enabled`, languages, and time-window checks against `dates_repeat_data`.

Provenance: **Implemented**. Region cascade uses theme REST `GET .../cities/?region=...`.

### W6 — Book and pay

Trigger: CareSeeker books from caregiver profile UI.

1. Theme helpers insert a pending row in `cco_cc_booked_caregiver` (table has no CREATE in plugin activation — schema origin **Unknown**).
2. Checkout page template initiates PayGate PayWeb3 (ZAR, return `/thank-you/`).
3. Thank-you page validates checksum, queries PayGate, sets payment completed and booking approved.

Provenance: **Implemented** (`tpl-checkout.php`, `tpl-thankyou.php`, `paygate.payweb3.php`). Production merchant ID vs sample values: **Requires Confirmation**.

### W7 — Ratings and reviews

Plugin class `CC_Ratings` uses `{prefix}cc_user_ratings` (`from_user_id`, `to_user_id`, `booking_id`, `rating`). Theme UI and AJAX `submit_custom_review` use hardcoded `cco_user_ratings` with different column names (`rating_from`, `rating_to`, `review_text`). Provenance: **Implemented** dual models — which is live is **Unknown / Requires Confirmation**.

### W8 — Training academy / help center / referrals

Page templates exist for Training Academy and Help Center. Referral keys table and refer-a-friend UI exist (`class.Referrals.php`, profile menu). Exact public content and enablement: **Unknown**.

## Functional requirements

### FR-001 — CareGiver registration

| Field | Value |
|---|---|
| Requirement | A visitor can register as a CareGiver with name, email and/or cellphone, preferred contact method, password, and accepted terms, then activate via emailed or SMS key. |
| Actor | Public visitor |
| Trigger | Become a Caregiver form submit |
| Inputs | Form fields + nonce `registersecurity` |
| Expected behaviour | User created with role `caregiver`; activation row; message sent; verify then login |
| Validation | `validate_user_registration` |
| Errors | Validation WP_Error; spam after 3 activation sends |
| Evidence | `become-a-caregiver.php`, `ajax_register`, `process_user_signup` |
| Implementation | Implemented |
| Confidence | High |

### FR-002 — CareSeeker registration

| Field | Value |
|---|---|
| Requirement | A visitor can register as a CareSeeker via the CareSeeker signup template and AJAX handler. |
| Actor | Public visitor |
| Trigger | Become a CareSeeker form submit |
| Evidence | `become-a-careseeker.php`, `ajax_register_seeker` |
| Implementation | Implemented |
| Confidence | Medium — slug/referer mismatch risk |
| Notes | Confirm live page slug matches `/become-a-seeker/` check |

### FR-003 — Authentication

| Field | Value |
|---|---|
| Requirement | Users can log in with email or cellphone and password; inactive accounts must verify; password reset via email/ID/passport; optional Facebook login when enabled. |
| Evidence | `login.php`, `forgot-password.php`, `CCFacebook` |
| Implementation | Implemented |
| Confidence | High for password path; Medium for Facebook production enablement |

### FR-004 — CareGiver activation gate

| Field | Value |
|---|---|
| Requirement | Only caregivers with `caregiver_activated = 1` appear in public search results. |
| Evidence | `search_caregivers` AJAX filter |
| Implementation | Implemented |
| Confidence | High |

### FR-005 — Profile completion

| Field | Value |
|---|---|
| Requirement | CareGivers complete personal details, experience, banking, and approval submission before full marketplace participation. |
| Evidence | Profile tabs; `registration_step` transitions; `update_approval` |
| Implementation | Implemented |
| Confidence | High |

### FR-006 — OTP for sensitive changes

| Field | Value |
|---|---|
| Requirement | Contact and banking updates require a short-lived OTP delivered by email or SMS and supplied via `X-CC-OTP` / form field. |
| Evidence | `class.OTP.php`; `trigger_contact_OTP`; banking/contact update paths |
| Implementation | Implemented |
| Confidence | High |
| Notes | OTP is **not** the account-activation key mechanism |

### FR-007 — Caregiver search

| Field | Value |
|---|---|
| Requirement | Seekers can filter activated caregivers by category, region, city, keyword, languages, and optional date/time availability. |
| Evidence | `find-a-caregiver.php`; `search_caregivers` |
| Implementation | Implemented |
| Confidence | High |

### FR-008 — Booking and PayGate payment

| Field | Value |
|---|---|
| Requirement | A CareSeeker can create a booking and pay via PayGate PayWeb3; successful payment updates booking payment and status. |
| Evidence | Profile booking UI; checkout; thank-you; `cco_cc_booked_caregiver` |
| Implementation | Implemented |
| Confidence | Medium — table DDL and production credentials not in install path |

### FR-009 — SMS and email notifications

| Field | Value |
|---|---|
| Requirement | System sends verification, password reset, banking/contact OTP, and application emails/SMS using CareComms templates. |
| Evidence | `class.Comms.php`; templates under `templates/emails` and `templates/sms` |
| Implementation | Implemented |
| Confidence | High for code path; production SMS credentials/config **Requires Confirmation** |

### FR-010 — REST API for locations and caregiver profile data

| Field | Value |
|---|---|
| Requirement | Authenticated (and some public location) REST endpoints under CareDirect namespaces support locations, caregivers, roles, training, and references. |
| Evidence | `api/init.php`, controllers |
| Implementation | Implemented |
| Confidence | High for presence; Medium for which consumers call them in production |

## Integrations (product-facing)

| System | Purpose | Direction | Provenance |
|---|---|---|---|
| PayGate PayWeb3 | Booking payment | Outbound initiate/process; inbound return/query | Implemented |
| CLX XMS | SMS | Outbound | Implemented |
| Facebook Graph v2.2 | Social login | OAuth | Implemented when enabled |
| Amazon S3 | Media uploads | Outbound | Config present; plugin enablement Unknown |
| WP Mail / WP Mail SMTP | Email | Outbound | Implemented |

## Constraints

- WordPress 4.8.2 is end-of-life by modern standards. Security and PHP compatibility for current hosts: **Requires Confirmation** before any change work.
- Calendar feature flag `CC_CALENDAR_DISABLED` is `True`. Availability search uses user meta, not the `user_availability` table UI. Provenance: **Implemented**.
- Hardcoded secrets in the tree are a constraint on safe sharing of the repository. Provenance: **Implemented**.

## Out of scope / unknown

- Mobile apps or non-WordPress clients — none found in this repository.
- Multi-country expansion beyond ZA location seed data — world country tables exist; search UX is ZA-oriented.
- Commercial pricing, commission, and criminal/ID verification product rules beyond checkout UI labels — **Unknown / Requires Confirmation**.

## Traceability note

Detailed business rules: `business-rules.md`. Feature inventory: `features.md`. Technical map: `technical-documentation.md`.