Sukoon.mom — the real WhatsApp product

0Read this first

We have a validated prototype of this product built on an agent framework (OpenClaw). It works, real parents used it, and it proved the demand and the conversation quality. It is not the foundation we scale on — it drives WhatsApp as a "linked device", which is against WhatsApp's terms for automation, keeps getting de-linked, and handles payments and subscription state manually.

Your job: rebuild the same product as a proper WhatsApp Business product on modern, boring, reliable technology — with automated subscription billing as the first milestone.

Read §0–§3 for orientation, §4–§10 for the system, §14–§16 before you write a line of code. §16 exists specifically so you don't get sidelined.

1What we're building

Sukoon is a WhatsApp companion for new parents. A parent messages our number, tells us about their baby once, and then has a calm, always-available helper that:

• Answers everyday baby questions (feeding, sleep, growth, vaccines, common symptoms) grounded in trusted Indian pediatric guidance, in the parent's language (Hindi / Marathi / English).
• Remembers their baby — age, term/preterm, conditions, what happened last week — so answers are specific, not generic.
• Flags red-flag symptoms and tells them to call a doctor / emergency services. It is explicitly not a doctor and never diagnoses or prescribes.
• Turns messy parent notes into timelines, checklists, and questions to ask their pediatrician.

Business model

10-day free trial → ₹199/month per baby. Recurring via UPI AutoPay. The bot handles trial, expiry, renewal prompts and premium gating automatically once billing is wired.

Why WhatsApp

Indian parents already live on WhatsApp — zero app install, zero learning curve, works on any phone. That is the entire distribution thesis. The product must feel like texting a knowledgeable, kind friend, not "using an app".

2Product principles (non-negotiable)

3The prototype & exactly what to reuse

The prototype lives in a scrubbed repo you already have access to: sukoon-baby-dev (bot brain) and sukoon-web (the web app). Treat sukoon-baby-dev as the product specification, file by file:

4Target architecture

Boring, proven, cheap to run. Nothing exotic. Everything here is a managed service or a standard library.

Recommended stack

5WhatsApp Business Cloud API — the hard part

This is the riskiest, slowest integration. Spike it first (§14). The LLM is easy; WhatsApp is where projects stall.

What you must set up

1. Meta Business account + WhatsApp Business Platform access.
2. Business verification with Meta (documents; can take days–weeks — start early).
3. A dedicated phone number for the bot. Never a personal number. It cannot already be on a personal WhatsApp account.
4. Message templates pre-approved by Meta for anything we initiate (welcome, trial-ending, renewal, payment confirmation).
5. A public webhook endpoint (HTTPS) registered with Meta, with a verify token + signature validation.

The two rules that shape the whole design

Inbound message flow

Pricing model (know it before you design)

Meta bills per conversation (not per message), in categories (service / marketing / utility / authentication), with a monthly free tier of service conversations. Design implication: batch outbound, avoid needless template sends, and track conversation cost per tenant so unit economics stay honest. A single ₹199/mo subscriber must not cost more than a fraction of that in WhatsApp + LLM fees.

6Data model

Replaces the prototype's JSON registry with real tables. Core entities (fields abbreviated — design the full schema, add timestamps, soft-delete, and indexes on lookup keys):

tenant            -- one family / account
  id, wa_phone_e164 (customer), display_name, locale,
  status, created_at

child             -- one baby (a tenant may have >1 later)
  id, tenant_id → tenant, name, dob, term (full/preterm),
  conditions[], pediatrician, notes, created_at

caregiver         -- mom/dad; who may message
  id, tenant_id, wa_phone_e164, role, name

subscription      -- billing state per tenant/child
  id, tenant_id, child_id, plan (₹199/mo),
  status (trial|active|past_due|expired|canceled),
  trial_start, trial_end,
  current_period_start, current_period_end,
  razorpay_subscription_id, last_payment_at, last_payment_ref

message           -- every inbound/outbound (audit + context)
  id, tenant_id, direction, wa_message_id (idempotency!),
  body, media_url, template_name, created_at

usage_daily       -- throttling + cost control
  tenant_id, date, user_messages, tool_calls,
  llm_tokens, wa_conversations, renewal_nudge_sent

memory            -- long-term curated facts about a child
  id, child_id, kind (fact|concern|plan), text, embedding

journal_entry     -- daily events (symptoms, sleep, feeds, visits)
  id, child_id, date, text, embedding

consent           -- DPDP compliance (§12)
  id, tenant_id, purpose, granted_at, withdrawn_at, source

kb_chunk          -- pediatric knowledge base for RAG
  id, doc, section, text, embedding, source_org, source_year

7Subscriptions & payments Milestone 1

This is your first shippable win and the whole reason the product can make money. Today it's manual (bot quotes UPI, a human verifies and edits JSON). Replace it with Razorpay Subscriptions driving state automatically.

The lifecycle state machine

How it works with Razorpay

1. At signup, create a Razorpay Plan (₹199/mo) once; create a Subscription per tenant with a 10-day trial / first-charge date.
2. Parent authorizes a UPI AutoPay mandate (or card) via a Razorpay checkout link sent in chat / on web.
3. Razorpay webhooks (subscription.charged, subscription.halted, payment.failed, etc.) flip subscription.status and period dates in our DB. No human edits JSON ever again.
4. The entitlement check runs on every inbound message: is this tenant premium right now? Gate features accordingly (§8).

Entitlement gating (ported from the prototype rules)

8Conversation engine

The bit that makes it feel human. A single pass per inbound message:

1. Resolve tenant + child (from the sender's WA number).
2. Safety pre-check: a fast classifier scans for red-flag symptoms (breathing trouble, blue/grey colour, high fever in young infants, seizures, severe lethargy, dehydration). If hit → respond with escalation guidance immediately, regardless of tier, and still log it.
3. Entitlement check (§7) → decide premium vs free behavior + caps.
4. Build the prompt: system prompt (from SOUL.md rules) + this child's profile + relevant memory/journal (vector search) + relevant KB chunks (RAG) + recent conversation.
5. Call the LLM (strong model for health-adjacent, cheap model for chit-chat/routing).
6. Post-process: ensure the "not a doctor" disclaimer is present on health replies; enforce length by tier; strip anything unsafe.
7. Send via WhatsApp; persist the message; update usage counters; optionally journal a memory note.

Grounding & language

• RAG over the pediatric KB (the iap_* docs, expandable). Answers cite the source org + rough year. Premium tier may additionally do live guideline lookups from trusted bodies (WHO/AAP/NHS/IAP).
• Language detection per message; reply in the parent's language (Devanagari for Hindi, Latin/Devanagari for Marathi as they write). Safety text especially must be crystal-clear in their language.

9Onboarding flow (self-serve)

The whole loop must run without a human. A parent should go from "never heard of us" to "trial active, baby set up" in one WhatsApp conversation (kicked off from an ad, a link, or a QR on sukoon-web).

• Collect the minimum to be useful: baby name, DOB, term/preterm, any known conditions, primary language. Capture conversationally, not a rigid form.
• Consent is captured here (data use + medical disclaimer) and stored (§12).
• Model onboarding as an explicit state machine so a parent can drop off and resume. Don't rely on the LLM to "remember where we were" — persist the step.

10Memory & knowledge

11Multi-tenancy & isolation

• Tenant = the family, keyed by the caregiver's WhatsApp number. One business number serves all tenants (Meta routes inbound by sender).
• Every query is tenant-scoped. Row-level scoping on tenant_id everywhere. A bug here = a family sees another family's baby data = catastrophic trust + compliance failure.
• Conversation context is per-tenant. Never build a prompt with another tenant's messages/memory. (The prototype enforced this via session scoping; you enforce it via scoped queries + tests.)
• Support multiple caregivers per tenant (mom + dad) mapping to the same child.

12Compliance, privacy & safety

This is a health-adjacent product storing PII about infants. Compliance is not a phase-2 nicety; design it in now — it's far cheaper than retrofitting and it's a genuine trust selling point for a moms' brand.

13Reliability & operations

14Build plan

Phase 0 — De-risk the unknowns Week 1–2

• Spike WhatsApp Cloud API: get a test number, receive a webhook, send a reply, send a template. Prove the whole round trip.
• Spike Razorpay Subscriptions: create a plan, a subscription with trial, complete a UPI AutoPay mandate in test mode, receive the webhook.
• Stand up the skeleton: repo, Postgres, Redis, CI, env config, provider interfaces.
• Start Meta business verification + draft message templates (long lead time — begin now).

Phase 1 — MVP conversation + trial Week 3–5

• Inbound pipeline: webhook → queue → router → engine → reply. Idempotent.
• Onboarding FSM: welcome → consent → capture baby → create tenant/child → start trial.
• Conversation engine v1: system prompt + child context + RAG over KB + safety pre-check + disclaimer. One language first (whatever your test users use), then add.
• Per-child memory (write + retrieve). Tenant-isolation test in CI.

Phase 2 — Payments live Week 6–7

• Full subscription state machine driven by Razorpay webhooks.
• Entitlement gating (premium vs free) on every message.
• Trial-ending + renewal + payment-confirmation templates via scheduler.
• Admin view in sukoon-web: tenants, subscription status, message audit.

Phase 3 — Harden & scale Week 8+

• Multi-language, richer journaling, premium live-lookup, media (parents sending photos).
• Observability dashboards, cost controls, backups, load test.
• Migrate the one live prototype family onto the new system; then open the doors.

15Definition of done

16How not to get sidelined

Read this whenever you feel a rabbit hole opening.

17Open questions for Sanchit

• Business number — which dedicated number do we verify with Meta? (Needs to be a fresh line, not on any personal WhatsApp.)
• Meta business verification — who owns the Meta Business account + verification docs?
• Razorpay account — existing merchant account to reuse, or new one for Sukoon?
• Languages at launch — Hindi + English first? Marathi when?
• Pricing confirmation — ₹199/mo, 10-day trial, per baby — locked, or revisit for launch?
• LLM provider — Gemini or Claude as primary? (Cost vs quality tradeoff.)
• Data residency / legal review — timeline for consent + disclaimer legal sign-off before live payments.
• Migration — when do we move the existing live family off the prototype?

Glossary & links

Reference material

• Spec repo — sukoon-baby-dev (behavior, commerce rules, pediatric KB) — the source of truth for what to build.
• Web app — sukoon-web (Next.js).
• WhatsApp Cloud API docs · Razorpay Subscriptions docs · pgvector · BullMQ · NestJS.
• Git primer for onboarding: Pro Git · Learn Git Branching.