where_woof/docs/PRODUCT-MODEL.md

# Where Woof — Product Model & Pricing (AUD)

Scope: keep small and lean now; rebuild a larger system once there are a few thousand customers.
**Explicitly out of scope (from the old CMS):** the page-builder/CMS flow and SMS campaigns — ignored.

## Two use cases (the core split)

| | **Info tags** (bulk operators: parks, trails, campgrounds) | **Owner-alert tags** (dogs, luggage, valuables) |
|---|---|---|
| What the finder sees | Rich info page (multilingual, custom content per tag) | Return details + call/SMS the owner |
| SMS to owner | **Never** (no SMS → no SMS cost) | **Automatic on every scan with location** (+ finder can also message) |
| Pricing | Per-tag or annual license | $1 tag + annual fee with **metered SMS** |
| Cost exposure | ~zero (DB only) | SMS metered (the business's only real variable cost) |

## How SMS actually fires (important)

- When a finder scans and **approves location → an SMS is automatically sent to the owner**. It is not the scanner's choice (they can *also* send one via the contact form).
- So: **every scan-with-location = 1 SMS = cost**. The throttles (250 m / 10 min, fingerprint 24 h, daily/IP caps) are *cost control*, but different finders at different spots legitimately each alert.
- A heavily-lost dog could generate several SMS/day → that's the meter working as designed (frequent loss → credits consumed → top-ups).

## Costs to design against (AUD, ex GST — 10% GST to add at checkout)

| Item | Cost |
|---|---|
| SMSGlobal **prepaid** (current) | ~**AU$0.06 / SMS** |
| SMSGlobal plans at volume (Build→Scale) | ~$0.03 → ~$0.013 / SMS |
| DB/storage/bandwidth per scan | **negligible** (a scan ≈ 100–150 bytes; 10k scans/day ≈ 1.5 MB/day) — data is not a cost driver, SMS is |
| Tag manufacture (Asia, preset) | your cost basis; retail margin on top |

## Proposed retail pricing (AUD) — pinch points to tune

**Owner-alert tags**
- Tag: **$1.50–2.00** per tag (one-off)
- Annual plan: **$5/year = 10 SMS** (your cost ≈ 60¢ prepaid → ~88% margin)
- **Top-ups**: $2.50 / 5 SMS · $4.50 / 10 SMS · $8 / 20 SMS
- Unused credits: roll over within the year; reset (or cap) at renewal — decide per plan

**Family bundles** (pooled SMS across the account's tags)
- **5 tags / $20 yr** (50 SMS pool) · **10 tags / $35 yr** (100) · **20 tags / $60 yr** (200)
- Cost check @6¢: 20-tag plan = 200 SMS × 6¢ = $12 vs $60 retail → ~80% margin even if fully used

**Info tags (bulk)**
- e.g. **$1.50/tag** one-off **or** an annual operator license (e.g. $30/yr for up to 100 tags + content management) — no SMS, near-100% margin; tune with the parks use case

**✅ Done**: server-side metering (per-tag credits, admin top-up), renewal date + lazy expiry, unlock notice to the owner (ntfy/SMS) when gated by lapsed or credits. **Remaining pinch points:**
1. **Metering enforced server-side** — count only *sent* (OK:0) SMS; block when credits hit 0 → triggers the unlock flow.
2. **Renewal reminders** (30/7/1 days before) + **grace period** (~7 days) before lapsed.
3. **Top-up profitability at the 6¢ prepaid rate** (works above; even better on a plan).
4. **GST** (10%) — decide ex/incl display.
5. Finder-contact SMS counts toward the **same** meter.
6. Bulk-operator licenses vs per-tag — pick per deal.

## The missed location-link flow

- Scan → owner SMS contains a **short URL** (`where-woof.com/s/Ab3xY9` — shortener needed; also keeps lat/lng out of the SMS, which is already ~160-char constrained).
- The link opens a **location page**: embedded Google Map of the finder's position + finder details (phone if left) + link back to the tag page.
- **Unpaid variant**: the SMS/email instead says *"your item was found — pay the $5 annual fee to unlock the details"* (the 2014 `late_payment` flow). ⚠️ No email system yet — use SMTP (hosting) or ntfy on .13 as interim.
- Location page is the owner's private view: keyed by the unguessable short code; decide validity window.

## Product range & variants (coming)

- Tags are **manufactured in Asia → preset IDs** (100 in registry; new runs generate IDs per production order).
- Broader range coming: **sizes, colours, plaques (outdoor), screw-on** etc. → needs `product_variants` (products + variant attributes) later.
- QR/NFC **production step needed** for new runs (QR generation util — the old `qrcode.php` pattern).
- Multilingual info pages (i18n) for the info-tag use case.

## Schema implications (future, keep lean)

- `sms_allocated` / `sms_used` per tag or account + a **top-up ledger** (the old `sms_billing` / `product_network_costs` concept).
- `orders` already has status (pending/paid/lapsed/cancelled) → renewal = new order/period; add `renews_at`.
- `users.paused` (admin pause → gate alerts) + audit log (`product_accounts_actions` pattern).
- `url_shortened` table + `location_page` (scan → location page keyed by code).
- `product_variants` when the range expands.
- Email channel abstraction (ntfy now, SMTP later).