docs: capture missed-call lead recovery future project

projects/missed-call-lead-recovery.md

@@ -0,0 +1,151 @@
+# Missed-Call Lead Recovery — Multi-Tenant SaaS Product
+
+**Saved:** 2026-07-23  
+**Status:** Future Project — Research & Planning  
+**Category:** SaaS Product / Revenue  
+**Owner:** IT Pro Partner (Sho'Nuff)
+
+---
+
+## Product Concept
+
+A multi-tenant SaaS platform that converts missed phone calls into recovered leads via instant SMS text-back. When a small business misses a call, the system immediately texts the caller from the business's number, logs the lead, and optionally triggers email confirmations, owner alerts, and CRM integration — all before the caller dials the next competitor.
+
+**Inspiration:** [never-miss-a-lead-lite](https://github.com/leegoldmd-beep/never-miss-a-lead-lite) (MIT license) — a single-tenant n8n workflow built by a diesel repair shop owner that catches Twilio missed calls, sends an SMS text-back, and logs to Google Sheets. Proven concept, real-world validated.
+
+## Target Customer Outcome
+
+Businesses leave ~62% of calls unanswered (411 Locals study, 2016). Each missed call is a lead that dials the next competitor. This product gives SMBs and agencies a turnkey recovery system so every missed call becomes a logged, texted-back lead within seconds — no technical setup required from the customer.
+
+**Ideal customers:** SMBs (plumbers, electricians, repair shops, legal, medical), marketing agencies reselling to clients, and vertical SaaS platforms needing embedded lead recovery.
+
+## Inspiration Repo vs. Production Architecture
+
+| Aspect | never-miss-a-lead-lite (LITE) | ITPP Production |
+|---|---|---|
+| Tenancy | Single business | Multi-tenant (isolated per client) |
+| Storage | Google Sheets | Postgres (schema-per-tenant or tenant-id column) |
+| Workflow | Manual n8n import (~20 min setup) | Automated provisioning, zero manual setup |
+| Auth | None (single-user n8n) | API keys + tenant-scoped access via ops portal |
+| A2P/Toll-Free | Advisory note in README | Managed compliance as a service |
+| Logging | Google Sheets row | Structured DB with API, analytics, export |
+| Deployment | Manual n8n workflow import | Containerized, orchestrated, CI/CD |
+| Pricing | Free ($0) or $47–97 one-time | Recurring SaaS tiers ($49–$299+/mo) |
+| Lead enrichment | None | Optional: email auto-confirmation, owner alert, CRM push |
+
+**Key distinction:** The inspiration repo is a single-user n8n workflow — excellent proof-of-concept but not a multi-tenant product. ITPP's version is a managed platform where onboarding a new tenant is an automated operation, not a manual 20-minute import.
+
+## MVP Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│                  Twilio                          │
+│  Missed-call webhook → HTTP POST to n8n         │
+│  SMS text-back (programmable SMS)               │
+│  A2P 10DLC / Toll-Free managed per tenant       │
+└──────────────────┬───────────────────────────────┘
+                   │
+┌──────────────────▼───────────────────────────────┐
+│                  n8n (app1)                       │
+│  Per-tenant workflow instance (or parameterized) │
+│  Webhook → Normalize lead → SMS → Log → Respond  │
+│  Optional: email confirmation, owner alert       │
+└──────────────────┬───────────────────────────────┘
+                   │
+┌──────────────────▼───────────────────────────────┐
+│              PostgreSQL (app1 or Core)            │
+│  Schema: tenants, leads, sms_log, usage          │
+│  Tenant isolation via tenant_id FK or RLS        │
+└──────────────────┬───────────────────────────────┘
+                   │
+┌──────────────────▼───────────────────────────────┐
+│          ops.itpropartner.com (Core)             │
+│  Tenant management dashboard                     │
+│  Provisioning UI, analytics, billing             │
+│  API for lead export (CSV, webhook, Zapier)      │
+└──────────────────────────────────────────────────┘
+```
+
+**Core flows:**
+1. Customer calls business → unanswered → Twilio webhook fires
+2. n8n receives webhook, looks up tenant by Twilio number
+3. n8n sends SMS text-back from business number (templated message)
+4. Lead logged to Postgres with timestamp, caller number, message, source
+5. Optional: email to lead, SMS alert to owner, push to CRM/webhook
+
+## Tenant Isolation & Provisioning
+
+### Isolation Model
+- **Database:** Single Postgres cluster, tenant isolation via `tenant_id` foreign key on all lead/sms/usage tables. Row-Level Security (RLS) available if tenant-scoped DB users are needed.
+- **Twilio:** Each tenant gets dedicated Twilio phone number(s). SMS webhooks include the `To` number, which n8n uses to resolve tenant identity.
+- **n8n:** Single parameterized workflow (not per-tenant workflow instances). `tenant_id` derived from incoming Twilio number → DB lookup → all subsequent nodes scoped.
+- **Portal:** API key authentication, tenant-scoped views (tenant sees only their leads, usage, billing).
+
+### Provisioning (New Tenant)
+1. Acquire Twilio number (local or toll-free) via Twilio API
+2. Register A2P 10DLC brand/campaign if 10DLC number; or use verified toll-free
+3. Configure Twilio number webhook → n8n production URL
+4. Insert tenant row in Postgres: `tenant_id, business_name, twilio_number, tier, sms_template, created_at`
+5. Tenant gets portal login → views leads dashboard immediately
+6. **Automation target:** Steps 1–5 in a single n8n provisioning workflow or ops portal button
+
+## A2P 10DLC / Toll-Free Compliance
+
+US carriers require business SMS registration. Two paths:
+
+| Path | Requirements | Timeline | Cost |
+|---|---|---|---|
+| **A2P 10DLC** | Twilio Brand + Campaign registration, business EIN, website | 3–7 days | ~$44 one-time brand + ~$1.50–10/mo campaign |
+| **Toll-Free Verified** | Toll-free number + verification submission (use case, opt-in flow, volume estimate) | 2–5 days | ~$2/mo per number, no campaign fees |
+
+**ITPP approach:** Managed compliance. During tenant onboarding, ITPP handles registration and verification. Compliance status tracked per tenant in Postgres. Non-compliant tenants flagged, SMS blocked until verified.
+
+**Opt-out handling:** Twilio's built-in STOP/HELP handling left ON for all numbers. No additional opt-out logic needed — Twilio filters at carrier level.
+
+## Product Tiers & Suggested Pricing
+
+| Tier | Price/mo | Included | Target |
+|---|---|---|---|
+| **Basic** | $49–79 | 1 Twilio number, SMS text-back, lead logging, portal dashboard, CSV export, up to 250 leads/mo | Solo SMB (plumber, electrician, shop) |
+| **Pro** | $129–199 | 3 Twilio numbers, Basic + email auto-confirmation, owner SMS alert, urgency routing (3 reply tiers), webhook/Zapier export, up to 1,000 leads/mo, analytics dashboard | Growing SMB, small agency (up to 3 clients) |
+| **Managed** | $299+ | 10+ Twilio numbers, Pro + agency resell panel, white-label option, priority support, custom SMS templates, CRM integration (Twenty/HubSpot), unlimited leads, SLA | Marketing agencies, multi-location businesses |
+
+**Overage:** $0.05/lead above tier limit (Basic/Pro). Twilio SMS/voice usage billed at cost or included margin.
+
+## Dependencies
+
+| Dependency | Status | Notes |
+|---|---|---|
+| Twilio account (A2P 10DLC verified) | On file | Toll-free verification submitted 2026-07-21 |
+| n8n (app1) | Live | n8n.itpropartner.com, Docker on app1 |
+| Postgres | Live | Already on app1 (n8n + LiteLLM databases) |
+| ops.itpropartner.com | Live | FastAPI on Core, extendable with new endpoints |
+| Domain DNS | SiteGround | Manual — `leads.itpropartner.com` or similar would need SiteGround panel entry |
+| Twilio numbers | Pending purchase | Acquire programmatically or via Console |
+| A2P 10DLC campaigns | Pending registration | Per-tenant or pooled campaign TBD |
+
+## Open Questions
+
+1. **Pooled vs. per-tenant A2P 10DLC campaign:** Can a single ITPP campaign (with ITPP as brand) cover all tenants, or must each tenant register their own brand? If per-tenant, Managed tier must handle this.
+2. **n8n workflow isolation:** Parameterized single workflow vs. per-tenant workflow instances. Single is simpler to maintain; per-tenant allows customization but creates sprawl.
+3. **Billing integration:** Stripe? Manual invoicing? Integrate with ops portal or standalone?
+4. **SMS cost passthrough:** Bill Twilio usage at cost or include margin? Affects tier pricing.
+5. **CRM push destinations:** Which CRMs first? Twenty (already on Core), HubSpot, GoHighLevel?
+6. **Lead enrichment:** Append caller name/location from Twilio Lookup API? Cost per lookup.
+
+## Next Steps
+
+1. **Week 1–2:** Validate Twilio A2P 10DLC brand registration for IT Pro Partner
+2. **Week 2–3:** Build single-tenant MVP (one Twilio number → one n8n workflow → Postgres)
+3. **Week 3–4:** Add tenant model + ops portal dashboard
+4. **Week 4–5:** Automated provisioning workflow (Twilio number purchase + n8n hookup)
+5. **Week 5–6:** Beta with 1–2 friendly customers, iterate on SMS templates and routing
+6. **Week 7+:** Tiers, billing, agency panel, CRM integrations
+
+## Source
+
+**Inspiration repository:** https://github.com/leegoldmd-beep/never-miss-a-lead-lite  
+**License:** MIT  
+**Author:** Lee Gold (diesel repair shop owner)  
+**Key stat:** Only 37.8% of small-business calls answered live (411 Locals study, 2016)  
+**Retrieved:** 2026-07-23