# Technical documentation — caredirect

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

Secrets are not reproduced here. The working tree contains hardcoded credentials in `wp-config.php` and `plugins/caredirect/classes/class.Comms.php`. Treat rotation and removal from VCS as a separate hardening task.

## Stack

| Layer | Technology | Evidence |
|---|---|---|
| CMS | WordPress 4.8.2 | `wp-includes/version.php` |
| Language | PHP (WP-era; exact required PHP version Unknown) | Tree of `.php` files |
| Database | MySQL/MariaDB; table prefix `cco_` | `wp-config.php` |
| Front end | jQuery, Bootstrap assets, Select2, Moment, FullCalendar assets (calendar disabled), Croppie, validation plugins | Theme/plugin `js` / `assets` |
| Deploy | Bitbucket Pipelines + git-ftp status | `bitbucket-pipelines.yml` |
| Media | Amazon S3 via Human Made S3 Uploads | `.S3-Uploads`, `S3_UPLOADS_*` |

## Repository layout

```text
caredirect/
├── wp-admin/, wp-includes/, index.php, wp-*.php   # WordPress core
├── wp-content/
│   ├── themes/
│   │   ├── caredirect/          # Custom theme
│   │   └── twentyseventeen/     # Stock theme
│   ├── plugins/
│   │   ├── caredirect/          # Primary custom plugin
│   │   ├── careconnect/         # Incomplete remnant
│   │   ├── .caredirect-old/     # Archived plugin copy
│   │   ├── .S3-Uploads/         # S3 Uploads (dot-prefixed)
│   │   └── …vendor plugins…
│   ├── uploads/, languages/, ewww/
├── bitbucket-pipelines.yml
├── ccpull.php                   # `git pull` via web
├── mover/                       # Search-Replace-DB 3.1.0
├── adminer.php
├── email-signatures/
├── googlec1c317a3b33727d6.html  # Google site verification
└── README.md
```

## Application architecture

### Theme (`wp-content/themes/caredirect`)

- Underscores-derived theme (stock `README.md` remains).
- Registers WP roles `caregiver` / `careseeker`; removes contributor/author/editor.
- Booking and PayGate checkout/thank-you page templates.
- Registers REST route under namespace used as `api/caredirect/v1/cities/` for region→city cascade.
- Enqueues site JS/CSS for profiles, ratings, availability UI.

### Plugin (`wp-content/plugins/caredirect`)

Bootstrap: `caredirect.php`.

Important constants:

| Constant | Value (non-secret) | Meaning |
|---|---|---|
| `CC_PLUGIN_DIR` / `URL` | plugin paths | Base paths |
| `CC_FB_LOGIN` | `1` | Facebook login enabled in code |
| `CC_CALENDAR_DISABLED` | `True` | Calendar feature off |
| `CC_VERSION` | `1.0.3` | Install migration gate |
| `CC_PREFIX` | `cc_` | Custom table name segment |
| `CC_SALT` | *(omitted)* | OTP seed material |

Activation hook `careconnect_activate` installs static lists, roles, referrals, locations, ratings, availability tables, `social_users`, and `cc_user_activations` when stored version ≠ `CC_VERSION`.

`PageTemplater` injects marketplace page templates into the theme template list.

## Data model

### Custom tables created on plugin activation

Physical names are `{wpdb->prefix}{CC_PREFIX}…` except `social_users` which is `{prefix}social_users`. With prefix `cco_`, examples look like `cco_cc_regions`.

| Logical table | Purpose |
|---|---|
| `cc_regions`, `cc_countries`, `cc_borders` | World geography seed |
| `cc_languages`, `cc_country_languages` | Languages |
| `cc_currencies`, `cc_country_currencies` | Currencies |
| `cc_care_category`, `cc_care_roles`, `cc_user_care_roles` | Care taxonomy + user links |
| `cc_caregiver_logs` | Role approve/reject audit |
| `cc_referral_keys` | Referrals |
| `cc_za_cities` | SA city/suburb seed (`id`, `city`, `suburb`, `code` in DDL) |
| `cc_location_relationships` | Caregiver ↔ location |
| `cc_user_ratings` | Plugin ratings model |
| `cc_user_availability` | Calendar slots |
| `cc_user_activations` | Signup activation keys |
| `social_users` | Facebook identifiers |

### Tables used without CREATE in activation

| Table (as referenced) | Purpose |
|---|---|
| `cco_cc_booked_caregiver` | Bookings / payment status |
| `cco_user_ratings` | Theme reviews (different columns from plugin ratings) |

`$wpdb->role_references` (`user_care_role_references`) is registered; CREATE not found in install methods reviewed.

### Important user meta (non-exhaustive)

`caregiver_activated`, `approval_sent`, `registration_step`, `work_region`, `work_city`, `dates_enabled`, `dates_repeat_data`, `languages`, `id_number`, `password_resets`, `cc_facebook_id`, preferred contact method, cellphone, banking-related fields.

### Schema discrepancy: `za_cities.region`

Runtime queries (`get_za_regions`, work_region lookup, cities by region) expect a `region` column on ZA cities. Install DDL and `city_suburbs_codes.json` seed as found under `classes/` do not define `region`. How production DBs obtained `region` is **Unknown / Requires Confirmation**.

## APIs

REST URL prefix is overridden to `api` in `api/init.php`.

### Plugin namespace `caredirect/v1` (under prefix `api`)

| Route pattern | Methods | Notes |
|---|---|---|
| `/locations`, `/locations/search/`, `/locations/get/{id}/`, `/locations/{city}/` | GET | Location search; search may be unauthenticated |
| `/caregivers`, `/caregivers/{id}`, `/caregivers/me` | GET/PUT | Caregiver resources |
| `/caregivers/{id\|me}/roles` (+ role id, logs) | CRUD | Care roles |
| `/caregivers/{id\|me}/training` | CRUD | Training meta |
| `/caregivers/{id\|me}/reference/{ref_id}` | POST/PUT | References |

### Theme namespace used by UI

| Route | Purpose |
|---|---|
| `api/caredirect/v1/cities/` | Cities for `region` query param |

Exact live URL shape depends on WP rewrite / `rest_route` query usage. Search UI uses `rest_route=/api/caredirect/v1/cities/`.

### AJAX (admin-ajax)

Notable actions: `ajaxregister`, `ajaxregisterseeker`, `ajaxlogin`, `ajaxreset`, `search_caregivers`, profile update actions, `submit_custom_review`, `cc_facebook`, caregiver available-dates endpoints.

## External integrations

### PayGate PayWeb3

- Client: `themes/caredirect/paygate.payweb3.php`
- Endpoints: `secure.paygate.co.za/payweb3/{initiate,process,query}.trans`
- Flow: checkout initiate → browser POST to process → thank-you query
- Currency ZAR; return `home_url()/thank-you/`

### CLX / Sinch XMS SMS

- SDK: `plugins/caredirect/Clx/`
- Default endpoint: `https://api.clxcommunications.com/xms`
- Wrapper usage: `CareComms::send_sms` → `Client::createTextBatch`

### Email

- `CareComms::send_email` → `wp_mail`
- Optional vendor: WP Mail SMTP 0.10.1
- HTML/SMS templates under plugin `templates/emails` and `templates/sms`

### Facebook Connect

- Graph API version `v2.2`
- Callback: `admin-ajax.php?action=cc_facebook`
- Settings option: `careconnect_fb_connect`
- Scopes: `email`

### Amazon S3

| Constant | Non-secret value |
|---|---|
| `S3_UPLOADS_BUCKET` | `caredirect` |
| `S3_UPLOADS_REGION` | `eu-central-1` |
| `S3_UPLOADS_KEY` / `SECRET` | Present; values omitted |

Plugin directory is `.S3-Uploads` (leading dot). Whether WordPress discovers it without rename/symlink is **Unknown**.

## Authentication and security

| Mechanism | Notes |
|---|---|
| WordPress auth cookies | Standard login / `wp_signon` / `force_login` helpers |
| Nonces | Registration, login, profile AJAX |
| Activation keys | 5-char keys in `cc_user_activations` |
| OTP | HOTP-style for banking/contact; salt constant in plugin |
| Capabilities | Role names used as caps; admin `manage_options` for FB settings |
| Ops exposure | `ccpull.php` runs `git pull`; `adminer.php` and `mover/` are web-capable DB tools if reachable |

WordPress 4.8.2 is obsolete by current WP standards. Hosting hardening and upgrade path: **Requires Confirmation**.

## Background jobs / queues

No Redis/Rabbit/worker framework found. WordPress cron (`wp-cron.php`) is present as core. Theme pending-booking cleanup runs in request path logic (not a separate queue). Provenance: **Implemented** / **Inferred**.

## Storage

- Local `wp-content/uploads/` present in tree structure.
- S3 intended for uploads when S3 Uploads is active.
- Uploads content itself is typically environment-specific; what is committed vs ignored was not exhaustively inventoried.

## Monitoring

- Google site verification HTML file at repository root.
- No application APM/config found.
- Task-creation scan mentioned Sonar files that are **not** in `5721fda`.

## Deployment

```text
Bitbucket (master)
  → Pipeline (python:3.5.7): apt install zip git git-ftp
  → git ftp status -vv -u $USR_NME -p $USR_PWD ftp://$SRV_HST/
```

Observations:

- Active step is **status**, not **push**. Deploy may be manual or elsewhere.
- Env vars: `USR_NME`, `USR_PWD`, `SRV_HST`.
- `ccpull.php` suggests some environments pull via HTTP.
- `mover/` supports search-replace URL migrations for WP moves.

## Development and testing

- No PHPUnit, Jest, or CI test suite found for the custom plugin/theme.
- Debug plugins present (`debug-plugin-activation-errors`, rewrite analyzer).
- Pipeline does not run tests; only git-ftp status.

## Configuration

| Item | Location | Notes |
|---|---|---|
| DB / salts / S3 | `wp-config.php` | Gitignored in `.gitignore` but present in inspected clone |
| Facebook app | WP option `careconnect_fb_connect` | Admin UI |
| SMTP | WP Mail SMTP options (DB) | Unknown values |
| Feature flags | `CC_FB_LOGIN`, `CC_CALENDAR_DISABLED` | Compile-time defines |

## Dependencies (vendor plugins)

See `features.md` inventory. Notable commercial packages: Revolution Slider, WP All Import Pro.

## Related Silicon Ark documents

- `project-plan.md` — status and scope
- `prd.md` — requirements and workflows
- `features.md` — feature inventory
- `business-rules.md` — domain rules

## Open technical questions

1. Is production still on WordPress 4.8.2 / this commit?
2. Are PayGate credentials in checkout sample or live?
3. How was `za_cities.region` introduced?
4. Which ratings table is authoritative?
5. Are `.S3-Uploads` and `.caredirect-old` intentionally hidden from the plugin list?
6. Does the Bitbucket pipeline ever deploy, or only check FTP status?
7. Should `ccpull.php`, `adminer.php`, and `mover/` remain web-accessible?