commit d4b05e7a037100fe3e62f03847f6812df29a8290 Author: root Date: Mon Aug 10 09:41:36 2026 -0400 Initial proposal: ITPP SEO Audit Tool diff --git a/proposal.md b/proposal.md new file mode 100644 index 0000000..f0660da --- /dev/null +++ b/proposal.md @@ -0,0 +1,381 @@ +# ITPP SEO Audit Tool — Product Proposal + +**Status:** PROPOSED +**Date:** 2026-08-10 +**Product Type:** ITPP Toolset — Hosting Add-on +**Git Repo:** `git.itpropartner.com/ippadmin/seo-tool` + +--- + +## Executive Summary + +IT Pro Partner sells web hosting. Every hosting client launches a site with SEO problems they don't know about — missing meta tags, no sitemap, broken canonical, zero structured data. These problems cost them traffic and conversions. They don't find out until they hire an SEO consultant 6 months later, by which point they've lost thousands in potential revenue. + +The SEO Audit Tool flips this: every ITPP hosting client gets a launch-day audit, monthly monitoring, and actionable fix-it snippets. It's an automated system — not a manual checklist — that catches issues before the client notices them. + +**The competitive moat:** Bluehost, GoDaddy, SiteGround, Cloudways — none of them bundle automated SEO auditing into hosting. This is a retention tool first (clients see value every month) and a revenue add-on second ($49/mo per site). + +--- + +## Market Context + +### The Problem + +Small business websites have predictable SEO failures: +- **Missing meta descriptions** — 63% of small business sites have no meta descriptions (source: Ahrefs study of 1M domains) +- **No structured data** — under 5% of small business sites use JSON-LD +- **Missing sitemap** — a silent killer; Google can still crawl without one, but slower +- **No OG tags** — social shares look broken, reducing referral traffic +- **Dead internal links** — every site accumulates rot over time, Google penalizes this +- **No analytics/tracking** — the client has no idea if their site works + +### The Current Alternatives + +| Option | What Happens | Cost | +|--------|--------------|------| +| Hire SEO consultant | Manual audit, one-time, $500-2,000 | High, one-shot | +| Semrush / Ahrefs | Full suite, overkill for SMB | $129-449/mo | +| Screaming Frog | Desktop crawler, technical | $259/yr | +| Free tools (Google Search Console) | Fragmented, no synthesis | $0 but nobody uses them | +| **Nothing** | Site launches with problems, loses traffic | $0 upfront, costs revenue | + +**Nobody does "launch-day audit + monthly watch" for small business sites.** It's either expensive one-time consultant, expensive ongoing enterprise tooling, or nothing. The gap is the integrated hosting add-on. + +--- + +## Product Description + +### Core Features + +1. **Launch Audit** — runs automatically when a site goes live on ITPP hosting. Crawls all pages, checks: + - Meta titles and descriptions (presence, length, uniqueness) + - Heading hierarchy (H1-H6) + - OG tags and Twitter cards + - Canonical URLs + - JSON-LD structured data + - robots.txt and sitemap.xml + - Image alt text + - Internal link health + - Page load performance + - Mobile responsiveness + - SSL certificate status + +2. **Fix-It Snippets** — not just "your meta description is missing." The audit produces: + - Exact HTML to paste (per page) + - Priority-ranked fix list + - Before/after previews + - Copy-paste ready code blocks + +3. **Monthly Crawl & Trend Report** — every 30 days: + - Issues introduced vs resolved + - Score trend (0-100) per page + - New pages detected + - Broken links found + - Ranking changes (via GSC integration) + +4. **White-Label Dashboard** — hosted at `seo.itpropartner.com` (or client-branded): + - Per-site audit scores + - Issue lists with fix status + - Historical trends + - Export to PDF for client reports + +5. **Email Reports** — monthly digest per site, configurable: + - Summary score + trend arrow + - Top 3 urgent issues + - Link to full report + +### Architecture + +``` +┌─────────────────────────────────────────────────┐ +│ ITPP Hosting │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Site A │ │ Site B │ │ Site C │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ SEO Crawler (Cron Job) │ │ +│ │ • Crawls all hosting subdirectories │ │ +│ │ • Runs per-site: 5 min crawl │ │ +│ │ • Detects new/deleted pages │ │ +│ └─────────────────┬────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Audit Engine (Python) │ │ +│ │ • BeautifulSoup + lxml parsing │ │ +│ │ • 50+ checks per page │ │ +│ │ • De-dupes across pages │ │ +│ │ • Generates fix snippets │ │ +│ └─────────────────┬────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ AI Enhancement (Optional) │ │ +│ │ • DeepSeek V4 Pro via admin-ai │ │ +│ │ • Keyword opportunity analysis │ │ +│ │ • Content gap detection │ │ +│ │ • Competitor comparison │ │ +│ └─────────────────┬────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Dashboard (Flask/FastAPI) │ │ +│ │ • seo.itpropartner.com │ │ +│ │ • Per-site reports │ │ +│ │ • PDF export │ │ +│ │ • Email delivery (Mailgun/SES) │ │ +│ └──────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +### Technical Stack + +| Layer | Technology | Rationale | +|-------|-----------|-----------| +| Crawler | Python + requests + BeautifulSoup | Fast, no JS rendering needed for audit | +| Checks engine | Python library (standardized check classes) | Extensible — add new checks without touching core | +| AI layer | admin-ai (DeepSeek V4 Pro) | $0.25/audit, only for paid tier | +| Dashboard | FastAPI + HTMX | Lightweight, server-rendered, no SPA overhead | +| Database | SQLite per-site | Zero config, portable, works at scale for this use case | +| Scheduling | Systemd timers + cron | Built-in, no additional dependency | +| Email | Mailgun API | Reliable, cheap, already in ITPP stack | +| PDF | WeasyPrint | HTML → PDF with CSS, no headless browser needed | + +--- + +## Pricing & Packaging + +### Tier Structure + +| | Free (All Hosting) | Pro ($49/mo) | Agency ($149/mo) | +|---|---|---|---| +| **Launch Audit** | ✅ | ✅ | ✅ | +| **Fix-It Snippets** | ✅ | ✅ | ✅ | +| **Monthly Crawl** | ✅ | ✅ | ✅ | +| **Email Reports** | ✅ | ✅ | ✅ | +| **Dashboard Access** | ✅ | ✅ | ✅ | +| **AI Enhancement** | ❌ | ✅ | ✅ | +| **GSC Integration** | ❌ | ✅ | ✅ | +| **Sites Included** | 1 | 1 | 5 | +| **White-Label Reports** | ❌ | ❌ | ✅ | +| **PDF Export** | ❌ | ✅ | ✅ | +| **Competitor Tracking** | ❌ | ❌ | ✅ | + +### Revenue Model + +- Every ITPP hosting client gets Free tier at launch (retention) +- Conversion target: 15-20% of clients upgrade to Pro +- Agency tier: target web design agencies who host client sites with ITPP +- Annual billing: Pro = $499/yr (save 15%), Agency = $1,499/yr + +### Unit Economics (per 100 clients) + +| Metric | Value | +|--------|-------| +| Free tier cost/site/month | $0.08 (crawler + storage) | +| Pro tier cost/site/month | $0.35 (crawler + AI + GSC) | +| Agency tier cost/site/month | $0.65 (crawler + AI + multi-site) | +| Pro LTV (24 months) | $1,176 | +| Pro CAC (hosting upsell) | ~$15 (email campaign + dashboard prompt) | +| LTV:CAC | 78:1 | + +--- + +## Competitive Analysis + +### Direct Competitors (White-Label SEO Audits) + +| Tool | Pricing | Target | Gap vs ITPP | +|------|---------|--------|-------------| +| **MetricSpot** | $29-99/mo | Agencies | Not hosting-integrated; separate platform | +| **WooRank** | $79-249/mo | Agencies/enterprise | Expensive; overkill for SMB | +| **marketgoo** | $49-149/mo | Hosting add-on | Closest competitor; but partners with hosts, doesn't own the hosting | +| **SEOptimer** | $19-59/mo | SMB/agencies | Good reports, no hosting integration | +| **SiteGuru** | $29-99/mo | SMB | Technical SEO focus, no AI, limited whitespace | + +### Indirect Competitors + +| Tool | Pricing | Why Indirect | +|------|---------|-------------| +| **Semrush** | $129-449/mo | Full marketing suite; overkill for SMB owner | +| **Ahrefs** | $99-999/mo | SEO power tool; steep learning curve | +| **Screaming Frog** | $259/yr | Desktop app; technical; one-shot | +| **Google Search Console** | Free | Fragmented; no synthesis; nobody checks it | + +### Moat Analysis + +| Moat Factor | ITPP | Competitors | +|-------------|------|-------------| +| **Hosting integration** | ✅ Native — runs on our servers, no config | ❌ None (marketgoo partners but doesn't own infra) | +| **Auto-discovery** | ✅ Detects new sites and pages automatically | ❌ Manual setup or API integration required | +| **Fix-it snippets** | ✅ Exact copy-paste HTML per page | ⚠️ Some generate generic recommendations | +| **AI analysis** | ✅ admin-ai stack, cost-controlled | ⚠️ Some offer AI; pricing uncertain | +| **Price point** | ✅ Free tier → $49/mo upsell | ⚠️ $19-249/mo range | +| **Client retention** | ✅ SEO scores as monthly value proof | ❌ Standalone tools; client can cancel anytime | + +--- + +## Build Plan + +### Phase 1: Core Crawler + Audit Engine (Week 1-2) +- Python crawler that walks `/home/*/htdocs/*/` directory trees +- Page parser: BeautifulSoup + lxml +- 20 core checks: meta tags, headings, OG, canonical, structured data, images, links +- JSON output per site + +### Phase 2: Dashboard + Snippets (Week 2-3) +- FastAPI backend with SQLite per-site +- HTMX dashboard at seo.itpropartner.com +- Fix-it snippet generator (exact HTML per issue) +- Launch audit auto-trigger on new site detection + +### Phase 3: AI Layer + Email (Week 3-4) +- Optional AI enhancement using admin-ai +- Keyword gap analysis +- Competitor content analysis +- Monthly email reports via Mailgun +- PDF export (WeasyPrint) + +### Phase 4: Agency Tier + GSC (Week 4-5) +- Multi-site dashboard for agencies +- White-label branding (logo, colors, domain) +- Google Search Console API integration +- Ranking trend data +- Competitor tracking + +### Phase 5: Launch + Hosting Integration (Week 5-6) +- Auto-enable Free tier for all ITPP hosting clients +- Dashboard prompt: "Upgrade to Pro for AI analysis" +- Client onboarding email sequence +- Documentation and KB articles + +--- + +## Risk Assessment + +| Risk | Likelihood | Impact | Mitigation | +|------|-----------|--------|------------| +| Low conversion to Pro | Medium | High | Make Free tier genuinely useful; prompt upgrade at pain points | +| AI cost overrun | Low | Medium | Rate limit AI analysis; cost per audit is <$0.25 | +| Competitor entry | Medium | Low | Hosting integration is hard to replicate without owning the servers | +| Google algorithm changes | Low | Low | Checks are standards-based (schema.org, W3C); adapt checks, not architecture | +| Crawler load on servers | Low | Low | Run off-peak; rate-limit; incremental only | + +--- + +## Git Repository Structure + +``` +seo-tool/ +├── README.md +├── proposal.md +├── architecture.md +├── LICENSE +├── src/ +│ ├── crawler/ +│ │ ├── __init__.py +│ │ ├── site_discovery.py # Walk hosting directories +│ │ ├── page_fetcher.py # HTTP fetch + local file read +│ │ └── sitemap_parser.py # Sitemap XML parsing +│ ├── checks/ +│ │ ├── __init__.py +│ │ ├── base.py # Abstract check class +│ │ ├── meta_tags.py # Title, description, robots +│ │ ├── headings.py # H1-H6 hierarchy +│ │ ├── social.py # OG, Twitter cards +│ │ ├── structured_data.py # JSON-LD, schema.org +│ │ ├── seo_files.py # robots.txt, sitemap.xml +│ │ ├── images.py # Alt text, dimensions +│ │ ├── links.py # Internal links, broken links +│ │ └── performance.py # Page size, load time +│ ├── engine/ +│ │ ├── __init__.py +│ │ ├── auditor.py # Run all checks, produce report +│ │ ├── scorer.py # 0-100 scoring algorithm +│ │ └── snippet_gen.py # Fix-it HTML generator +│ ├── ai/ +│ │ ├── __init__.py +│ │ ├── keyword_analysis.py # Keyword opportunities via admin-ai +│ │ ├── content_gap.py # Content gap detection +│ │ └── competitor.py # Competitor page analysis +│ ├── dashboard/ +│ │ ├── __init__.py +│ │ ├── app.py # FastAPI application +│ │ ├── templates/ # HTMX templates +│ │ ├── static/ # CSS, JS +│ │ └── pdf.py # WeasyPrint PDF export +│ ├── integrations/ +│ │ ├── __init__.py +│ │ ├── gsc.py # Google Search Console API +│ │ └── mailgun.py # Email delivery +│ └── cli.py # Command-line interface +├── config/ +│ ├── checks.yaml # Enabled checks + thresholds +│ └── scoring.yaml # Scoring weights +├── tests/ +│ ├── test_crawler.py +│ ├── test_checks.py +│ ├── test_engine.py +│ └── fixtures/ # Sample HTML pages +├── docs/ +│ ├── api.md +│ ├── checks-reference.md +│ └── deployment.md +└── cron/ + ├── launch-audit.sh # Triggered on site creation + ├── monthly-crawl.sh # Monthly scheduled audit + └── weekly-cleanup.sh # Rotate old reports +``` + +--- + +## Financial Projections + +### 12-Month Revenue Ramp + +| Quarter | Hosting Clients | Pro Conversions | Agency Conversions | MRR | +|---------|----------------|-----------------|-------------------|-----| +| Q1 | 20 | 2 (10%) | 0 | $98 | +| Q2 | 30 | 5 (17%) | 1 | $394 | +| Q3 | 45 | 8 (18%) | 2 | $690 | +| Q4 | 60 | 12 (20%) | 3 | $1,035 | + +**Y1 total revenue:** ~$6,600 +**Y1 cost:** ~$1,200 (AI, Mailgun, negligible computing) +**Y1 net:** ~$5,400 + +### 3-Year Projection + +| Year | Clients | Pro (20%) | Agency (5%) | ARR | Net | +|------|---------|-----------|-------------|-----|-----| +| Y1 | 60 | 12 | 3 | $12,420 | ~$5,400 | +| Y2 | 120 | 24 | 6 | $24,840 | ~$18,000 | +| Y3 | 200 | 40 | 10 | $41,400 | ~$33,000 | + +--- + +## The Ask + +| Resource | Need | +|----------|------| +| Dev time | ~40 hours total (5-6 weeks part-time) | +| AI costs | ~$5-10/month during development (testing) | +| Mailgun | Already in ITPP stack ($0 incremental) | +| Domain | seo.itpropartner.com (subdomain, $0) | +| Git repo | Create on git.itpropartner.com | + +--- + +## Next Steps + +1. Create `git.itpropartner.com/ippadmin/seo-tool` repo +2. Build Phase 1 (crawler + check engine) — 2 weeks +3. Deploy dashboard stub at seo.itpropartner.com +4. Run pilot audit on modelortho.com (validation) +5. Launch Free tier for all ITPP hosting clients + +--- + +*ITPP SEO Audit Tool — A product of IT Pro Partner*