`PLAN.md`

163 lines
# Project: Animals — Master Plan

**Goal.** Build the dominant consumer + B2B platform for the U.S. animal-care
ecosystem. Mirrors the architecture of `lawyer-directory-builder` and
`professional-directory` (doctors), but for vets, clinics, breeds, breeders,
shelters, groomers, and trainers — with three monetization rails baked in
from day one.

Owner: Steve. Working dir: `~/Projects/animals/`. PG DB: `animals_directory`.
Ports: 9720 (viewer), 9721 (ingest), 9722 (audit), 9723 (leads).

---

## 1. Why this works

The exact pattern already proved itself twice:
- `lawyer-directory-builder` — CalBar full-scrape, audits, lead funnel, EZ-Upgrade $499 site product.
- `professional-directory` — NPI doctors, LA County focus, 5-agent crawler/enrich/dedupe.

Both already have `site_audits → site_mockups → upgrade_orders` and `leads`
tables. We mirror that schema exactly, swap "law firm" → "vet clinic", add the
animal-specific entities (breeds, shelters, breeders, groomers, trainers), and
flip on the same monetization rails.

The animal market is *less crowded* than legal/medical for digital tooling:
- ~32k accredited vet hospitals in the US (AAHA + non-AAHA ≈ 70k+ practices).
- Most independent vet clinic websites are objectively bad (WordPress 2014,
  no online booking, no schema.org, no mobile). A real upgrade is a slam-dunk pitch.
- Pet owners search constantly: breed traits, "vet near me", emergency clinics,
  groomers, breeder vetting, rescue/adoption.

---

## 2. Entity model (high level)

| Entity        | Source(s)                                            | Volume target |
| ------------- | ---------------------------------------------------- | ------------- |
| breeds        | AKC + UKC + FCI + cat fancier assoc + exotic         | ~500          |
| veterinarians | state license boards (CA, TX, FL, NY first)          | ~120k US      |
| clinics       | AAHA accredited list + state corp registries + GMaps | ~70k US       |
| shelters      | Petfinder + ASPCA + state SPCAs                      | ~14k US       |
| breeders      | AKC parent club referrals + state ag registries      | ~60k US       |
| groomers      | NDGAA + state directories                            | ~40k US       |
| trainers      | CCPDT + APDT directories                             | ~20k US       |
| pet_stores    | independent pet stores (PIDA + state biz registries + GMaps) + chains (Petco/Petsmart/Pet Supplies Plus locator pages) | ~22k US |
| boarding      | IBPSA + state biz registries                         | ~9k US        |
| dog_parks     | OSM + city parks-dept feeds                          | ~5k US        |
| emergency_vets| AAHA accredited emergency category + VECCS           | ~1.5k US      |

Each business entity has the same site_audit + mockup + upgrade_order pipeline.

---

## 3. Data sourcing rules (MUST follow Steve's standing rules)

- **No stock images.** Public domain only — Wikimedia Commons, USDA, NIH/NLM,
  AKC public photos, owner uploads. Empty image > stock image.
- **Source-traceable.** Every fact stores `source_url` and a `raw_records` row.
  No fabricated bios, no hallucinated phone numbers.
- **Opt-out honored.** `opt_out_flag` on every business + professional. A single
  email request removes them from public surfaces within 24h.
- **State-board ToS.** We honor robots.txt and rate limits. CalBar-style scrape
  patterns are reused (proven legal in lawyer project).

---

## 4. Monetization (three rails, all turned on day one)

### Rail A — Display ads on every directory page
- Every clinic page, vet page, breed page = ad-supported (AdSense first, then
  direct contextual ads — pet food, pet insurance, Chewy/Petco affiliate, etc.).
- Revenue model at scale: 70k clinics × 200 sessions/mo × $4 RPM = ~$56k/mo.
- See `src/monetize/ad_engine.js` (in-house) + AdSense fallback.

### Rail B — Lead-gen funnel ("Find a Vet" / "Find a Trainer")
- Public form on every directory page → `leads` table → matches top 3 nearby
  clinics by ZIP + species + service type → SMS/email blast to those clinics
  via George (gmail agent on tailnet) and Twilio (later).
- Pricing: $25/lead for vets, $15/lead for groomers/trainers, $50/lead for
  breeders. 5x more sustainable than ads if conversion is real.

### Rail C — White-label upgraded-website upsell ("Vet Site Upgrade")
- For every clinic w/ site_audit score < 60: auto-generate 3 mockup variants
  (Editorial Noir, Clean Modern Light, Bold Confident) via Playwright + a few
  EJS templates. Email the office with screenshots.
- Pricing: $499 setup + $49/mo hosting (Kamatera-deployed Express+EJS, on a
  brandable subdomain we own — see Section 5).
- ~70k clinics with bad sites × 1% conversion × $499 = $349k one-time + $34k MRR.
  Even 0.1% conversion is $35k one-time + $3.4k MRR.

---

## 5. Domain strategy (use GoDaddy / domain-suite MCP)

Two domain decisions:

**A. The consumer-facing directory.** Working name: `animalsdirectory.com`,
fallbacks `animalpages.com`, `petsdirectory.com`, `findavet.com`.

**B. The B2B SaaS upsell brand.** This is the brand we sell clinics on.
Candidates to check via domain-suite (`check_availability`):
- vetsites.com, vetpages.com, clinicpages.com, pawpages.com, vethaus.com,
  paws.site, vet.site, animalsite.com, kennelweb.com, clinicfront.com,
  vetfront.com, vethq.io, healvet.com, vetlinked.com, vetbranded.com,
  vetcrafted.com, hellopaws.com, paws.studio, bigpawvet.com, petsetgo.com,
  pawloft.com, vetloft.com, paws.host, vetbloom.com, vetorigin.com.

Pick 3 finalists by: (1) available, (2) ≤$2k registration, (3) brandable in
under 5 syllables, (4) `.com` preferred (per Steve's default-TLD rule).

`src/scripts/research_domains.js` runs this lookup + writes results to
`docs/domain_research.json` + a markdown summary.

---

## 6. Build order (week 1)

1. ✅ Scaffold project layout, package.json, ecosystem.config.js
2. ✅ Postgres schema (migration `001_initial_schema.sql`)
3. Seed AKC breed list (≈200 dogs) + cat breeds
4. Seed sources table (state vet boards, AAHA, Petfinder)
5. Wire Express viewer w/ `/`, `/breeds`, `/breeds/:slug`, `/vets`, `/clinic/:id`,
   `/groomers`, `/pet-stores`, `/shelters`, `/breeders`, `/trainers`, `/dog-parks`,
   plus city pages `/in/:city-:state` that show **all categories on one map**.
   Every detail page embeds a **Leaflet + OpenStreetMap** map (no API key, free,
   tile attribution per OSM ToS). City pages use a clustered marker layer.
6. Site-audit job + mockup generator (Playwright)
7. Lead form + email blast (via George)
8. Domain research script + finalist picks
9. claude-codex debate on PLAN.md + monetization.md → converge
10. Launch `animals-hawk` watchdog (launchd, every 30m)

---

## 7. Watchdogs / ops

- pm2: `animals-viewer`, `animals-ingest`, `animals-audit`, `animals-leads`
- launchd: `~/Library/LaunchAgents/com.steve.animals-hawk.plist` pings
  `localhost:9720/healthz` every 30m and restarts via pm2 on failure.
- All long-running jobs under pm2 (per Steve's rule — no cloud agents).

---

## 8. What's explicitly NOT in v1

- Booking/scheduling integration (vet calendars are a swamp; defer)
- Telehealth (regulated; defer)
- Mobile app (web-first; defer)
- Pet insurance comparison (PII-heavy; defer)
- Genetic-testing affiliate (defer to v2)

---

## 9. Risk register

| Risk                                | Mitigation                                    |
| ----------------------------------- | --------------------------------------------- |
| State vet boards block scraping     | Same pattern that worked for CalBar; throttle |
| Clinics complain about cold pitches | Opt-out flag + one-click removal              |
| Stock-image rule violation          | Hard gate in audit job — never use Unsplash   |
| Stripe fee on $499 = $14            | Acceptable; price covers it                   |
| Trademark on "AKC" / "AAHA"         | Use only as factual references, never logos   |