Research
RankFlow AI -- Comprehensive Product Specification
Version: 1.0
docs/research_product.mdOn this page
- UX, Friction Mitigation & Feature Prioritization
- 1. Client Onboarding Flow
- 1.1 Design Philosophy
- 1.2 Entry Points
- 1.3 Onboarding Flow: Screen-by-Screen
- 1.4 Onboarding Progress Indicator
- 1.5 Resume Onboarding Flow
- 1.6 Onboarding Drop-off Analysis & Mitigation Summary
- 2. Client Dashboard UX Specification
- 2.1 Information Architecture
- 2.2 Mobile-First Design Principles
- 2.3 Dashboard Pages
- 2.4 Language Toggle
- 2.5 "Call Support" Button Placement
- 2.6 Report Viewing Experience
- 2.7 WhatsApp-Style Notification Preferences
- 3. Admin Dashboard UX Specification
- 3.1 Information Architecture
- 3.2 Client Management Table
- 3.3 Citation Health Monitoring Dashboard
- 3.4 Content Approval Workflow
- 3.5 Job Monitoring Dashboard
- 3.6 Directory Profile Management
- 3.7 Social Connection Status Overview
- 3.8 Alert System
- 4. Feature Flags & Plan Tiers
- 4.1 Plan Overview
- 4.2 Feature Flag Matrix
- 4.3 Feature Flag Implementation
- 5. Friction Mitigation Strategies
- 5.1 Onboarding Friction
- 5.2 Ongoing Friction
- 7.2 Weekly Digest Design
- 7.3 Alert Types and Thresholds
- 7.4 WhatsApp Notification Strategy
- 7.5 In-App Notification System
- 8. Success Metrics (for the Product Team)
- 8.1 Activation Metrics
- 8.2 Engagement Metrics
- 8.3 Retention Metrics
- 8.4 NPS / Satisfaction Proxy
- 8.5 Support Ticket Volume & Resolution
- 9. Phase 1 Feature Cut (MoSCoW)
- 9.1 Context
- 9.2 MoSCoW Prioritization
- 9.3 Phase 1 Feature Cut Summary Table
- 9.4 Phase 1 Technical Simplifications
- 9.5 18-Week Timeline (Phase 1)
- 9.6 Risk Mitigation for Phase 1
- Appendices
- Appendix A: User Flow Diagrams (Mermaid)
- Appendix B: Glossary
- Appendix C: Kerala Market Context
- Document End
UX, Friction Mitigation & Feature Prioritization#
Version: 1.0
Date: June 2026
Prepared for: Engineering team (single engineer + AI assistance, 18-week build)
Target Market: Indian medical professionals (Kerala Phase 1)
Primary Users: Dr. Sharma (client persona), Agency Admin (operations manager)
1. Client Onboarding Flow#
1.1 Design Philosophy#
The onboarding flow is the single most critical conversion funnel in RankFlow AI. A doctor who drops off during onboarding is a lost customer forever. Every screen must be:
- Mobile-first: 90%+ of doctors will complete this on their smartphone
- Single-column: No side-by-side forms, no complex layouts
- One question per screen: Where possible, break into micro-steps
- Visual, not textual: Use icons, illustrations, and progress indicators instead of paragraphs
- Vernacular-ready: Malayalam labels alongside English for Kerala market
- Always escapable: Doctor can exit and resume anytime via WhatsApp link
Target completion rate: 75%+ (industry average for B2B SaaS: 40-60%)
Target completion time: Under 5 minutes
Primary drop-off points: GBP OAuth (40% drop), Social auth (30% drop), Payment (15% drop)
1.2 Entry Points#
Doctors can begin onboarding through multiple channels:
| Entry Point | Context | Pre-filled Data |
|---|---|---|
| WhatsApp CTA | Salesperson sends onboarding link after call | Phone number |
| Sales Close | Salesperson creates account, doctor completes | Business name, phone |
| Referral Link | Existing doctor refers colleague | None |
| Website | Doctor discovers RankFlow via search/ad | None |
| Admin Created | Admin pre-creates account for sales pipeline | Business name, category |
1.3 Onboarding Flow: Screen-by-Screen#
FLOW OVERVIEW (7 Steps, ~4.5 minutes)
[Welcome] → [Phone Verify] → [Business Info] → [GBP Connect]
↑ ↓
[Done!] ← [Payment] ← [Plan Select] ← [Social Connect]
SCREEN 1: Welcome Screen#
Purpose: Set expectations, build trust, show progress exists
Time estimate: 15 seconds
Drop-off risk: Low (5%)
Layout (Mobile):
┌─────────────────────────────┐
│ [RankFlow Logo] │
│ │
│ "Your Clinic's Online │
│ Presence, Automated" │
│ │
│ [Illustration: Doctor │
│ smiling at phone with │
│ Google Maps ranking #1 ] │
│ │
│ "Get found by patients │
│ on Google, Instagram, │
│ and 30+ websites" │
│ │
│ Step 1 of 7 ───────○○○○○○○ │
│ │
│ [Start Setup] │
│ (Green, full-width button) │
│ │
│ "Takes 5 minutes" │
│ "Setup support: 9AM-9PM" │
│ 📞 Call 1800-RANKFLOW │
│ 💬 WhatsApp Help │
└─────────────────────────────┘
Elements:
- Hero illustration: Animated SVG showing clinic on map with ranking badge
- Trust indicators: "500+ doctors trust RankFlow" (once available), "SSL secured"
- Support access: Sticky "Need help?" FAB (Floating Action Button) bottom-right
- WhatsApp fallback: "Rather do this on WhatsApp? Click here" -- sends user a guided form flow
Interactions:
Start Setup→ Screen 2 (Phone Verification)Call support→ Dials helplineWhatsApp Help→ Opens WhatsApp chat with pre-filled "I need help with onboarding"
SCREEN 2: Phone Verification#
Purpose: Verify identity, establish primary communication channel
Time estimate: 45 seconds
Drop-off risk: Medium (10%) -- OTP delivery failures are common in India
Layout (Mobile):
┌─────────────────────────────┐
│ ← Back │
│ │
│ "Verify Your Phone" │
│ │
│ "We'll send updates and │
│ reports on WhatsApp" │
│ │
│ [🇮🇳 +91 │ 98765 43210 ] │
│ ───────────────────────── │
│ │
│ [Send OTP via WhatsApp] │
│ [Send OTP via SMS] │
│ │
│ ── or ── │
│ [Continue with Google] │
│ │
│ Step 2 of 7 ────●────○○○○○ │
└─────────────────────────────┘
Form Fields:
| Field | Type | Validation | Error Messages |
|---|---|---|---|
| Country code | Fixed | +91 (India) |
N/A |
| Phone number | Number input | 10 digits, Indian format | "Please enter a valid 10-digit Indian mobile number" / Malayalam: "സാധുവായ 10 അക്ക മൊബൈൽ നമ്പർ നൽകുക" |
| OTP | 6-digit input | 6 digits, expires 5 min | "OTP has expired. Please request a new one." / "തെറ്റായ OTP. വീണ്ടും ശ്രമിക്കുക." |
OTP Flow:
User clicks [Send OTP]
→ System generates 6-digit OTP
→ Primary: Send via WhatsApp Business API (free, reliable)
→ Fallback: Send via SMS (Twilio/Exotel) if WhatsApp not delivered in 30s
→ Auto-detect OTP from message (Android only)
→ Show countdown: "Resend OTP in 00:45"
→ After 3 failed attempts: "Having trouble? Call us" + show helpline
OTP Delivery Mitigation (Critical for India):
- Primary channel: WhatsApp Business API (higher delivery rate than SMS in India)
- Fallback 1: SMS via Exotel/Twilio after 30-second delay
- Fallback 2: Voice call with OTP after 60 seconds
- Auto-read: Use Web OTP API for Android auto-detection
- Retry button: Always visible with countdown, never hidden
- Support escalation: After 3 failed attempts, auto-trigger support callback
Interactions:
- OTP verified → Auto-advance to Screen 3 (no button tap needed)
Continue with Google→ Google OAuth → Skip to Screen 4 (pre-fill email)← Back→ Screen 1
SCREEN 3: Business Information#
Purpose: Collect essential business data for AI content generation
Time estimate: 90 seconds
Drop-off risk: Medium (15%) -- form fatigue sets in
Layout (Mobile) -- Part A (Basic Info):
┌─────────────────────────────┐
│ ← Back │
│ │
│ "Tell Us About Your Clinic"│
│ │
│ "We need this to create │
│ your online presence" │
│ │
│ Your Full Name * │
│ [Dr. │
│ Arun Sharma ]│
│ │
│ Clinic/Hospital Name * │
│ [HeartCare │
│ Cardiology Centre ]│
│ │
│ Medical Speciality * │
│ [ 🔍 Select speciality ▼ ] │
│ - Cardiologist │
│ - Dentist │
│ - Dermatologist │
│ - General Physician │
│ - Orthopedic │
│ - Pediatrician │
│ - Gynecologist │
│ - Other... │
│ │
│ [Continue →] │
│ │
│ Step 3 of 7 ─────●────○○○○ │
└─────────────────────────────┘
Layout (Mobile) -- Part B (Location):
┌─────────────────────────────┐
│ ← Back │
│ │
│ "Where Is Your Clinic?" │
│ │
│ City/Town * │
│ [ 🔍 Kochi, Kerala ] │
│ │
│ [📍 Use Current Location] │
│ "OR" │
│ Complete Address * │
│ [42, MG Road, │
│ Near Lulu Mall, │
│ Kochi, Kerala 682016 ]│
│ │
│ [🗺️ Preview on Map] │
│ │
│ [Continue →] │
│ Step 3 of 7 (2/2) ───●──○○ │
└─────────────────────────────┘
Form Fields (Part A):
| Field | Type | Validation | Notes |
|---|---|---|---|
| Full name | Text | Required, min 3 chars | Pre-fill from Google OAuth if available |
| Clinic name | Text | Required, min 3 chars | This becomes the directory profile title |
| Speciality | Dropdown | Required | 20+ specialities pre-loaded. "Other" triggers text input |
| Years of experience | Number | Optional | Used for trust signals in content |
Form Fields (Part B):
| Field | Type | Validation | Notes |
|---|---|---|---|
| City | Autocomplete | Required | Geocoded to lat/lng. Kerala cities prioritized for Phase 1 |
| Full address | Textarea | Required | Used for NAP consistency across all 30 citations |
| Pincode | Number | 6 digits, Indian | Auto-validated against India Post database |
Smart Defaults:
- Use GPS to suggest current city
- Autocomplete address from Google Places API as user types
- Pincode auto-fills city and state
Interactions:
📍 Use Current Location→ Browser geolocation → Reverse geocode → Fill city, address🗺️ Preview on Map→ Show embedded Google Map with pin at addressContinue→ Screen 4 (GBP Connection)- Progress shows "Step 3 of 7 (2/2)" to indicate sub-steps within this screen
SCREEN 4: Google Business Profile Connection#
Purpose: Grant RankFlow access to manage the doctor's Google Business Profile
Time estimate: 2-3 minutes (includes watching guide + OAuth flow)
Drop-off risk: VERY HIGH (40%) -- this is the #1 drop-off point
Design Principle: DO NOT show the raw Google OAuth screen immediately. Build a guided bridge first.
Layout (Mobile) -- Step 4A: Explanation:
┌─────────────────────────────┐
│ ← Back │
│ │
│ "Connect Your Google │
│ Business Profile" │
│ │
│ [📱 Illustration: │
│ Doctor's clinic showing │
│ on Google Maps with │
│ "Managed by RankFlow" │
│ badge ] │
│ │
│ "This lets us:" │
│ ✅ Update your clinic hours │
│ ✅ Post weekly updates │
│ ✅ Reply to patient reviews│
│ ✅ Add photos and services │
│ │
│ "We CANNOT:" │
│ ❌ Access your emails │
│ ❌ See patient data │
│ ❌ Delete your profile │
│ │
│ "You'll stay in control │
│ -- you can disconnect │
│ anytime" │
│ │
│ [▶ Watch 30-sec Guide] │
│ [I Understand, Connect →] │
│ │
│ "Don't have a Google │
│ Business Profile?" │
│ [Create One First →] │
│ │
│ Step 4 of 7 ──────●───○○○○ │
└─────────────────────────────┘
30-Second Video Guide Script:
[0:00-0:05] "Hi Doctor! Let's connect your Google profile."
[0:05-0:15] "Tap this green button. Sign in with the Google
account that owns your clinic profile."
[0:15-0:25] "Tap 'Allow'. That's it! We take care of the rest."
[0:25-0:30] "Questions? Tap 'Call Support' anytime."
Layout (Mobile) -- Step 4B: OAuth In-Progress:
┌─────────────────────────────┐
│ │
│ "Connecting to Google..." │
│ │
│ [ Animated loader ] │
│ │
│ "A Google sign-in window │
│ will open. Please sign in │
│ with your clinic's Google │
│ account." │
│ │
│ [📞 Having trouble? Call │
│ support - 1800-RANKFLOW] │
│ │
│ [⏳ Waiting for Google... │
│ (tap to retry)] │
└─────────────────────────────┘
GBP OAuth Flow (Behind the Scenes):
User taps "Connect"
→ Open Google OAuth popup (scope: business.manage)
→ User selects Google account
→ User approves permissions
→ Callback receives: access_token, refresh_token, account_id
→ System fetches GBP locations for this account
→ If 1 location: Auto-select, proceed to confirmation
→ If 2+ locations: Show location picker
→ If 0 locations: Show "No GBP found" error path
→ Store tokens encrypted (AES-256)
→ Verify phone number matches our records
Post-Connection Confirmation:
┌─────────────────────────────┐
│ ✓ Connected! │
│ │
│ "HeartCare Cardiology │
│ Centre is now linked" │
│ │
│ [🗺️ Map preview of clinic] │
│ "42, MG Road, Kochi" │
│ "4.2★ (127 reviews)" │
│ │
│ "We found a phone number │
│ on your Google profile: │
│ +91 98765 43210" │
│ [✓ This matches] │
│ [✗ This is different] │
│ │
│ [Continue →] │
└─────────────────────────────┘
Error States:
| Error | UI Message | Recovery Path |
|---|---|---|
| No GBP found | "We couldn't find a Google Business Profile for this account" | "Let's create one" → Redirect to GBP creation guide |
| Multiple locations | "We found multiple clinics. Which one is yours?" | Location picker list |
| Phone mismatch | "The phone on your Google profile (+91 XXXXX) doesn't match what you entered (+91 YYYYY)" | "Update my number" or "This is a different clinic" |
| OAuth denied | "Permission was not granted. Without this, we can't optimize your Google presence." | "Try Again" + "Why do we need this?" explainer + "I'll do this later" (soft deferral) |
| Token expiry during flow | "Connection timed out. Please try again." | Auto-retry once, then manual retry |
Critical: Soft Deferral Option
- Always offer "I'll do this later" -- do NOT block onboarding
- Doctor can complete onboarding and come back to GBP from dashboard
- Deferral triggers: WhatsApp reminder after 2 hours, then daily for 3 days
- Admin alert: "Dr. Sharma skipped GBP connection"
SCREEN 5: Social Media Connection#
Purpose: Connect Instagram and Facebook for auto-posting
Time estimate: 90 seconds
Drop-off risk: High (30%) -- many doctors don't have business accounts
Layout (Mobile):
┌─────────────────────────────┐
│ ← Back │
│ │
│ "Connect Social Media │
│ (Optional)" │
│ │
│ "We'll post health tips │
│ and clinic updates for │
│ you automatically" │
│ │
│ ┌─────────────────────┐ │
│ │ 📸 Instagram │ │
│ │ @[handle or │ │
│ │ 'Not connected'] │ │
│ │ [Connect →] │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │
│ │ 📘 Facebook │ │
│ │ @[handle or │ │
│ │ 'Not connected'] │ │
│ │ [Connect →] │ │
│ └─────────────────────┘ │
│ │
│ [Skip for Now →] │
│ "You can connect these │
│ later from your dashboard"│
│ │
│ Step 5 of 7 ───────●──○○○ │
└─────────────────────────────┘
Instagram Connection Prerequisites (Pre-Checklist): Before showing OAuth, display a checklist:
"Before connecting Instagram, please check:"
☐ You have an Instagram Business Account (not personal)
☐ Your Instagram is linked to a Facebook Page
☐ You're an admin of that Facebook Page
"Not sure? [Watch 1-min guide] or [Skip for now]"
Meta OAuth Flow:
User taps "Connect Instagram"
→ Composio OAuth initiation
→ Redirect to Meta login
→ User logs into Facebook
→ Selects Facebook Page
→ Grants Instagram Basic Display + Content Publishing permissions
→ Composio returns connection_id
→ System stores: connection_id, page_id, ig_account_id, status
→ Show success confirmation
Social Connection States:
| State | Visual | Action |
|---|---|---|
| Not connected | Grey outline | "Connect →" button |
| Connecting | Spinner | Disabled |
| Connected | Green checkmark | "✓ Connected as @handle" |
| Failed | Red warning | "Retry" + error message |
| Expired | Yellow warning | "Reconnect" + reason |
Soft Deferral:
- "Skip for Now" is always available and prominent (not hidden)
- Social is genuinely optional for Starter plan
- Post-onboarding: Weekly reminder in dashboard to connect social
- WhatsApp: "Hi Dr. Sharma! Connecting Instagram can help you reach 40% more patients. Would you like help?"
SCREEN 6: Plan Selection#
Purpose: Show pricing, help doctor choose right plan, collect payment
Time estimate: 60 seconds
Drop-off risk: High (15%) -- price shock or payment friction
Layout (Mobile):
┌─────────────────────────────┐
│ ← Back │
│ │
│ "Choose Your Plan" │
│ │
│ "Start with 7-day free │
│ trial. Cancel anytime." │
│ │
│ ┌───────────────────────┐ │
│ │ 🥉 STARTER │ │
│ │ ₹4,000/month │ │
│ │ │ │
│ │ ✓ 15 citations │ │
│ │ ✓ Basic directory profile │ │
│ │ ✓ GBP posts (2x/mo) │ │
│ │ ✗ Social posting │ │
│ │ ✗ Review replies │ │
│ │ │ │
│ │ [Start Free Trial] │ │
│ └───────────────────────┘ │
│ │
│ ┌───────────────────────┐ │
│ │ 🥈 STANDARD │ │
│ │ ₹8,000/month │ │
│ │ MOST POPULAR ★ │ │
│ │ │ │
│ │ ✓ 30 citations │ │
│ │ ✓ Full directory profile │ │
│ │ ✓ GBP posts (4x/mo) │ │
│ │ ✓ Social posting │ │
│ │ ✓ Review replies │ │
│ │ │ │
│ │ [Start Free Trial] │ │
│ └───────────────────────┘ │
│ │
│ [📞 Need help choosing? │
│ Talk to our team] │
│ │
│ Step 6 of 7 ────────●──○○ │
└─────────────────────────────┘
Plan Comparison Behavior:
- Default to "Standard" plan (anchoring effect)
- "Most Popular" badge on Standard (social proof)
- Swipe horizontally to see all 4 plans
- Each plan card: max 5 features, check/cross for clarity
- Sticky "Compare all features →" link at bottom
Payment Flow:
User selects plan
→ Show trial confirmation: "Your 7-day free trial starts now"
→ Collect payment method for post-trial billing
→ Razorpay checkout (UPI, Card, Net Banking, Wallets)
→ Store payment method token
→ Trial active immediately
→ Next charge: 7 days later (reminder sent 2 days before)
Trial Design:
- No payment required to start (true free trial)
- Payment method collected but NOT charged for 7 days
- Reminder email/WhatsApp at Day 5: "Your trial ends in 2 days"
- Conversion prompt at Day 7: "Your trial ends today. Continue for ₹X/month?"
- If no response: Auto-downgrade to "Paused" (not deleted -- data retained 30 days)
SCREEN 7: Completion / Done!#
Purpose: Celebrate completion, set expectations, drive to first value moment
Time estimate: 30 seconds
Drop-off risk: None (completion!)
Layout (Mobile):
┌─────────────────────────────┐
│ │
│ [🎉 Celebration animation] │
│ │
│ "You're All Set, │
│ Dr. Sharma!" │
│ │
│ "Here's what happens next:"│
│ │
│ ┌───────────────────────┐ │
│ │ ⏱️ In 60 minutes: │ │
│ │ Your directory profile │ │
│ │ goes live │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ 📅 Within 24 hours: │ │
│ │ 15+ citations built │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ 📈 In 30 days: │ │
│ │ Your first ranking │ │
│ │ report │ │
│ └───────────────────────┘ │
│ │
│ [Go to My Dashboard →] │
│ │
│ "We'll WhatsApp you when │
│ your directory profile is live" │
│ │
│ [Add to WhatsApp →] │
│ │
└─────────────────────────────┘
Post-Onboarding Sequence:
T+0 min: WhatsApp "Welcome Dr. Sharma! We're setting up your profile."
T+60 min: WhatsApp "🎉 Your directory profile is live! [Link]"
T+60 min: Email with directory profile link + GBP connection guide (if deferred)
T+24 hours: WhatsApp "15 citations built! View progress in your dashboard."
T+Day 3: WhatsApp "Your first Google post is live. See it here: [Link]"
T+Day 5: WhatsApp trial reminder (if on trial)
T+Day 7: First weekly digest email
T+Day 30: First monthly report
1.4 Onboarding Progress Indicator#
Persistent at bottom of every screen:
Step X of 7 ─────●────○○○○○
- Filled circle = completed
- Current circle = highlighted (green, pulsing)
- Empty circle = upcoming
- Clickable: Can tap any completed step to go back and edit
- Label below: "Step 4: Connect Google" (contextual reminder)
1.5 Resume Onboarding Flow#
If doctor leaves and returns:
1. Doctor clicks onboarding link again (from WhatsApp/email)
2. System detects: phone number already in system, onboarding incomplete
3. Shows: "Welcome back, Dr. Sharma! You were on Step 4"
4. [Resume where I left off] [Start over]
5. If "Resume" → Goes directly to Step 4 (state preserved)
6. All previously entered data pre-filled
Session Persistence:
- Form data saved to localStorage after every field change
- Server-side draft saved on every screen completion
- Draft expires after 7 days of inactivity
- After expiry: WhatsApp nudge → New onboarding link
1.6 Onboarding Drop-off Analysis & Mitigation Summary#
| Step | Est. Drop-off | Root Cause | Mitigation |
|---|---|---|---|
| 1. Welcome | 5% | Not interested | A/B test headlines, add social proof |
| 2. Phone OTP | 10% | OTP delivery fail | WhatsApp primary + SMS fallback + voice fallback |
| 3. Business Info | 15% | Form fatigue | Auto-fill everything possible, GPS location |
| 4. GBP Connect | 40% | Fear, confusion, technical barrier | 30-sec video, explainer, soft deferral, support call |
| 5. Social Connect | 30% | No business account | Pre-checklist, skip option, deferred onboarding |
| 6. Plan/Payment | 15% | Price shock, payment fail | True free trial, UPI support, call-to-complete |
| 7. Done | 0% | -- | -- |
Overall target completion rate: 75% (with mitigations) vs. 35% (without)
2. Client Dashboard UX Specification#
2.1 Information Architecture#
CLIENT DASHBOARD NAVIGATION
┌─────────────────────────────────────────────────────────┐
│ [☰] RankFlow 🔔 💬 👤 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Google Maps │ │ Citations │ │ Reviews │ │
│ │ Position │ │ Built │ │ Score │ │
│ │ #3 ↑2 │ │ 28/30 │ │ 4.2 ★ │ │
│ │ +2 this mo │ │ +5 this mo │ │ +3 new │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 📈 RANKING TREND (Last 30 Days) │ │
│ │ [Sparkline chart showing position over time] │ │
│ │ │ │
│ │ 1 ─┐ │ │
│ │ 3 ─┼──●──●──●──●──●──●──●──●──●──● │ │
│ │ 5 ─┘ ● ● ● ● ● ● ● ● ● ● │ │
│ │ Day 1 10 20 30 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 📋 RECENT ACTIVITY │ │
│ │ ✅ Directory profile published (2 days ago) │ │
│ │ ✅ 3 new citations built (yesterday) │ │
│ │ ✅ Google post published "Heart Health Tips" │ │
│ │ ✅ 2 review replies sent │ │
│ └─────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────┤
│ 🏠 📊 📍 💬 ⚙️ │
│ Home Stats GBP Social More │
└─────────────────────────────────────────────────────────┘
2.2 Mobile-First Design Principles#
Viewport Target: 375px - 428px width (iPhone SE through iPhone 14 Pro Max)
| Principle | Implementation |
|---|---|
| Thumb zone optimization | Primary actions (CTAs, call support) in bottom 25% of screen |
| Tap targets ≥ 48×48dp | All buttons, links, form fields |
| Single-column layout | No side-by-side cards on mobile |
| Scroll, don't navigate | Dashboard home is scrollable; minimize page transitions |
| Sticky bottom nav | 5-tab navigation always accessible |
| Pull-to-refresh | All data screens support pull-to-refresh |
| Offline indicators | Grey banner: "You're offline. Some data may be outdated." |
| Font size ≥ 16px inputs | Prevents iOS zoom on form fields |
| Reduce motion support | Respect prefers-reduced-motion for animations |
Breakpoints:
- Mobile: < 768px (primary target)
- Tablet: 768px - 1024px (2-column grid)
- Desktop: > 1024px (admin-style layout, 3-column grid)
2.3 Dashboard Pages#
PAGE 1: Home (Dashboard Overview)#
Purpose: At-a-glance summary of everything happening
Frequency: Doctor opens this 80% of the time
Content Sections (top to bottom):
-
Header Bar
- Clinic name + greeting: "Good morning, Dr. Sharma"
- Language toggle:
[EN ▼]→ Dropdown: English / Malayalam / Tamil / Hindi - Notification bell (red dot if unread > 0)
- Profile avatar (tap → settings)
-
Three KPI Cards (horizontal swipe on mobile)
- Google Maps Position: Current rank (#3), change (↑2), sparkline
- Citations Built: Count (28/30), change (+5 this month), progress ring
- Review Score: Star rating (4.2★), review count (127), change (+3 new)
-
Ranking Trend Chart
- 30-day sparkline
- Y-axis inverted (position 1 at top)
- Annotation dots for key events ("Directory profile went live")
- Tappable: Opens full /stats page
-
Recent Activity Feed
- Chronological list of last 10 actions
- Each item: icon + description + timestamp + "View →" link
- Grouped by day
-
This Month's Summary
- "So far this month, RankFlow has:"
- ✅ Posted X updates to Google
- ✅ Built X citations
- ✅ Replied to X reviews
- ✅ Published X social posts
- "Your next report arrives [Date]"
-
Quick Actions Row
- [📞 Call Support] [💬 WhatsApp] [📄 View Report]
-
Bottom Navigation
- 🏠 Home | 📊 Stats | 📍 GBP | 💬 Social | ⚙️ More
Loading State:
┌─────────────────────────────┐
│ [Skeleton shimmer] │
│ ░░░░░░░░ ░░░░░░░░ ░░░░░░░ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░ │
└─────────────────────────────┘
PAGE 2: Stats (Detailed Analytics)#
Purpose: Deeper data for doctors who want to understand trends
Sections:
- Time Period Selector:
[7 days] [30 days] [90 days] [All time] - Google Maps Position Chart: Full-sized line chart with competitor comparison
- Citation Growth Chart: Bar chart of citations added over time
- Review Breakdown: Pie chart (5★, 4★, 3★, 2★, 1★) + trend
- Social Reach: Posts published, estimated impressions (if available)
- Keyword Performance: Which search terms you're ranking for
- Comparison: "You're #3 for 'cardiologist in Kochi'. #1 is [Competitor Name]"
Empty State:
"Not enough data yet. Check back after 2 weeks!"
[Animated illustration of seed growing into tree]
PAGE 3: GBP Management#
Purpose: Google Business Profile overview and recent activity
Sections:
-
GBP Status Card:
- Profile name, address, phone
- Connection status (green dot = healthy)
- "Last synced: 2 hours ago"
- [View on Google Maps →] (external link)
-
Recent Posts:
- List of last 5 GBP posts
- Each: thumbnail + title + date + status (published/scheduled)
- Tap → Full post view
-
Reviews Inbox:
- New reviews requiring attention (red dot if > 0)
- Each: reviewer name, stars, text, AI-generated reply preview
- [✓ Approve] [✗ Edit] buttons
- "Auto-reply is ON. All positive reviews get instant replies."
-
Q&A Section:
- Questions from Google Maps users
- AI-suggested answers
- [Approve] [Edit] buttons
-
Photos:
- Grid of recently uploaded photos
- [Upload New Photo] button
PAGE 4: Social Media#
Purpose: Social account status and post history
Sections:
-
Connected Accounts:
- Instagram: @handle, status, [Disconnect]
- Facebook: Page name, status, [Disconnect]
- [+ Connect Another Account]
-
Upcoming Posts:
- Calendar-style view
- Tap a date → See scheduled posts
- [Approve All] [Pause All] buttons
-
Recent Posts:
- Grid of published posts
- Each: thumbnail + platform icon + engagement (if available)
-
Post Approval Toggle:
- "Do you want to approve every post before it goes live?"
- Toggle: ON/OFF
- When ON: All posts show in "Pending Approval" 24h before publish
PAGE 5: More (Settings & Navigation)#
Menu Items:
┌─────────────────────────────┐
│ 👤 My Profile │
│ ───────────────────────── │
│ 📄 Monthly Reports │
│ 🌐 My Directory Profile │
│ 📍 My Citations │
│ ───────────────────────── │
│ 💳 Billing & Plan │
│ 🔔 Notification Settings │
│ 🌐 Language / भाषा │
│ ───────────────────────── │
│ ❓ Help & Support │
│ 📞 Call Support │
│ 💬 WhatsApp Support │
│ ───────────────────────── │
│ 🚪 Log Out │
└─────────────────────────────┘
2.4 Language Toggle#
Location: Sticky top-right on all dashboard pages
Supported Languages (Phase 1):
| Language | Code | Coverage |
|---|---|---|
| English (default) | en |
All UI, all content |
| Malayalam | ml |
All UI labels, key messages |
| Hindi | hi |
All UI labels |
| Tamil | ta |
All UI labels |
Behavior:
- Toggle instantly switches all UI labels (client-side i18n)
- AI-generated content remains in English (content language is separate from UI language)
- Malayalam UI labels use simple, non-technical language
- Content in Malayalam: Can be requested via support (manual process in Phase 1)
Malayalam Key Translations:
| English | Malayalam (UI) |
|---|---|
| Dashboard | ഡാഷ്ബോർഡ് |
| Google Maps Position | ഗൂഗിൾ മാപ്സ് സ്ഥാനം |
| Citations | ഉദ്ധരണികൾ |
| Reviews | അവലോകനങ്ങൾ |
| Call Support | സപ്പോർട്ട് വിളിക്ക് |
| Your Clinic | നിങ്ങളുടെ ക്ലിനിക് |
| View Report | റിപ്പോർട്ട് കാണുക |
2.5 "Call Support" Button Placement#
The "Call Support" button must be omnipresent but non-intrusive.
| Location | Style | Behavior |
|---|---|---|
| Dashboard header | Phone icon (📞) in top-right | Taps → Dials 1800-RANKFLOW |
| Sticky FAB (bottom-right, above nav) | Floating pill: "📞 Help" | Always visible on all pages. Taps → Options: Call / WhatsApp / FAQ |
| Error states | Prominent button: "Need help? Call us" | Appears whenever an error occurs |
| Onboarding screens | Full-width button below primary CTA | Visible but secondary |
| Report viewing | "Questions about your report? 📞 Call" | Below every report |
FAB Behavior:
Tap FAB → Bottom sheet slides up:
📞 Call Support (1800-RANKFLOW)
💬 WhatsApp Support
📧 Email Support
❓ View FAQs
✕ Close
Support Hours: Displayed prominently: "Available 9 AM - 9 PM IST, 7 days"
2.6 Report Viewing Experience#
Monthly Report Screen#
┌─────────────────────────────┐
│ ← Back June 2026 Report │
│ │
│ [📄 PDF Preview Thumbnail] │
│ [Tap to download full PDF] │
│ │
│ ┌───────────────────────┐ │
│ │ THIS MONTH'S WINS │ │
│ │ │ │
│ │ 🏆 Google Maps: #3 │ │
│ │ (up from #7) │ │
│ │ │ │
│ │ 📊 28 citations live │ │
│ │ (+5 new) │ │
│ │ │ │
│ │ ⭐ 127 reviews, 4.2★ │ │
│ │ (+12 new, all │ │
│ │ replied) │ │
│ │ │ │
│ │ 📱 8 social posts │ │
│ │ published │ │
│ └───────────────────────┘ │
│ │
│ [📥 Download PDF] │
│ [📤 Share on WhatsApp] │
│ [📧 Email to Myself] │
│ │
│ "Your next report: July 1" │
│ │
│ 📞 "Questions? Call us" │
└─────────────────────────────┘
PDF Report Design:
- Page 1: Cover page with clinic name, logo, month, RankFlow branding
- Page 2: Executive summary with 4 KPI cards
- Page 3: Google Maps position chart (30-day trend)
- Page 4: Citation inventory (all 30 URLs with status)
- Page 5: Review summary (new reviews, replies sent)
- Page 6: Social posts summary (what was published where)
- Page 7: What's coming next month (upcoming actions)
- Branding: Clean, medical-professional aesthetic. Green/gold color scheme.
- Language: English (primary) + Malayalam summary for Kerala clients
Chart Specifications:
- Use Chart.js or Recharts (SVG-based, responsive)
- All charts must render as SVG in PDF (server-side rendering)
- Color palette: Primary green (#1b4332), accent gold (#f0a500), neutral grey (#888)
- Sparklines: No axes, just the line + current value annotation
- Full charts: Clean axes, gridlines at 20% opacity, data point tooltips
2.7 WhatsApp-Style Notification Preferences#
Doctors configure notifications through a familiar WhatsApp-style toggle interface:
┌─────────────────────────────┐
│ 🔔 Notification Settings │
│ │
│ WHATSAPP NOTIFICATIONS │
│ ┌───────────────────────┐ │
│ │ Ranking changes │ │
│ │ [─────────●───] ON │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ New reviews │ │
│ │ [─────────●───] ON │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ Weekly summary │ │
│ │ [──────────●──] ON │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ Post approvals needed │ │
│ │ [─────────●───] ON │ │
│ └───────────────────────┘ │
│ │
│ EMAIL NOTIFICATIONS │
│ ┌───────────────────────┐ │
│ │ Monthly report │ │
│ │ [─────────●───] ON │ │
│ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │ Billing alerts │ │
│ │ [────●────────] OFF │ │
│ └───────────────────────┘ │
│ │
│ FREQUENCY │
│ [Immediately] [Daily Digest]│
│ [Weekly Only] │
│ │
└─────────────────────────────┘
3. Admin Dashboard UX Specification#
3.1 Information Architecture#
ADMIN NAVIGATION (Desktop-first, sidebar layout)
┌──────────┬────────────────────────────────────────────────────────────┐
│ │ 🔍 Search clients... 🔔 👤 Admin │
│ RankFlow ├────────────────────────────────────────────────────────────┤
│ │ │
│ 📊 KPIs │ TOTAL CLIENTS MRR CHURN ACTIVE JOBS │
│ │ 87 ₹6.96L 3% 12 running │
│ 👥 │ │
│ Clients │ ┌─────────────────────────────────────────────────────┐ │
│ │ │ CLIENT MANAGEMENT TABLE │ │
│ 🌐 │ │ │ │
│ Domains │ │ [🔍 Search] [Filter ▼] [Export] [+ Add Client] │ │
│ │ │ │ │
│ 📝 │ │ Name Plan Status GBP Cit. Since ▼ │ │
│ Content │ │ ───────────────────────────────────────────────── │ │
│ │ │ Dr. Sharma Std Active ✓ 28/30 Mar 26 │ │
│ 🔗 │ │ Dr. Kumar Prem Active ✓ 30/30 Jan 26 │ │
│ Social │ │ Dr. Nair Str Warning ⚠ 15/30 Feb 26 │ │
│ │ │ Dr. Mathew Ent Paused ✗ 0/30 Dec 25 │ │
│ 📍 │ │ ... (50 more rows) │ │
│ Citations│ │ │ │
│ │ │ Showing 1-25 of 87 [< 1 2 3 ... 4 >] │ │
│ ⚙️ Jobs │ └─────────────────────────────────────────────────────┘ │
│ │ │
│ 💳 │ ┌─────────────────────────────────────────────────────┐ │
│ Billing │ │ RECENT ALERTS │ │
│ │ │ 🔴 GBP token expired: Dr. Nair (2h ago) │ │
│ ⚙️ │ │ 🟡 3 citation failures pending retry │ │
│ Settings │ │ 🟢 5 new reviews auto-replied │ │
│ │ │ 🔴 Payment failed: Dr. Mathew (₹12K) │ │
│ │ └─────────────────────────────────────────────────────┘ │
│ │ │
└──────────┴────────────────────────────────────────────────────────────┘
3.2 Client Management Table#
Route: /admin/clients
Columns:
| Column | Content | Sortable | Filterable |
|---|---|---|---|
| Client Name | Name + clinic name + avatar | Yes | Yes |
| Plan | Badge: Starter/Standard/Premium/Enterprise | Yes | Yes (multi-select) |
| Status | Badge: Active / Trial / Paused / Cancelled / Warning | Yes | Yes |
| GBP | Dot: Green (healthy), Yellow (warning), Red (disconnected), Grey (not connected) | No | Yes |
| Citations | "28/30" with progress bar | Yes | No |
| Social | Icons for IG + FB, each with status dot | No | Yes |
| MRR | ₹X,XXX | Yes | Yes (range) |
| Since | Onboarding date | Yes | Yes (date range) |
| Last Activity | Time ago | Yes | No |
| Actions | [View] [Edit] [⚙️] dropdown | No | No |
Filters Panel (collapsible):
- Status: Multi-checkbox (Active, Trial, Paused, Cancelled, Warning)
- Plan: Multi-checkbox (all 4 tiers)
- GBP status: Dropdown (All, Connected, Disconnected, Error)
- Citation progress: Slider (0% - 100%)
- Date range: Date picker (onboarding date)
- City: Multi-select (auto-populated from client data)
Bulk Actions:
Select all / Select page → Bulk actions appear:
[📧 Send Message] [📄 Generate Reports] [🔄 Retry Citations]
[⏸️ Pause Accounts] [▶️ Resume Accounts] [📥 Export CSV]
Client Detail Drawer (on click): Slide-out panel from right:
┌─────────────────────────────────┐
│ Dr. Arun Sharma [✕ Close] │
│ HeartCare Cardiology Centre │
│ ───────────────────────────── │
│ Plan: Standard (₹8K/mo) │
│ Status: Active │
│ Since: Mar 15, 2026 │
│ Phone: +91 98765 43210 │
│ ───────────────────────────── │
│ [📊 View Full Profile →] │
│ [📞 Call Client] │
│ [💬 WhatsApp Client] │
│ ───────────────────────────── │
│ QUICK STATS │
│ GBP: ✓ Connected (synced 2h) │
│ Citations: 28/30 (93%) │
│ Reviews: 127 total, 4.2★ │
│ Social: IG ✓, FB ✗ │
│ ───────────────────────────── │
│ RECENT ACTIVITY │
│ 2h ago: GBP post published │
│ 1d ago: 3 citations built │
│ 3d ago: Review reply sent │
│ ───────────────────────────── │
│ [Edit Client] [Change Plan] │
│ [⚠️ Flag Issue] [🚫 Cancel] │
└─────────────────────────────────┘
3.3 Citation Health Monitoring Dashboard#
Route: /admin/citations
Purpose: Real-time view of all citation submissions across all clients
Layout:
┌────────────────────────────────────────────────────────────┐
│ CITATION HEALTH [🔄 Refresh] │
├────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 2,440 LIVE │ │ 120 PENDING│ │ 86 FAILED │ │
│ │ (94%) │ │ (5%) │ │ (3%) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ CITATION SUCCESS RATE BY SITE (Bar Chart) │ │
│ │ │ │
│ │ Justdial ████████████████████████████ 98% │ │
│ │ Practo ██████████████████████████ 95% │ │
│ │ Sulekha ████████████████████████ 92% │ │
│ │ Yelp ████████████████ 78% │ │
│ │ Hotfrog ██████████████ 72% │ │
│ │ [etc...] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ RECENT FAILURES (Auto-refresh every 5 min) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Time Client Site Error Action │ │
│ │ 10:23 Dr. Nair Yelp Timeout [Retry] │ │
│ │ 10:15 Dr. Kumar Hotfrog CAPTCHA [Fix →] │ │
│ │ 09:48 Dr. Sharma Justdial 500 [Retry] │ │
│ │ 09:30 Dr. Mathew Practo Auth [Check] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────┘
Failure Analysis: Click any failure → Expand detail:
Client: Dr. Nair
Site: Yelp (yelp.com)
Error: Request timeout after 30s
Failed: 3 times (last: 10:23 AM)
Stack trace: [view]
Suggested fix: Increase timeout for Yelp submissions
[Retry Now] [Edit & Retry] [Mark as Unfixable] [Snooze 24h]
Auto-Retry Policy:
| Failure Type | Retry Count | Backoff | Escalation |
|---|---|---|---|
| Timeout | 3 | 5min, 15min, 1hr | Alert admin after 3rd |
| 5xx Server Error | 3 | 5min, 15min, 1hr | Alert admin after 3rd |
| 4xx Client Error | 1 | None | Alert admin immediately |
| CAPTCHA | 2 | 1hr, 6hr | Queue for manual + 2captcha |
| Auth Failure | 1 | None | Alert admin + mark token expired |
| Rate Limited | 5 | 1hr × attempt | Auto-backoff |
3.4 Content Approval Workflow#
Route: /admin/content
Purpose: Review and approve AI-generated content before it goes live
Layout:
┌────────────────────────────────────────────────────────────┐
│ CONTENT APPROVAL QUEUE [🔍 Search] [Filter ▼] │
├────────────────────────────────────────────────────────────┤
│ │
│ TABS: [All (45)] [Pending (12)] [Approved (28)] │
│ [Rejected (3)] [Auto-approved (2)] │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Type: GBP Post │ │
│ │ Client: Dr. Sharma │ │
│ │ Scheduled: Mar 20, 9:00 AM │ │
│ │ │ │
│ │ Content: │ │
│ │ "🫀 5 Early Signs of Heart Disease You Shouldn't │ │
│ │ Ignore -- Read our latest blog post to learn more │ │
│ │ about prevention. #HeartHealth #Kochi #Cardiologist"│ │
│ │ │ │
│ │ AI Confidence: 87% │ │
│ │ Medical Fact-Check: ✓ Verified (no claims) │ │
│ │ │ │
│ │ [✓ Approve] [✗ Reject] [✏️ Edit] [📅 Reschedule] │ │
│ │ │ │
│ │ ── Auto-publish in: 18 hours ── │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Type: Review Reply │ │
│ │ Client: Dr. Kumar │ │
│ │ Review: 2★ -- "Waited 2 hours, doctor didn't come" │ │
│ │ │ │
│ │ AI Suggested Reply: │ │
│ │ "We're deeply sorry for the wait. We take patient │ │
│ │ time seriously. Please call us at +91 XXXXX so we │ │
│ │ can make this right." │ │
│ │ │ │
│ │ ⚠️ SENTIMENT: NEGATIVE -- Requires manual approval │ │
│ │ │ │
│ │ [✓ Approve] [✗ Reject] [✏️ Edit] [📞 Call Client] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────┘
Content Types in Queue:
| Type | Auto-approve? | Human Review Trigger |
|---|---|---|
| GBP Post (general) | Yes, after 24h | Admin can override anytime |
| GBP Post (promotional) | No | Always requires approval |
| Review Reply (4-5★) | Yes | None |
| Review Reply (1-3★) | Never | Always requires approval |
| Social Post | Yes, after 24h | Client toggle can require pre-approval |
| Directory Profile Content | No | Always requires approval (first month) |
| FAQ Update | Yes, after 48h | Admin configurable |
Bulk Actions:
- Select multiple items → [Approve All] [Reject All] [Reschedule All]
- Keyboard shortcuts:
A= Approve,R= Reject,E= Edit,→= Next item
3.5 Job Monitoring Dashboard#
Route: /admin/jobs
Purpose: Real-time visibility into all background job execution
Layout:
┌────────────────────────────────────────────────────────────┐
│ JOB MONITOR [⏸️ Pause All] [▶️ Resume]│
├────────────────────────────────────────────────────────────┤
│ │
│ QUEUE STATUS: │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ RUNNING │ │ QUEUED │ │ FAILED │ │ COMPLETED│ │
│ │ 12 │ │ 48 │ │ 3 │ │ 1,247 │ │
│ │ (4 high) │ │ │ │ │ │ (today) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ RECENT JOBS: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ID Type Client Status Time ▼ │ │
│ │ ─────────────────────────────────────────────────── │ │
│ │ #48291 Citation Dr. Sharma Running 2m ago │ │
│ │ #48290 GBP Post Dr. Kumar Completed 5m ago │ │
│ │ #48289 Social Post Dr. Nair Failed 8m ago │ │
│ │ #48288 Review Poll Dr. Mathew Completed 12m ago │ │
│ │ ... │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Click any job to view logs, retry, or debug] │
│ │
└────────────────────────────────────────────────────────────┘
Job Detail View:
Job #48289: Social Post Publication
Client: Dr. Nair (ID: 45)
Type: Instagram Post
Status: FAILED (permanent)
Created: Mar 18, 10:23 AM
Duration: 32 seconds
PAYLOAD:
caption: "5 Early Signs of Heart Disease..."
media_url: https://cdn.rankflow.in/heart.jpg
scheduled_at: 2026-03-18T10:00:00Z
ERROR:
Instagram Graph API returned 400:
"The media object is not owned by this business"
SUGGESTED FIX:
The Instagram account may have been disconnected.
Re-authenticate the Instagram connection for Dr. Nair.
[Retry Job] [Edit & Retry] [Re-authenticate IG] [Mark Resolved]
LOGS:
10:23:00 Job started
10:23:05 Fetched connection credentials
10:23:10 Uploaded media to Instagram
10:23:32 ERROR: 400 - media ownership mismatch
10:23:32 Job failed, moved to dead letter queue
3.6 Directory Profile Management#
Route: /admin/directory
Columns:
| Column | Content |
|---|---|
| Client | Name + link to profile |
| Directory URL | directory.com/clinics/kochi/dr-sharma-cardiology |
| Profile Status | Published / Draft / Paused / Archived |
| Last Updated | Timestamp |
| Profile Views | Views this month |
| Actions | [Edit] [Preview] [Publish] [Unpublish] |
Profile Status Flow:
Admin publishes profile
→ System sets status to PUBLISHED
→ Trigger ISR revalidation for the route
→ Update XML sitemap
→ Sync GBP websiteUri to directory profile URL
→ Status: "Live" (green)
Admin unpublishes profile (client cancellation)
→ System sets status to ARCHIVED
→ Trigger ISR revalidation (page returns 404)
→ Remove from sitemap
→ Status: "Removed" (grey)
3.7 Social Connection Status Overview#
Route: /admin/social-connections
Table:
| Client | GBP | Last Sync | ||
|---|---|---|---|---|
| Dr. Sharma | @heartcarekochi (green) | HeartCare (green) | Connected (green) | 2h ago |
| Dr. Kumar | @drrajesh (yellow-expires 3d) | — | Connected (green) | 1d ago |
| Dr. Nair | Not connected (grey) | — | Error (red) | — |
Expiry Warnings:
- Yellow: Token expires in < 7 days
- Red: Token expired or connection error
- Auto-refresh runs daily for all tokens
- Failed refresh → Immediate alert + WhatsApp to client
3.8 Alert System#
Alert Triggers:
| Severity | Trigger | Destination | Action Required |
|---|---|---|---|
| 🔴 Critical | GBP token expired (client) | Admin dashboard + Slack + Email | Re-authenticate within 24h |
| 🔴 Critical | Payment failed (3rd attempt) | Admin dashboard + Email | Contact client for new payment method |
| 🔴 Critical | Directory profile down > 30 min | Admin dashboard + Slack + PagerDuty | Investigate immediately |
| 🟡 Warning | Citation success rate < 80% | Admin dashboard | Investigate site-specific issues |
| 🟡 Warning | Client inactive > 14 days | Admin dashboard | Outreach to re-engage |
| 🟡 Warning | Social token expires < 3 days | Admin dashboard + Email to client | Re-authenticate |
| 🟢 Info | New client onboarded | Admin dashboard | None (auto) |
| 🟢 Info | Monthly report sent | Admin dashboard | None (auto) |
| 🟢 Info | Content approved/published | Admin dashboard | None (auto) |
Alert Delivery Channels:
- In-app notification center (bell icon) -- all alerts
- Slack webhook -- Critical + Warning only
- Email -- Critical + Warning + Daily digest
- WhatsApp -- Critical only (to admin ops number)
Alert Aggregation:
- Critical alerts: Immediate, individual
- Warning alerts: Batched into hourly digest
- Info alerts: Batched into daily summary
4. Feature Flags & Plan Tiers#
4.1 Plan Overview#
| Feature | Starter ₹4K | Standard ₹8K | Premium ₹12K | Enterprise ₹20K |
|---|---|---|---|---|
| Target | Single doctor | Growing clinic | Multi-doctor clinic | Hospital chain |
| Citation Count | 15 sites | 30 sites | 30 sites + priority | 30 sites + custom + Practo API |
| Directory Profile | Basic listing | Full directory profile | Premium listing + related clinics | Custom design + dev support |
| GBP Posts | 2/month | 4/month | 8/month + photos | Unlimited + video |
| Social Posting | None | IG + FB (4/month) | IG + FB (8/month) | All platforms + stories |
| Review Replies | Manual only | Auto (positive only) | Auto (all) + sentiment | Auto (all) + custom templates |
| Support | WhatsApp (24h) | WhatsApp + Call (12h) | Dedicated WhatsApp + 4h | Dedicated account manager |
| Reports | Monthly email | Monthly + weekly | Monthly + weekly + real-time | Custom reports + API access |
| Vernacular | English only | English + Malayalam | All 4 languages | All + custom translations |
| Content Approval | Post-publish | 24h pre-approval | 48h pre-approval | Custom workflow |
| Sub-accounts | 1 | 1 | 3 | Unlimited |
| Custom Keywords | 3 | 5 | 10 | Unlimited |
4.2 Feature Flag Matrix#
Feature Flags (stored in database, cached in Redis)
CLIENT-SIDE FLAGS (per client):
┌──────────────────────────────┬─────────┬──────────┬─────────┬─────────────┐
│ Flag │ Starter │ Standard │ Premium │ Enterprise │
├──────────────────────────────┼─────────┼──────────┼─────────┼─────────────┤
│ directory_profile.basic │ ✓ │ ✓ │ ✓ │ ✓ │
│ directory_profile.premium_layout │ ✗ │ ✗ │ ✓ │ ✓ │
│ directory_profile.related_clinics │ ✗ │ ✗ │ ✓ │ ✓ │
│ directory_profile.city_page │ ✗ │ ✓ │ ✓ │ ✓ │
│ directory_profile.specialty_page │ ✗ │ ✗ │ ✓ │ ✓ │
│ citations.count │ 15 │ 30 │ 30 │ 30+ │
│ citations.priority_sites │ ✗ │ ✗ │ ✓ │ ✓ │
│ citations.indian_directories │ ✗ │ ✓ │ ✓ │ ✓ │
│ gbp.posts_per_month │ 2 │ 4 │ 8 │ unlimited │
│ gbp.photo_posts │ ✗ │ ✗ │ ✓ │ ✓ │
│ gbp.video_posts │ ✗ │ ✗ │ ✗ │ ✓ │
│ gbp.qa_management │ ✗ │ ✓ │ ✓ │ ✓ │
│ social.instagram │ ✗ │ ✓ │ ✓ │ ✓ │
│ social.facebook │ ✗ │ ✓ │ ✓ │ ✓ │
│ social.posts_per_month │ 0 │ 4 │ 8 │ unlimited │
│ review.auto_reply_positive │ ✗ │ ✓ │ ✓ │ ✓ │
│ review.auto_reply_negative │ ✗ │ ✗ │ ✓ │ ✓ │
│ review.custom_templates │ ✗ │ ✗ │ ✗ │ ✓ │
│ report.monthly_email │ ✓ │ ✓ │ ✓ │ ✓ │
│ report.weekly_email │ ✗ │ ✓ │ ✓ │ ✓ │
│ report.real_time_dashboard │ ✗ │ ✗ │ ✓ │ ✓ │
│ report.custom │ ✗ │ ✗ │ ✗ │ ✓ │
│ language.malayalam │ ✗ │ ✓ │ ✓ │ ✓ │
│ language.hindi │ ✗ │ ✗ │ ✓ │ ✓ │
│ language.tamil │ ✗ │ ✗ │ ✓ │ ✓ │
│ support.whatsapp_24h │ ✓ │ ✓ │ ✓ │ ✓ │
│ support.call_12h │ ✗ │ ✓ │ ✓ │ ✓ │
│ support.dedicated_4h │ ✗ │ ✗ │ ✓ │ ✓ │
│ support.account_manager │ ✗ │ ✗ │ ✗ │ ✓ │
│ subaccounts.count │ 1 │ 1 │ 3 │ unlimited │
│ keywords.custom_count │ 3 │ 5 │ 10 │ unlimited │
│ content.pre_approval_hours │ 0 │ 24 │ 48 │ custom │
│ api_access │ ✗ │ ✗ │ ✗ │ ✓ │
└──────────────────────────────┴─────────┴──────────┴─────────┴─────────────┘
4.3 Feature Flag Implementation#
Database Schema:
-- Feature flags defined per plan
CREATE TABLE plan_features (
plan_type VARCHAR(20) PRIMARY KEY, -- STARTER, STANDARD, PREMIUM, ENTERPRISE
features JSONB NOT NULL, -- All flags as JSON
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Per-client feature overrides (for custom plans, promos, etc.)
CREATE TABLE client_feature_overrides (
id SERIAL PRIMARY KEY,
client_id INTEGER REFERENCES clients(id),
feature_key VARCHAR(100) NOT NULL,
feature_value JSONB NOT NULL,
reason TEXT, -- Why override (audit trail)
set_by INTEGER REFERENCES users(id), -- Admin who set it
expires_at TIMESTAMP, -- Optional expiry
created_at TIMESTAMP DEFAULT NOW()
);
Flag Evaluation Logic:
// Pseudocode for feature access check
function canAccessFeature(clientId: string, feature: string): boolean {
// 1. Check client-specific override
const override = getClientOverride(clientId, feature);
if (override) return override.value;
// 2. Check plan-level feature
const client = getClient(clientId);
const planFeatures = PLAN_FEATURES[client.plan];
return planFeatures[feature] === true || planFeatures[feature] > 0;
}
// Usage example
if (canAccessFeature(client.id, 'social.instagram')) {
showInstagramConnectButton();
} else {
showUpgradePrompt('social.instagram');
}
Upgrade Prompts (gated features): When a Starter client tries to access a Standard+ feature:
┌─────────────────────────────┐
│ 🔒 Upgrade Required │
│ │
│ "Social media posting is │
│ available on Standard │
│ plan and above" │
│ │
│ Current: Starter (₹4K/mo) │
│ Upgrade: Standard (₹8K/mo) │
│ │
│ [📊 See Comparison →] │
│ [Upgrade Now →] │
│ [Maybe Later] │
└─────────────────────────────┘
5. Friction Mitigation Strategies#
5.1 Onboarding Friction#
FRICTION 1: "Doctor doesn't understand 'GBP access grant'"#
Root Cause: Doctors don't know what "Google Business Profile" is, let alone "grant access." They fear losing control of their Google account.
UI/UX Solutions:
-
Reframe the language:
- Don't say: "Grant GBP OAuth access"
- Do say: "Let us update your Google Maps listing for you"
-
30-Second Video Guide (embedded in product):
- Vertical video (9:16) optimized for mobile
- Step-by-step screen recording with Malayalam voiceover
- Each tap highlighted with a red circle
- Pause points: "Tap here", "Sign in with this account", "Tap Allow"
-
Visual Step-by-Step Screenshots:
Step 1: Tap the green button below [Screenshot of the button they'll see] Step 2: Sign in with your Gmail [Screenshot of Google sign-in with annotation] Step 3: Tap "Allow" [Screenshot of consent screen with "Allow" circled] Step 4: Done! You'll see a checkmark [Screenshot of success] -
One-Click Support:
- "Stuck? Tap here -- our team will call you in 10 minutes"
- Pre-filled support request: "Dr. Sharma needs help with Google connection"
-
Trust Indicators:
- "We cannot see your emails or personal data"
- "You can disconnect anytime from your dashboard"
- "This is the same login you use for Gmail"
- Show padlock icon + "SSL Secured" + "Verified by Google"
-
Alternative Path (if they refuse):
- "No problem! We'll send you a simple guide via WhatsApp"
- Support agent can do screen-share call (Google Meet/Zoom)
- Salesperson can visit clinic and do it on their phone (white-glove)
FRICTION 2: "Doctor doesn't have Meta Business Account for Instagram"#
Root Cause: Most doctors have a personal Instagram. Converting to Business + linking to Facebook Page is a multi-step process that happens OUTSIDE our product.
UI/UX Solutions:
-
Pre-Checklist Before OAuth:
"Before connecting Instagram, please check:" ☐ My Instagram is a Business Account (not personal) [How to check?] [How to convert?] ☐ My Instagram is linked to a Facebook Page [How to link?] ☐ I'm an admin of that Facebook Page [How to check?] [I'm Ready → Connect] [Not Sure -- Skip for Now →] -
Embedded Mini-Tutorials: Each "How to" link opens an in-app bottom sheet:
"How to Convert to Business Account" [Vertical video, 45 seconds] Step 1: Open Instagram app Step 2: Go to Settings → Account Step 3: Tap "Switch to Professional Account" Step 4: Select "Business" Step 5: Choose your category (Doctor/Health) Done! Come back here and tap Connect. -
WhatsApp Guide Delivery:
- "We'll send the step-by-step guide to your WhatsApp"
- Automated message with screenshots and links
- "Reply DONE when you've completed the steps"
-
Deferred Connection (Default):
- Make social connection genuinely optional in onboarding
- Post-onboarding: "Hi Dr. Sharma! Your Google profile is doing great. Want to add Instagram next? It takes 2 minutes."
- Week 2 check-in: "Many of your patients find doctors on Instagram. Would you like us to set it up?"
-
Support-Assisted Connection:
- "Need help? Book a 10-min call -- we'll walk you through it"
- Calendly integration for scheduling
- Support agent does it via screen share
FRICTION 3: "Doctor's phone number on GBP doesn't match what they entered"#
Root Cause: The clinic may have multiple phone numbers (reception, personal, assistant). The GBP profile may have an old or different number.
UI/UX Solutions:
-
Detection & Display: After GBP connection, automatically show:
"We found a phone number on your Google profile: 📞 +91 98471 22334 You entered: 📞 +91 98765 43210 [✓ This is the same clinic -- update Google] [✗ This is a different number -- keep both] [? I'm not sure -- call me] -
Automatic Sync Options:
- "Update Google to match my number" -- Push new number to GBP
- "Keep both -- this is reception" -- Store both, use primary for NAP
- "Let me check" -- Pause, send WhatsApp reminder in 2 hours
-
NAP Consistency Warning: If numbers don't match, show persistent (but gentle) warning:
⚠️ Phone number mismatch detected "Having different numbers on Google and our system can hurt your rankings. Let's fix this." [Fix Now] [Remind Me Later] -
Admin Override:
- Admin can see all mismatches in a dedicated view
- Bulk action: "Update all GBP phone numbers to match client records"
- One-click fix for common issues
FRICTION 4: "OTP delivery issues"#
Root Cause: Indian telecom infrastructure is unreliable. SMS delivery rates vary by carrier, region, and time of day.
UI/UX Solutions:
-
Multi-Channel OTP (cascade):
Attempt 1: WhatsApp Business API (primary -- free, high delivery) Attempt 2 (after 30s): SMS via Exotel/Twilio Attempt 3 (after 60s): Voice call with spoken OTP -
Visual Feedback:
"Sending OTP..." → "OTP sent via WhatsApp ✓" → (if delayed) "Also sending via SMS..." → (if still delayed) "You'll receive a voice call with your OTP" -
Smart Retry:
- Show countdown: "Resend OTP in 00:45"
- After countdown: [Resend via WhatsApp] [Resend via SMS] [Call me instead]
- Track which channel works per user (preference learning)
-
Failure Escalation:
- After 3 failed attempts: Show "Having trouble?" section
- [📞 Call me instead] → Automated call with OTP
- [💬 WhatsApp me] → Human support reaches out
- [⏭️ Skip for now] → Allow onboarding to continue with email verification as fallback
-
Admin Alert:
- If OTP failure rate > 10% in 1 hour → Auto-alert ops team
- Check: Is Twilio down? Is WhatsApp API having issues?
- Switch primary provider dynamically
5.2 Ongoing Friction#
FRICTION 5: "Doctor wants to approve every social post before it goes live"#
Root Cause: Medical professionals are risk-averse. They fear inappropriate content could damage their reputation or attract regulatory scrutiny.
UI/UX Solutions:
-
Approval Toggle in Dashboard:
"Post Approval Settings" "Do you want to approve posts before they go live?" [──────────●────] YES When enabled: • You'll get a WhatsApp notification 24 hours before publishing • Tap the link to approve or edit • If you don't respond, the post will be auto-approved "Review the post:" [📱 Preview: "5 Early Signs of Heart Disease..."] [✓ Approve This Post] [✓ Approve All Future Posts] [✏️ Edit Post] [✗ Reject -- Don't Post] -
WhatsApp Approval Flow:
WhatsApp message to Dr. Sharma: "👋 Hi Dr. Sharma! We have a post ready for your Instagram: 📝 '5 Early Signs of Heart Disease You Shouldn't Ignore...' Scheduled: Tomorrow, 9:00 AM Reply: ✅ to APPROVE ❌ to REJECT 📝 to EDIT (we'll call you) If no reply, we'll post it tomorrow at 9 AM." -
Content Preview:
- Show exact post as it will appear on each platform
- Platform-specific preview (Instagram square, Facebook rectangle)
- Doctor can see image, caption, hashtags
-
Gradual Trust Building:
- Month 1: All posts require approval (default for new clients)
- Month 2: "You've approved 12 posts. Want to turn on auto-approve for general health tips?"
- Month 3+: Auto-approve by category (health tips = auto, promotions = manual)
-
One-Click Emergency Pause:
- Sticky button: "⏸️ Pause All Posts"
- Confirmation: "All scheduled posts paused. Nothing will go live until you resume."
- Resume just as easy
FRICTION 6: "Doctor gets a negative review and panics"#
Root Cause: A 1-2 star review feels like a personal attack. Doctors worry about reputation damage and may react emotionally.
UI/UX Solutions:
-
Instant WhatsApp Alert:
"⚠️ New Review Alert ⭐ 2 stars -- Google Maps 'Waited 2 hours, doctor didn't come' We've drafted a professional reply: 'We're deeply sorry for the wait. Patient time is our priority. Please call +91 XXXXX so we can make this right.' [View & Approve Reply →] [Call Support →]" -
Dashboard "Review Inbox":
┌─────────────────────────────┐ │ 💬 Reviews │ │ │ │ NEW (3) │ │ ┌───────────────────────┐ │ │ │ ⭐⭐⭐⭐⭐ Anonymous │ │ │ │ "Excellent doctor, │ │ │ │ very caring" │ │ │ │ [✓ Auto-replied ✓] │ │ │ └───────────────────────┘ │ │ ┌───────────────────────┐ │ │ │ ⭐⭐ Anonymous │ │ │ │ "Waited too long" │ │ │ │ │ │ │ │ AI Suggested Reply: │ │ │ │ "We're sorry..." │ │ │ │ [✓ Approve] [✏️ Edit]│ │ │ └───────────────────────┘ │ │ │ │ "💡 Tip: Responding to │ │ negative reviews calmly │ │ builds trust with │ │ future patients" │ │ │
└─────────────────────────────┘
3. **Reply Templates (Positive):**
- Auto-approve 4-5 star reviews
- Template: "Thank you for your kind words, [Name]! We're glad you had a great experience. -- Dr. Sharma"
- Personalized with patient name from review
4. **Reply Templates (Negative) -- ALWAYS manual approval:**
- AI drafts empathetic, non-defensive response
- Never blames the patient
- Always includes call to action (call us, visit again)
- Medical claims fact-checked (no promises of outcomes)
5. **Emotional Support Messaging:**
"Getting a negative review can be upsetting. Here's what to know: • One negative review among many positive ones has minimal impact • Your response matters more than the review itself • A professional reply shows future patients you care • We can help you craft the right response" [Talk to Support] [View Suggested Reply]
6. **Review Dispute Guidance:**
- "Is this review fake or from someone who wasn't your patient?"
- [Yes -- Help me report to Google] → Step-by-step Google report guide
- "Note: Google rarely removes reviews. Focus on your reply instead."
---
#### FRICTION 7: "Doctor wants to change their clinic hours"
**Root Cause:** Clinic hours change (seasonal, Ramadan, vacation, emergencies). This is the #1 most common change request.
**UI/UX Solutions:**
1. **Self-Service in Dashboard:**
⚙️ Settings → Business Information
"Clinic Hours" Monday: [9:00 AM] to [6:00 PM] [✓ Open] [Closed] Tuesday: [9:00 AM] to [6:00 PM] [✓ Open] [Closed] Wednesday: [9:00 AM] to [6:00 PM] [✓ Open] [Closed] Thursday: [9:00 AM] to [6:00 PM] [✓ Open] [Closed] Friday: [9:00 AM] to [1:00 PM] [✓ Open] [Closed] Saturday: [9:00 AM] to [2:00 PM] [✓ Open] [Closed] Sunday: [Closed]
"These hours will be updated on:" ☑ Google Maps ☑ Your directory profile ☑ All 30 citation sites
[Save Changes →]
2. **WhatsApp Update:**
Doctor sends WhatsApp: "Change my Saturday hours to 10-1"
Bot replies: "Got it! I'll update your Saturday hours to 10:00 AM - 1:00 PM on Google Maps, your directory profile, and all citations. Confirm? Reply YES to proceed."
Doctor: "YES" Bot: "✓ Updated! Changes will be live within 24 hours."
3. **Vacation/Holiday Mode:**
"Going on vacation? Set holiday hours:" [From Date] [To Date] [Hours: Reduced / Closed] "We'll update Google Maps and auto-post: 'Closed for [dates]. Emergency: [phone]'"
4. **One-Click Common Changes:**
- "Ramadan Hours" → Pre-set: 10 AM - 4 PM
- "Sunday Closed" → One toggle
- "Emergency Only" → Custom message
5. **Change Propagation Tracking:**
After doctor saves hours:
"Updating your hours everywhere..." ✅ Google Maps -- Updated (2 min ago) ✅ Directory Profile -- Updated (5 min ago) ⏳ Justdial -- Pending (usually 24h) ⏳ Practo -- Pending ✅ 27 other sites -- Updated
---
#### FRICTION 8: "Doctor doesn't understand the monthly report"
**Root Cause:** Reports are full of SEO jargon (DA, NAP, schema, citations). Doctors just want to know: "Am I getting more patients?"
**UI/UX Solutions:**
1. **Lead with Patient Impact:**
┌─────────────────────────────┐ │ JUNE 2026 REPORT │ │ │ │ "This month, more patients │ │ found your clinic online" │ │ │ │ 📈 Google Maps: #3 │ │ "You're in the top 3 │ │ when patients search │ │ 'cardiologist in Kochi'"│ │ │ │ 🏥 28 places now show │ │ your clinic details │ │ "(up from 23 last month)"│ │ │ │ ⭐ 12 new patient reviews │ │ "All replied to -- this │ │ builds trust" │ │ │ │ 📱 4 posts published │ │ "Keeping your profile │ │ active on Google" │ └─────────────────────────────┘
2. **Plain Language Glossary:**
Every technical term has a (?) tooltip:
- "Citations (?): Other websites that list your clinic name, address, and phone. More = better."
- "Schema (?): Code that helps Google understand your clinic. You don't need to worry about this."
- "NAP (?): Name, Address, Phone -- the consistency of your info across the web."
3. **Comparison Context:**
- "Your clinic ranks #3. The average cardiologist in Kochi ranks #8."
- "You have 28 citations. Top-ranked clinics typically have 25+."
4. **Action-Oriented Summary:**
Instead of just data, suggest actions:
- "💡 Getting good reviews? Ask happy patients to leave one on Google!"
- "💡 Your GBP posts are performing well. Want to increase to 2 per week?"
5. **Video Report Option:**
- "Prefer a video? Watch Dr. Sharma's June report (2 min)"
- Auto-generated narrated video walkthrough
- Malayalam voiceover option
6. **Report Delivery Options:**
- WhatsApp: Summary + PDF link
- Email: Full PDF attachment
- Dashboard: Interactive version with charts
- Phone call: "Would you like us to walk you through your report?"
---
#### FRICTION 9: "Doctor wants to cancel (retention strategy)"
**Root Cause:** Price sensitivity, not seeing results, competitor offer, or personal circumstances.
**UI/UX Solutions:**
1. **Cancellation Flow (Mandatory Friction + Value Reminder):**
⚠️ Before You Go...
"Dr. Sharma, you've been with us for 6 months. Here's what we've achieved together:"
📈 Google Maps: #7 → #3 (+4 positions) 🏥 28 citations built ⭐ 45 reviews collected (4.2★ average) 📱 24 social posts published
"If you cancel, these will gradually decrease over the next 3 months (not disappear overnight)."
"Can we help instead?" [📞 Talk to Our Team -- Maybe we can help] [💰 Switch to Starter Plan (₹4K/month)] [⏸️ Pause for 1 Month (keep everything)] [🚫 Yes, Cancel My Account]
2. **Pause Option (Not Cancel):**
- "Pause your account for ₹1,000/month"
- What continues: Directory profile stays live, citations maintained
- What pauses: New posts, new citations, review replies
- Doctor can resume anytime with one click
3. **Downgrade Option:**
- "Switch to Starter at ₹4K/month" -- Immediate
- Pro-rated refund for difference
- Features reduce at next billing cycle
4. **Exit Interview (if they proceed):**
"We're sorry to see you go. Help us improve:" Why are you leaving? ☐ Too expensive ☐ Not seeing results ☐ Found another service ☐ Clinic is closing / personal reasons ☐ Other: _______
"Would you consider staying if:" ☐ Price was lower ☐ We showed results faster ☐ We provided more support ☐ We added [feature]
5. **Graceful Offboarding:**
- Cancellation effective at end of billing period (not immediate)
- Directory profile: Stays live for 30 days with "powered by RankFlow" removed
- Citations: Gradual removal over 90 days (not overnight)
- Data export: PDF of all reports, list of all citation URLs
- "You're always welcome back. Reactivate anytime."
---
### 5.3 Admin Friction
#### FRICTION 10: "50+ clients to review content for"
**Root Cause:** Admin is bottlenecked. Content approval queue grows, causing publishing delays.
**UI/UX Solutions:**
1. **Prioritized Queue:**
Sort by: [Urgency (publishing soonest)] ← Default [Client tier (Premium first)] [Content type (negative reviews first)] [Oldest first]
2. **Bulk Actions:**
- Select all visible → [Approve All] [Reject All]
- Filter by type: "Show me only GBP posts" → Approve in bulk
- Auto-approve rules: "Auto-approve all posts with confidence > 90%"
3. **Keyboard Shortcuts:**
- `A` = Approve + next
- `R` = Reject + next
- `E` = Edit
- `→` = Next item
- `←` = Previous item
- Target: 60+ items approved per hour
4. **AI Confidence Scoring:**
- High confidence (>90%): Auto-approve after 24h unless flagged
- Medium (70-90%): Show in queue with green indicator
- Low (<70%): Show with yellow warning, require review
5. **Client Segmentation:**
- First-month clients: All content requires approval (learning phase)
- Established clients: Auto-approve by category
- VIP/Enterprise: Always manual approval
---
#### FRICTION 11: "Citation submission failures piling up"
**Root Cause:** Directory sites change their forms, add CAPTCHA, go down, or block automated submissions.
**UI/UX Solutions:**
1. **Failure Dashboard:**
┌──────────────────────────────────────────────────┐ │ CITATION FAILURES (Last 7 Days) │ │ │ │ Site Fails Success Rate Action │ │ ────────────────────────────────────────────── │ │ Justdial 0 100% ✓ Healthy │ │ Yelp 12 78% ⚠️ Check │ │ Hotfrog 8 72% ⚠️ Check │ │ Practo 3 95% ✓ Healthy │ │ │ │ [View All Failures →] [Retry All Failed →] │ └──────────────────────────────────────────────────┘
2. **Auto-Retry with Escalation:**
- Attempt 1: Immediate retry (network blip?)
- Attempt 2: After 1 hour
- Attempt 3: After 6 hours
- Attempt 4: Alert admin + mark for manual review
3. **Site Health Monitoring:**
- Automated daily check: Can we submit to this site?
- If site is down/changed: Mark as "Temporarily Unavailable"
- Don't attempt submissions to unhealthy sites
- Auto-re-enable when site comes back
4. **2Captcha Integration:**
- Automatic CAPTCHA solving for form-based submissions
- Cost: ~$0.002 per CAPTCHA
- Fallback to manual if 2Captcha fails
5. **Manual Override:**
- "This site requires manual submission"
- Create task for VA/fresher to manually submit
- Mark as "Pending Manual" in dashboard
- VA marks complete with URL → System verifies
---
#### FRICTION 12: "Token expiry management across all clients"
**Root Cause:** Google, Meta, and other OAuth tokens expire. Keeping 100+ client tokens fresh is operationally intense.
**UI/UX Solutions:**
1. **Token Health Dashboard:**
┌──────────────────────────────────────────────────┐ │ TOKEN EXPIRY OVERVIEW │ │ │ │ Expired (now): 2 clients [Fix →] │ │ Expiring < 3 days: 5 clients [Notify →] │ │ Expiring < 7 days: 12 clients [Watch] │ │ Healthy: 68 clients ✓ │ │ │ └──────────────────────────────────────────────────┘
2. **Automated Refresh:**
- Daily cron job: Refresh all tokens 7 days before expiry
- Success: Logged silently
- Failure: Added to "Requires Attention" list
3. **Proactive Client Outreach:**
- 3 days before expiry: WhatsApp to client
"Hi Dr. Sharma! Your Google connection needs a quick refresh.
Tap here to reconnect (takes 30 seconds): [Link]"
- Day of expiry: Second WhatsApp + Email
- 1 day after expiry: Support call scheduled
4. **One-Click Reconnect (Client):**
- Client taps link → Pre-authenticated OAuth (remembers account)
- Usually 1-tap approval (not full sign-in again)
- "✓ Reconnected! No further action needed."
5. **Admin Actions:**
- [Refresh All Tokens] button
- [Send Reminder to All Expiring] button
- Bulk export: "Clients needing reconnection this week"
---
#### FRICTION 13: "Billing failures and follow-ups"
**Root Cause:** Indian payment methods fail frequently (UPI limit exceeded, card expired, insufficient balance).
**UI/UX Solutions:**
1. **Billing Dashboard:**
┌──────────────────────────────────────────────────┐ │ BILLING OVERVIEW (June 2026) │ │ │ │ Expected: ₹6,96,000 (87 clients) │ │ Collected: ₹6,24,000 (90%) │ │ Pending: ₹48,000 (5 clients) │ │ Failed: ₹24,000 (2 clients) │ │ │ │ [View Failed Payments →] [Send Reminders →] │ └──────────────────────────────────────────────────┘
2. **Retry Strategy:**
- Failure 1: Immediate retry (transient issue?)
- Failure 2: After 24 hours
- Failure 3: After 48 hours
- Failure 4: Account marked "Past Due" + Admin alert
3. **Automated Client Communication:**
Day 0: Payment fails → WhatsApp: "Your RankFlow payment of ₹8,000 didn't go through. Tap to retry: [Razorpay Link]. No worries -- your service continues uninterrupted."
Day 3: Still failed → WhatsApp: "Friendly reminder: Your payment is pending. Tap to update your payment method: [Link]"
Day 7: Final notice → Phone call from support → WhatsApp: "Your account will be paused on [Date]. To continue, please pay ₹8,000: [Link]"
4. **Grace Period:**
- 7-day grace period before any service reduction
- During grace: All services continue
- After grace: Downgrade to "Paused" (directory profile stays, new work stops)
- After 30 days: Begin gradual citation removal
5. **Payment Method Update:**
- One-click update via Razorpay
- Support-assisted: "Our team can help you update your payment. Call us."
- UPI Autopay support (India-specific)
---
#### FRICTION 14: "Client complaints about results not showing"
**Root Cause:** SEO takes 60-90 days to show results. Doctors expect immediate impact.
**UI/UX Solutions:**
1. **Set Expectations Upfront (During Onboarding):**
"Here's what to expect:" Week 1-2: Directory profile live, citations building Week 3-4: Google starts noticing changes Week 5-8: Ranking improvements begin Week 9-12: Significant position improvements Month 3+: Top 3 positions for most keywords
"Every clinic is different. We'll send you weekly updates so you can track progress."
2. **Progress Milestones:**
Celebrate small wins along the way:
- Day 1: "🎉 Your directory profile is live!"
- Day 7: "📊 First 10 citations built!"
- Day 14: "📈 Your first ranking update: +2 positions!"
- Day 30: "📄 Your first monthly report is ready"
- Day 60: "🏆 You're in the top 5 for [keyword]!"
3. **Competitor Comparison:**
- "You're at #7. The #1 clinic has been doing SEO for 2 years."
- "Your progress in 30 days matches what most clinics see in 60."
4. **Support Scripts:**
Train support team on responses:
- "I understand your concern. Let's look at your progress together."
- "In 30 days, you've gone from #12 to #7. That's significant."
- "SEO is like planting a tree -- the roots are growing even when you can't see them."
- "Let's schedule a call to review your report together."
5. **Results Guarantee (Limited):**
- "If you don't see improvement within 60 days, we'll give you a free month."
- This reduces perceived risk without being a refund promise
- "Improvement" defined as any positive ranking change (achievable)
---
## 6. Retention Without Lock-In
### 6.1 Philosophy
The original "delete everything on cancellation" strategy is:
- **Ethically questionable:** Punishing customers for leaving creates bad word-of-mouth
- **Legally risky:** Potential consumer protection violations under Indian law
- **Counterproductive:** Scared customers don't become advocates
**Instead, we design for "retention through value" -- clients stay because leaving hurts their business, not because we destroy it.**
---
### 6.2 Retention Mechanisms
#### 6.2.1 Value-Based Retention (Superior Results)
**Strategy:** Make the product so effective that canceling means losing patient acquisition.
**Implementation:**
- Track patient enquiries from Google Maps (use GBP insights API)
- Show in dashboard: "Est. 45 patients found you on Google this month"
- Monthly report: "Your online presence generated ~₹X in patient value"
- Quote from satisfied client: "I've seen 30% more patients since joining RankFlow"
**Success Metric:** Client sees clear ROI. Canceling = losing patients = losing revenue.
---
#### 6.2.2 Gradual Degradation (Not Instant Deletion)
**Strategy:** Instead of overnight destruction, gradual decay that gives clients time to reconsider.
**Timeline:**
Day 0 (Cancel):
→ Account marked "Cancelled"
→ All new work stops immediately
→ Directory profile: Remains active for 30-day grace period
→ Citations: All remain
→ GBP posts: Stop
→ Social posts: Stop
→ Review replies: Stop
Day 7: → WhatsApp reminder: "Your profile will be removed in 23 days. Reactivate to keep it live."
Day 30: → Directory profile: Removed from directory (returns 404, removed from sitemap) → Citations: First 5 removed (lowest-value sites) → WhatsApp: "Dr. Sharma, your directory profile has been removed. Reactivate for ₹X: [Link]"
Day 60: → Directory profile: Already removed (Day 30) → Citations: 10 more removed → GBP: Last posts are 60 days old (Google sees inactivity)
Day 90: → Directory profile: Already removed (Day 30) → Citations: All removed → Final email: "Your account has been fully closed. Data export: [Link]" → "We'd love to have you back. Reactivate within 30 days → all citations rebuilt at no extra cost."
**Why this works:**
- Client can reverse decision at any point during degradation
- No sudden shock to their business
- Word-of-mouth remains positive: "They were fair when I left"
- Reactivation incentive creates urgency
---
#### 6.2.3 Data Export Options
**Strategy:** Give clients ownership of their data. Paradoxically, this increases trust and retention.
**Export Package (delivered on cancellation):**
Your RankFlow Data Export:
📄 directory-profile-content.pdf -- All articles, FAQs, content we wrote 📊 all-reports.pdf -- Complete monthly report history 📋 citations-list.csv -- All 30 citation URLs (what we built) 📸 social-posts.zip -- All images and captions we published 📈 ranking-history.csv -- Your position data over time 📷 gbp-photos.zip -- All photos uploaded to Google
"Keep these for your records or share with your next provider."
---
#### 6.2.4 Annual Plan Incentives
**Strategy:** Reward commitment with significant discounts.
| Plan | Monthly | Annual (10 months) | Savings |
|---|---|---|---|
| Starter | ₹4,000 | ₹40,000 | ₹8,000 (17% off) |
| Standard | ₹8,000 | ₹80,000 | ₹16,000 (17% off) |
| Premium | ₹12,000 | ₹1,20,000 | ₹24,000 (17% off) |
| Enterprise | ₹20,000 | ₹2,00,000 | ₹40,000 (17% off) |
**Additional Annual Benefits:**
- 2 months free (pay for 10, get 12)
- Priority support (4-hour response vs. 12-hour)
- Dedicated onboarding call
- "Annual Partner" badge on dashboard
**Friction Reduction:**
- Offer annual at onboarding (highest intent moment)
- Show monthly cost equivalent: "Just ₹6,667/month when paid annually"
- Remind 30 days before renewal: "Your annual plan renews in 30 days"
---
#### 6.2.5 Loyalty Program
**Strategy:** Reward long-term clients with increasing value.
**"RankFlow Partner" Tiers:**
Month 1-3: Bronze Partner → Standard features
Month 4-6: Silver Partner
→ +2 extra GBP posts/month
→ Priority support (faster response)
→ "Silver" badge on dashboard
Month 7-12: Gold Partner → +5 extra citations (35 total) → Monthly strategy call with support → Early access to new features → "Gold" badge on dashboard
Year 2+: Platinum Partner → All Gold benefits → Free custom directory profile redesign annually → Dedicated phone line → Referral bonus: 1 free month per referred client
**Why this works:**
- Creates progression and achievement
- Makes switching feel like "losing status"
- Benefits are real but cost us little
- Gamification without being gimmicky
---
#### 6.2.6 Dedicated Support for Long-Term Clients
**Strategy:** Relationship-based retention through human connection.
**Implementation:**
- Every client gets a named support contact (not a generic inbox)
- "Your RankFlow partner: [Name] + [Photo] + [WhatsApp]"
- Monthly check-in call for Gold+ clients
- Birthday/clinic anniversary message
- "Dr. Sharma, it's been 6 months! Here's what we've achieved together..."
**Support Quality Standards:**
| Tier | Response Time | Resolution Time |
|---|---|---|
| Starter | 24h (WhatsApp) | 48h |
| Standard | 12h (WhatsApp/Call) | 24h |
| Premium | 4h (Dedicated) | 12h |
| Enterprise | 1h (Account Manager) | 4h |
---
### 6.3 Retention Metrics Dashboard
**Admin View:**
┌────────────────────────────────────────────────────────────┐ │ RETENTION METRICS │ ├────────────────────────────────────────────────────────────┤ │ │ │ Churn Rate (Last 30 Days): 3.2% (Target: < 5%) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Cancelled: 3 │ │ Downgraded:2 │ │ Paused: 4 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ Churn Reasons: │ │ Too expensive: 2 Results slow: 1 Other: 1 │ │ │ │ Retention Cohort: │ │ Month 1: 100% → M2: 85% → M3: 78% → M6: 72% → M12: 65% │ │ (Industry avg: 100% → 80% → 70% → 60% → 50%) │ │ │ │ At-Risk Clients (engagement drop): │ │ Dr. Nair (login: 14 days ago) │ │ Dr. Mathew (support ticket unresolved 5 days) │ │ [View All →] [Send Re-engagement →] │ │ │ │ Reactivation (Last 30 Days): 2 clients │ │ Revenue Recovered: ₹24,000 │ │ │ └────────────────────────────────────────────────────────────┘
---
## 7. Communication Strategy
### 7.1 Monthly Report Email Template
**Subject:** `Dr. Sharma, your June report is here 📊 -- #3 on Google Maps!`
**From:** `Dr. Sharma's RankFlow Partner <reports@rankflow.in>`
**Preview Text:** `28 citations live, 12 new reviews this month, +2 positions on Google`
**Email Body:**
```html
┌─────────────────────────────────────────────────────────────┐
│ [RankFlow Logo] │
│ │
│ Hi Dr. Sharma, │
│ │
│ Your June 2026 report is ready. Here's what stood out: │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 🏆 GOOGLE MAPS: Position #3 │ │
│ │ You're in the TOP 3 for 'cardiologist in Kochi' │ │
│ │ Change: ↑ 2 positions from last month │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ This Month's Numbers: │
│ 🏥 Citations: 28 live (+5 new) │
│ ⭐ Reviews: 127 total, 4.2★ average (+12 new) │
│ 📱 Social Posts: 4 published │
│ 📈 Ranking Change: +2 positions │
│ │
│ [📄 View Full Report →] │
│ [📥 Download PDF] │
│ │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ │
│ What's Coming in July: │
│ • Fresh GBP posts every week │
│ • 2 new citations to reach 30/30 │
│ • Your directory profile content refresh │
│ │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ │
│ Questions? Reply to this email or WhatsApp us: │
│ +91 98XXX XXXXX │
│ │
│ Your RankFlow Partner, │
│ [Name] │
│ │
│ [Unsubscribe from reports] [Update preferences] │
│ │
│ RankFlow AI | Kochi, Kerala | rankflow.in │
└─────────────────────────────────────────────────────────────┘
Design Principles:
- Single-column, 600px max width
- Large tap targets for mobile email clients
- Emoji-based visual hierarchy (no images required for basic comprehension)
- PDF attachment always included
- WhatsApp CTA always present
- Unsubscribe link (legally required)
- Sent on 1st of every month, 9 AM IST
7.2 Weekly Digest Design#
Subject: Your week at a glance 📊 -- RankFlow
WhatsApp Version (Primary for doctors):
📊 RankFlow Weekly Digest
Dr. Sharma, here's your week (June 1-7):
🏥 +3 new citations built (28/30 total)
📱 1 Google post published
⭐ 2 new reviews (both replied to)
📈 Google Maps: Still #3 ✓
Everything is on track! 💪
Questions? Reply here or call 1800-RANKFLOW.
Email Version:
Shorter version of monthly report. 3-4 lines max.
Focus: "Everything is working, nothing to worry about"
Purpose: Stay top-of-mind, reduce anxiety
7.3 Alert Types and Thresholds#
Alert Delivery Matrix:
| Alert Type | In-App | Frequency | ||
|---|---|---|---|---|
| Ranking milestone | Yes | Yes | Yes | Immediate |
| Negative review | Yes | No | Yes | Immediate |
| GBP token expiry | Yes | Yes | Yes | Days 3, 1, 0 |
| Payment failure | Yes | Yes | Yes | Immediate |
| Payment success | No | Yes | No | Immediate |
| Citation failure | No | No | Yes | Batched daily |
| Content approval needed | Yes | No | Yes | Immediate |
| Weekly digest | Yes | Optional | No | Every Monday |
| Monthly report | Summary | Full PDF | Yes | 1st of month |
| Trial ending | Yes | Yes | Yes | Days 5, 2, 0 |
Alert Thresholds:
| Metric | Green | Yellow | Red |
|---|---|---|---|
| Google Maps Position | Top 3 | #4-#8 | #9+ |
| Citation Success Rate | >95% | 80-95% | <80% |
| GBP Token Validity | >7 days | 3-7 days | <3 days |
| Payment Status | Paid | Retry pending | Failed |
| Client Login | <7 days | 7-14 days | >14 days |
7.4 WhatsApp Notification Strategy#
Frequency Guidelines:
- Maximum: 1 WhatsApp per day (for any reason)
- Default: 2-3 WhatsApp messages per week
- Never send: Before 8 AM or after 8 PM IST
- Always include: Clear value + easy action
WhatsApp Templates (pre-approved):
Template: monthly_report_summary
"📊 Hi {{1}}, your {{2}} report is ready!
🏆 Google Maps: Position {{3}}
🏥 Citations: {{4}} live
⭐ Reviews: {{5}} ({{6}}★ avg)
📄 Full report: {{7}}"
Template: negative_review_alert
"⚠️ New review on Google Maps:
⭐ {{1}} stars -- {{2}}
We've drafted a reply. Approve it here: {{3}}"
Template: trial_reminder
"Hi {{1}}, your RankFlow trial ends in {{2}} days.
Continue for just ₹{{3}}/month: {{4}}
Questions? Reply here 💬"
Template: ranking_milestone
"🎉 Great news, {{1}}!
You reached position {{2}} on Google Maps for '{{3}}'!
Keep it up! 💪"
7.5 In-App Notification System#
┌─────────────────────────────┐
│ 🔔 (3) │
│ │
│ NOTIFICATIONS │
│ │
│ 🏆 2h ago │
│ "You reached #3 on Google │
│ Maps!" │
│ [View →] │
│ │
│ ⭐ 1d ago │
│ "New 5-star review. Auto- │
│ replied." │
│ [View →] │
│ │
│ 📱 2d ago │
│ "Post approval needed: │
│ Instagram post" │
│ [Review →] │
│ │
│ [Mark all read] │
└─────────────────────────────┘
Notification Types:
- Success: Ranking improvements, milestones, posts published (green icon)
- Action needed: Approvals, reconnections, payment updates (orange icon)
- Warning: Token expiry, failures, issues (red icon)
- Info: Reports, digests, tips (blue icon)
8. Success Metrics (for the Product Team)#
8.1 Activation Metrics#
Definition: A client is "activated" when they complete all onboarding steps and receive their first value moment.
Activation Funnel:
Step 1: Account created (phone verified)
Step 2: Business profile complete (name, address, category)
Step 3: GBP connected (or explicitly deferred)
Step 4: Plan selected and payment method on file
Step 5: Directory profile live (first value moment)
Step 6: First citation batch complete
Step 7: First Google post published
Step 8: First monthly report received
Activation Criteria (client is considered "activated" when):
- ✅ Completed onboarding (Steps 1-4)
- ✅ Directory profile is live (Step 5)
- ✅ At least 10 citations published (Step 6)
- ✅ OR: Has logged into dashboard at least twice in first 14 days
Target: 80% of signups reach activation within 7 days
8.2 Engagement Metrics#
Weekly Active Usage Definition: Client is "active" in a given week if they:
- Log into dashboard at least once, OR
- Open a report email, OR
- Interact with a WhatsApp message, OR
- Approve/reject content
Engagement Levels:
| Level | Definition | % of Base |
|---|---|---|
| Power User | Logs in 3+ times/week, interacts with features | 10% |
| Active | Logs in 1-2 times/week or opens emails | 40% |
| Passive | Opens monthly report only | 35% |
| Dormant | No interaction in 14+ days | 15% |
Feature-Specific Engagement:
| Feature | Target Weekly Usage |
|---|---|
| Dashboard login | 50% of active clients |
| Report opened | 70% of active clients (monthly) |
| Content approval | 20% of active clients (if enabled) |
| WhatsApp interaction | 40% of active clients |
| Settings/Profile update | 5% of active clients |
8.3 Retention Metrics#
Cohort-Based Retention Analysis:
Cohort Retention Table ( Monthly )
Cohort M0 M1 M2 M3 M6 M12
─────────────────────────────────────────
Jan 2026 100% 92% 88% 85% 78% 70%
Feb 2026 100% 89% 85% -- -- --
Mar 2026 100% 94% -- -- -- --
─────────────────────────────────────────
Average 100% 92% 87% 85% 78% 70%
Target Retention Rates:
| Period | Target | Industry Avg |
|---|---|---|
| Month 1 | 90%+ | 80% |
| Month 3 | 80%+ | 65% |
| Month 6 | 72%+ | 55% |
| Month 12 | 65%+ | 45% |
Churn Analysis: Track by:
- Plan tier (which plans churn more?)
- Acquisition channel (which source retains better?)
- Geography (which cities?)
- Onboarding completion (did they connect GBP?)
- Support ticket volume (correlation with churn)
8.4 NPS / Satisfaction Proxy#
No formal NPS (doctors won't fill surveys). Instead:
Proxy Metric 1: Referral Rate
% of clients who refer at least 1 new client within 6 months
Target: 15%+
Proxy Metric 2: Upgrade Rate
% of Starter/Standard clients who upgrade within 3 months
Target: 20%+
Proxy Metric 3: Support Satisfaction
After every support interaction (WhatsApp):
"Was this helpful? 👍 / 👎"
Target: 90%+ 👍 rate
Proxy Metric 4: Login Frequency
Clients who log in weekly are "satisfied"
Clients who don't log in for 2+ weeks are "at risk"
Proxy Metric 5: Renewal Rate (Annual Plans)
% of annual clients who renew
Target: 80%+
8.5 Support Ticket Volume & Resolution#
Tickets by Category:
| Category | Target % | Target Resolution |
|---|---|---|
| "How do I...?" (Help) | 40% | 4 hours |
| "Something is broken" (Bug) | 20% | 8 hours |
| "I want to change..." (Request) | 25% | 24 hours |
| "I'm not happy" (Complaint) | 10% | 2 hours |
| "I want to cancel" (Churn) | 5% | 2 hours |
Support Metrics:
| Metric | Target |
|---|---|
| First response time | < 2 hours (Standard), < 4 hours (Starter) |
| Resolution time | < 24 hours (95% of tickets) |
| Tickets per client per month | < 0.5 |
| Self-service rate (FAQ solves) | > 30% |
| Escalation to admin | < 10% |
Weekly Support Dashboard:
Week of June 1-7:
- New tickets: 23 (down from 31 last week)
- Avg response time: 1.8 hours ✓
- Avg resolution time: 6.2 hours ✓
- Escalated: 2 (9%) ✓
- CSAT (👍 rate): 94% ✓
- Top issue: "How to update clinic hours" (5 tickets)
→ Action: Improve dashboard self-service for hours update
9. Phase 1 Feature Cut (MoSCoW)#
9.1 Context#
- Timeline: 18 weeks (4.5 months)
- Team: 1 senior engineer + AI assistance
- Goal: Beta launch with 10 Kerala clients
- Constraint: Must demonstrate value within 60 days of client signup
9.2 MoSCoW Prioritization#
MUST HAVE (Launch Blockers -- Weeks 1-12)#
| # | Feature | Weeks | Rationale |
|---|---|---|---|
| 1 | Monorepo + Auth + Database | 1-2 | Foundation. No product without this. |
| 2 | Client Onboarding Flow | 2-4 | Without onboarding, no clients. Mobile-first, WhatsApp OTP, simplified forms. |
| 3 | GBP OAuth + Basic Management | 3-5 | Core value prop. Posts, hours, basic info. |
| 4 | Directory Profile System + Dynamic Routes | 4-6 | The "owned" asset. Dynamic route per client. |
| 5 | AI Content Engine (Single LLM) | 5-7 | Claude-only for Phase 1. Multi-LLM is Phase 2. |
| 6 | Citation Engine (10 Core Sites) | 6-8 | 10 most important directories, not 30. API-based first. |
| 7 | Client Dashboard (Mobile-first) | 7-9 | 3 KPI cards, activity feed, basic charts. |
| 8 | Admin Dashboard (Client Management) | 8-10 | Client table, basic filters, content queue. |
| 9 | Billing (Razorpay + Stripe) | 9-10 | Subscription creation, payment collection, basic retry. |
| 10 | Monthly Email Report | 10-11 | PDF generation + email delivery. Simple template. |
| 11 | Review Monitoring + Auto-Reply | 11-12 | Daily poll, positive auto-reply, negative alert. |
| 12 | WhatsApp Notifications | 12 | Key alerts via WhatsApp Business API. |
MUST Total: 12 features, 12 weeks (with buffer)
SHOULD HAVE (Important -- Weeks 12-16)#
| # | Feature | Weeks | Rationale |
|---|---|---|---|
| 13 | Social Media (Instagram via Composio) | 12-14 | Adds value but not core. Deferrable if time crunch. |
| 14 | Content Approval Workflow | 13-14 | Important for medical clients. Manual workaround possible. |
| 15 | Vernacular (Malayalam UI) | 14-15 | Important for Kerala market. Can launch with English + support. |
| 16 | Job Queue Monitoring (Admin) | 14-15 | Important for ops. Basic logging acceptable for 10 clients. |
| 17 | Weekly Digest Email | 15 | Nice engagement driver. Monthly is sufficient for beta. |
| 19 | Trial System (7-day free) | 15-16 | Sales conversion. Can start with paid-only for beta. |
SHOULD Total: 7 features, 4 weeks
COULD HAVE (Nice-to-Have -- Weeks 16-18 if Time Permits)#
| # | Feature | Rationale |
|---|---|---|
| 20 | Social (Facebook posting) | Instagram covers most clients |
| 21 | NAP Consistency Monitoring | Manual check sufficient for 10 clients |
| 22 | Advanced Admin Analytics | Revenue tracking can be manual in spreadsheet |
| 23 | Sub-accounts | Most beta clients are single-doctor |
| 24 | Referral Program | Can track manually for beta |
| 26 | Multi-LLM Router | Claude-only works fine for beta scale |
| 27 | Advanced Report Charts | Table + basic line chart is sufficient |
WON'T HAVE (Phase 2 -- Post-Beta)#
| # | Feature | Rationale |
|---|---|---|
| 28 | Citation Network (All 30 Sites) | Build 10 first, scale later |
| 29 | Social Scheduling Calendar | Post immediately or basic queue |
| 30 | Advanced SEO Keyword Tracking | Manual rank check for beta |
| 31 | White-Label Agency Portal | No agency partners for beta |
| 32 | API Access for Clients | No enterprise clients in beta |
| 33 | AI Answer Engine Optimization | Unproven, complex, low priority |
| 34 | DPDPA Compliance Automation | Can be manual for 10 clients |
| 35 | Advanced Retention Analytics | Basic churn tracking is fine |
| 36 | Video Reports | PDF is sufficient |
| 37 | Auto-Generated Images for Posts | Manual image upload |
| 38 | Competitor Comparison Feature | Manual research for beta |
9.3 Phase 1 Feature Cut Summary Table#
| Module | Phase 1 (MVP) | Phase 2 (Scale) |
|---|---|---|
| Onboarding | Phone OTP, basic info, GBP connect, plan select | Social connect, video guides, full deferral system |
| Directory Profile | Basic listing, dynamic route, core content | Premium layout, related clinics, city/specialty pages |
| Citations | 10 core directories, API-based | 30 directories, form-based, CAPTCHA solving |
| GBP | Posts, hours, info, review replies | Photos, Q&A, products, services, video |
| Social | Instagram only, basic posting | Facebook, stories, scheduling calendar |
| AI Engine | Claude-only, basic prompts | Multi-LLM router, prompt A/B testing |
| Client Dashboard | 3 KPIs, activity feed, basic charts | Full analytics, comparison, settings |
| Admin Dashboard | Client table, content queue, billing | Job monitoring, full analytics, bulk actions |
| Reports | Monthly PDF email, basic charts | Weekly digest, real-time dashboard, video |
| Billing | Razorpay, basic retry, 2 plans | Stripe, full retry, all 4 plans, annual |
| Support | WhatsApp + basic call | Dedicated partners, help center, callbacks |
| Language | English | Malayalam, Hindi, Tamil |
9.4 Phase 1 Technical Simplifications#
| Area | Full Build | Phase 1 Simplification |
|---|---|---|
| Job Queue | Inngest/BullMQ | In-memory queue with cron (10 clients) |
| AI Router | Multi-LLM | Claude API only |
| PDF Generation | Playwright + HTML | Simple HTML → PDF library (puppeteer) |
| Citation Engine | Plugin system | Hardcoded submitters for 10 sites |
| Directory Profile | Dynamic routes + ISR | Pre-rendered profiles, revalidate on content change |
| Auth | NextAuth + Google OAuth | Credentials auth + simple Google OAuth for GBP |
| Cache | Redis | In-memory (10 clients) |
| Monitoring | Full observability | Basic logging + Slack webhooks |
| Testing | Unit + E2E | Critical path E2E only |
| Deployment | CI/CD pipeline | Manual deploy via Vercel CLI |
9.5 18-Week Timeline (Phase 1)#
Week 1-2: Foundation (monorepo, DB, auth, CI/CD)
Week 3-4: Onboarding flow (phone OTP, forms, progress)
Week 4-5: Directory profile system (dynamic routes, content pipeline, single domain)
Week 5-6: GBP OAuth + basic API (posts, hours, info)
Week 6-7: AI content engine (Claude, prompt system)
Week 7-8: Citation engine (10 core directories)
Week 8-9: Client dashboard (mobile-first, 3 KPIs)
Week 9-10: Admin dashboard (client table, content queue)
Week 10-11: Billing (Razorpay, subscriptions, basic retry)
Week 11-12: Review monitoring + auto-reply
Week 12-13: Monthly report (PDF generation + email)
Week 13-14: Instagram integration (Composio)
Week 14-15: Malayalam UI + content approval workflow
Week 15-16: Polish, bug fixes, performance
Week 16-17: Beta client onboarding (10 Kerala doctors)
Week 17-18: Feedback, hotfixes, iteration
Beta Launch Criteria (Week 18):
- 10 Kerala doctors onboarded and activated
- All 10 have live directory profiles
- All 10 have GBP connected and posting
- All 10 have at least 8 citations live
- Monthly report delivered to all 10
- No critical bugs in onboarding or dashboard
- Admin can manage all clients from dashboard
- Billing collection working (Razorpay)
9.6 Risk Mitigation for Phase 1#
| Risk | Impact | Mitigation |
|---|---|---|
| Engineer gets stuck on GBP API | High | Fallback: Manual GBP management via support for beta |
| Razorpay integration delays | Medium | Start with manual invoicing + UPI collection |
| Claude API rate limits | Medium | Implement basic retry + queue. Throttle if needed. |
| Citation sites block submissions | Medium | Focus on 5 API-based sites + 5 owned blog sites |
| Beta client acquisition slow | High | Founder/sales team responsible. 10 clients committed before Week 12. |
| WhatsApp API approval delays | Low | Use WhatsApp Business API sandbox for beta |
Appendices#
Appendix A: User Flow Diagrams (Mermaid)#
A.1 Client Onboarding Flow#
flowchart TD
A[Entry Point] --> B{Logged In?}
B -->|No| C[Welcome Screen]
B -->|Yes| D[Dashboard]
C --> E[Phone Verification]
E -->|OTP Success| F[Business Info]
E -->|OTP Failed| E
F --> G[GBP Connection]
G -->|Connected| H[Social Connection]
G -->|Deferred| H
G -->|No GBP| I[GBP Creation Guide]
I --> G
H -->|Connected| J[Plan Selection]
H -->|Skipped| J
J -->|Trial Started| K[Onboarding Complete]
K --> L[WhatsApp Welcome]
L --> M[Directory Profile Building]
M --> N[Citation Building]
N --> O[First GBP Post]
A.2 Content Approval Workflow#
flowchart TD
A[AI Generates Content] --> B{Content Type?}
B -->|GBP Post| C{Client Pre-Approval?}
B -->|Review Reply| D{Review Rating?}
B -->|Social Post| E{Client Pre-Approval?}
C -->|Yes| F[Pending Approval Queue]
C -->|No| G[Auto-Approve after 24h]
D -->|4-5 Stars| H[Auto-Reply]
D -->|1-3 Stars| I[Manual Approval Required]
E -->|Yes| F
E -->|No| G
F --> J[Admin Reviews]
I --> J
J -->|Approve| K[Publish]
J -->|Reject| L[Discard / Regenerate]
J -->|Edit| M[Admin Edits]
M --> K
G --> K
H --> K
A.3 Cancellation / Retention Flow#
flowchart TD
A[Client Clicks Cancel] --> B[Value Reminder Screen]
B --> C{Client Chooses?}
C -->|Downgrade| D[Switch to Lower Plan]
C -->|Pause| E[Pause Account]
C -->|Talk to Support| F[Support Call Scheduled]
C -->|Proceed to Cancel| G[Exit Interview]
D --> H[Plan Changed]
E --> I[Account Paused]
F --> J{Issue Resolved?}
J -->|Yes| K[Retention Success]
J -->|No| G
G --> L[Grace Period Starts]
L --> M[Gradual Degradation]
M --> N[Final Cancellation]
N --> O[Data Export]
O --> P[Reactivation Offer]
Appendix B: Glossary#
| Term | Meaning |
|---|---|
| GBP | Google Business Profile (formerly Google My Business) |
| NAP | Name, Address, Phone -- consistency across the web |
| Citation | A mention of the business on another website (directory, blog, etc.) |
| SSG | Static Site Generation -- pre-built HTML pages |
| ISR | Incremental Static Regeneration -- update pages without full rebuild |
| LLM | Large Language Model (Claude, GPT-4, etc.) |
| OAuth | Open Authorization -- secure third-party login |
| DA | Domain Authority -- score of how authoritative a website is |
| Schema | Structured data markup that helps search engines understand content |
| MRR | Monthly Recurring Revenue |
| ARPU | Average Revenue Per User |
| OTP | One-Time Password |
| SSO | Single Sign-On |
| ISR | Incremental Static Regeneration |
| RBAC | Role-Based Access Control |
Appendix C: Kerala Market Context#
Why Kerala First:
- High smartphone penetration (70%+)
- High literacy rate (96% -- highest in India)
- Strong medical tourism infrastructure
- English + Malayalam bilingual market
- Relatively affluent patient base
- ICO agency founder has existing network
Kerala-Specific Considerations:
- Malayalam UI is important but not critical (high English literacy)
- WhatsApp is THE communication channel
- Practo is the dominant healthcare directory
- Medical college hospitals dominate -- private clinics need differentiation
- Seasonal variation: Monsoon (June-Sep) = more clinic visits
- Festival calendar affects clinic hours (Onam, Vishu, Ramadan)
Document End#
Next Steps:
- Engineering review of Phase 1 scope
- Finalize 18-week sprint plan
- Set up beta client acquisition pipeline (begin Week 12)
- Provision API keys (Claude, Razorpay, Composio, Cloudflare)
- Begin Kerala doctor outreach for beta waitlist
Document prepared by Product Strategy Agent
For: RankFlow AI Engineering Team
Classification: Confidential -- Internal Use Only