gw-svelte/docs/onboarding.md

# Onboarding

How a Goodwalk client comes into the system, how their record is shaped, and how
that record evolves over time.

## Flow at a glance

1. **Enquiry / email claim** — the user signs in to `clients.goodwalk.co.nz`
   with a one-time code. A `client_profiles` entry is created keyed by the
   lower-cased email.
2. **Onboarding form** (`src/lib/components/OnboardingPage.svelte`) — a 5-step
   form: Owner Details → Dog Details → Health → Behaviour → Sign. Every
   question must be answered; there is no skip / mark-complete shortcut.
3. **Submit** — the form posts to `POST /api/onboarding-submit`. The backend
   validates, stores a `submissionSnapshot` on the profile, sends the owner an
   email + PDF, and flips `onboardingCompleted: true`.
4. **Admin dashboard** (`src/lib/components/admin-dashboard/AdminDashboard.svelte`)
   surfaces pending and completed clients, and now lets the owner change a
   client's lifecycle status.

## Where data lives today

| Thing | Storage | Source of truth |
| --- | --- | --- |
| Client profiles | `mail-api/data/client_profiles.json` (mirrored into `admin_db` KV) | `_client_profiles` dict in `main.py` |
| Onboarding drafts (in-progress, per email) | `mail-api/data/drafts.json` | `_drafts` dict |
| Submitted onboarding snapshot | Inside the client profile as `onboardingSubmission` / `submissionSnapshot` | same |
| Activity feed (admin actions) | SQLite via `admin_db.record_event` | same |
| Legacy historical data (Gravity Forms exports) | `data/legacy-onboarding.json`, `data/legacy-contracts.json`, `data/legacy-clients.json` | regenerated from the CSVs in repo root |

The plan is to move the JSON file to Postgres later; the JSON shape is already
relational-friendly (see *Postgres target* below).

## Client profile shape

Keyed by lower-cased email. Fields are merged over time as the client moves
through the funnel.

```jsonc
{
  "fullName": "Shelley McCabe",
  "phone": "+6421328907",
  "address": "...",
  "dogName": "Maisie",
  "dogBreed": "...",
  "dogAge": "2015-04-28",
  "services": ["Tiny Gang Pack Walks"],
  "onboardingCompleted": true,
  "onboardingSubmittedAt": "2026-03-14T16:14:20",
  "onboardingSubmission": { /* full 5-step snapshot */ },
  "welcomePackSentAt": "...",
  "welcomePackOffer": { "serviceType": "...", "priceDetails": "...", "startDate": "..." },
  "birthdayAutoSend": false,
  "birthdayEmailLastSentAt": "...",
  "lastEnquiryAt": "...",
  "lifecycle": {
    "status": "active",        // active | paused | cancelled | archived
    "reason": "",
    "changedAt": "2026-05-20T10:11:00",
    "changedBy": "info@goodwalk.co.nz"
  },
  "lifecycleHistory": [
    { "status": "active", "reason": "", "changedAt": "...", "changedBy": "..." }
  ]
}
```

## Lifecycle status

Soft-delete only. **No client is ever removed**, so we keep the full history
for retention / newsletter work.

| Status | Meaning | Outreach included? |
| --- | --- | --- |
| `active` | Currently walking with us. | Yes — pending + completed + birthdays |
| `paused` | Temporarily not walking (holiday, recovery, etc.). | Yes — still on outreach lists |
| `cancelled` | No longer a client. Kept on file. | **No** — excluded from outreach |
| `archived` | Long-term inactive. Hidden from default views. | **No** — excluded from outreach |

Defaults: every client starts as `active`. A missing `lifecycle` block is
treated as `active` by the API and the dashboard.

### Filters that respect lifecycle

`_client_is_reachable(profile)` in `mail-api/main.py` is the single gate.
`cancelled` and `archived` are filtered out of:

- `GET /owner/pending-onboarding`
- `GET /owner/completed-onboarding`
- `GET /owner/birthdays`

`GET /owner/all-clients` returns **everyone**, regardless of status, so the
admin can always find a former client. The status pill on each row makes the
state obvious.

### Changing a client's status

Admin dashboard → Clients tab → row action **"Change status"**. Opens a modal
with the four status options and an optional 500-char reason. Saving calls:

```
POST /api/owner/client-status
Authorization: Bearer <admin session token>
Content-Type: application/json

{
  "email": "owner@example.com",
  "status": "paused",
  "reason": "Moving house, back in June"
}
```

The backend writes the new `lifecycle` block, appends to `lifecycleHistory`
(capped at the last 50 entries), and records an
`owner_client_status_changed` event in the activity feed.

## Legacy data migration

Two CSV exports from the old Gravity Forms install:

- `dog-enrolment-form-2026-05-20.csv` — 72 onboarding submissions (2022–2026).
- `goodwalk-contract-2026-05-20.csv` — 39 contract signings (2022-06 → 2024-02).

Two cleansing scripts produce relational-friendly JSON:

```
node scripts/clean-legacy-onboarding.mjs   # → data/legacy-onboarding.json
node scripts/clean-legacy-contracts.mjs    # → data/legacy-contracts.json
                                           # also enriches legacy-onboarding.json
                                           # and writes data/legacy-clients.json
```

### Importing legacy clients into production

The deploy pipeline ships these 36 clients into the live system on every
deploy. The flow:

1. `deploy.ps1` runs `scripts/build-legacy-seed.mjs`, which folds the three
   legacy JSON files into one email-keyed dict shaped like the live
   `_client_profiles` entries. Output: `mail-api/legacy-clients-seed.json`.
2. The mail-api `Dockerfile` `COPY`s that file to `/app/legacy-clients-seed.json`
   so it lives **outside** the persistent `mail_api_data` volume — every
   deploy carries a fresh copy.
3. On boot, `_merge_legacy_seed_if_present()` adds every email that is not
   already in `_client_profiles`, persists the result to JSON + admin_kv,
   and never overwrites a live entry. Re-running is idempotent.

Each imported client is created with `lifecycle: { status: 'archived' }` so
they don't pollute outreach lists. The admin can promote any of them back to
`active` from the dashboard. Provenance (entry IDs, signature URL, PDF URLs)
is preserved on the `legacy` field of every profile.

To skip the rebuild on a hotfix deploy use `deploy.ps1 -SkipLegacySeed`; the
previous seed file is reused as-is. To regenerate locally:

```
node scripts/build-legacy-seed.mjs
```

The contracts script backfills owner email + postal address onto onboarding
records where a contract row matches (by owner name, then dog name, then a
unique surname). At present: **38 of 72** onboarding rows now have an email
attached; the rest were submitted after the contract form was retired in
2024-02 and will need an email-claim flow before they can sign in.

### Known gaps in the legacy data

- 34 onboarding rows have no email (mostly post-2024-02).
- Dog **breed** was never collected by the old forms — `null` everywhere.
- Owner **address** was only collected on the contract form, not on
  onboarding directly.
- One vet phone number (`6307168`) couldn't be normalised to E.164 — kept
  as `phoneRaw` only.

## Postgres target

The JSON shapes already map cleanly onto a relational schema. Suggested tables
once we migrate off the JSON file:

```sql
clients (
  email TEXT PRIMARY KEY,
  first_name, last_name, phone, phone_raw,
  address, address_street, address_line2, address_suburb,
  address_city, address_postal_code, address_country,
  -- lifecycle
  lifecycle_status TEXT NOT NULL DEFAULT 'active',  -- enum: active|paused|cancelled|archived
  lifecycle_reason TEXT,
  lifecycle_changed_at TIMESTAMPTZ,
  lifecycle_changed_by TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

client_status_history (
  id SERIAL PRIMARY KEY,
  client_email TEXT REFERENCES clients(email),
  status TEXT NOT NULL,
  reason TEXT,
  changed_at TIMESTAMPTZ NOT NULL,
  changed_by TEXT NOT NULL
);

dogs (
  id SERIAL PRIMARY KEY,
  client_email TEXT REFERENCES clients(email),
  name TEXT, surname TEXT, date_of_birth DATE, breed TEXT
);

onboarding_submissions (
  id SERIAL PRIMARY KEY,
  client_email TEXT REFERENCES clients(email),
  dog_id INT REFERENCES dogs(id),
  legacy_entry_id TEXT,
  legacy_pdf_url TEXT,
  signature_url TEXT,
  vet_name TEXT, vet_address TEXT, vet_phone TEXT, vet_phone_raw TEXT,
  emergency_contact_name TEXT, emergency_contact_phone TEXT,
  health JSONB,           -- vaccinated / allergies / diet / medication
  behaviour JSONB,        -- recall / reactivity / car / commands
  misc JSONB,             -- additional notes / referrals / socials
  signed_on DATE,
  submitted_at TIMESTAMPTZ
);

contracts (
  id SERIAL PRIMARY KEY,
  client_email TEXT REFERENCES clients(email),
  legacy_entry_id TEXT,
  signature_url TEXT,
  pdf_url TEXT,
  consent_text TEXT,
  signed_on DATE
);
```

`health` / `behaviour` / `misc` stay as `JSONB` rather than exploding every
nullable yes/no into a column — it matches the existing
`submissionSnapshot: dict[str, Any]` shape in
`mail-api/mail_api/models.py` and makes the form easier to evolve.

## Things that intentionally don't exist yet

- **Hard delete** of a client. Use `archived` instead. Hard delete would also
  break the activity feed and the legacy import provenance.
- **A "former client" notes log.** If we need anything richer than a 500-char
  reason, the next step is to add a `client_notes` table keyed by email — but
  hold off until the JSON → Postgres migration is done.
- **Re-engagement / win-back emails.** The data is there (lifecycle history +
  email), so this is unblocked whenever marketing wants to send a newsletter
  to past clients. `cancelled` and `archived` rows are still in
  `/owner/all-clients`.