Skip to content

planning.md

Latest commit

 

History

History
182 lines (135 loc) · 14.4 KB

planning.md

File metadata and controls

182 lines (135 loc) · 14.4 KB
Raw

BestSearch — Planning & Status

Living status board. Updated as features land.

The product goal: become the best GEO platform — sell two things tied together.

  1. Analytics — measure where a business appears across AI search engines today.
  2. GEO improvement — concrete, engine‑specific recommendations to rank higher (and eventually, done‑for‑you execution).

Status legend

  • DONE — shipped, working in the current build
  • IN PROGRESS — partially built, has visible gaps
  • TODO — not started, on the roadmap
  • IDEA — captured but not committed

Phase 1 — Core scanner (MVP)

Feature Status Notes
Multi‑engine scanner (Perplexity, OpenAI, Gemini) DONE lib/scanExecutor.ts
Query expansion (15 intent variations) DONE lib/queryExpansion.ts
Entity extraction (JSON + fallback parsers) DONE lib/entityExtractor.ts
Per‑engine leaderboards DONE app/api/scan/route.ts
Global score (rank weight + engine bonus) DONE lib/globalScoring.ts
Consensus score (mentions × engines × avg rank) DONE lib/consensusEngine.ts
Volatility / stability label DONE lib/volatility.ts
Supabase persistence + scan history DONE supabase/migrations/002
Dashboard with tabs + charts DONE app/dashboard/page.tsx
Free tier (3 scans/month) + Stripe checkout DONE lib/quota.ts, lib/stripe.ts
Auth (Supabase email/password) DONE — bypassed if env missing app/login/page.tsx

Phase 2 — Keyword Intelligence (the GEO product)

This is the differentiator. Analytics on its own is commodity — recommendations are the moat.

Feature Status Notes
md/engines.md — how each engine works + GEO levers DONE Educational anchor for buyers.
lib/keywordInsights.ts — per‑business aggregate (mentions, engine spread, avg rank, query coverage) DONE Powers the panel below.
lib/geoRecommendations.ts — explain ranking + outranking tips DONE Pure heuristics, no API calls.
Dashboard "Keyword Intelligence" panel — drilldown per business DONE Below the leaderboard tabs.
Target business input — track your own brand DONE Persists in localStorage; gap analysis surfaces.
Outranking recommendations — engine‑specific actions DONE Pulled from geoRecommendations.ts lever tables.
Login error message bug (showed "Something went wrong" for non‑Error rejections) DONE Fixed in app/login/page.tsx.

Still gaps in Phase 2

Gap Why it matters
DONE — Save target business per user in Supabase, not localStorage app/api/settings/route.ts + migration 004. Loads from Supabase on mount, debounced write on change, localStorage fallback.
DONE — "Why am I missing?" deep dive when target isn't in any leaderboard lib/missingDiagnosis.ts + WhyMissingPanel in dashboard. Per-engine root causes, leader comparison, priority action plan sorted by impact/effort.
DONE — Pull actual cited URLs from Perplexity response and surface "who's citing your competitors" lib/citationAggregator.ts + CitationIntelligencePanel. Top cited domains, gap domains (competitors cited but not you), per-brand citation breakdown. perplexity.ts now returns { content, citations[] }.
DONE — Sentiment / context of mentions, not just rank lib/sentimentParser.ts now classifies every mention positive/neutral/negative (was binary positive/negative) and extracts a context_snippet. globalScoring.ts + consensusEngine.ts + buildPerEngineLeaderboards (app/api/scan/route.ts) score neutral mentions at 60% weight, exclude negative entirely. Dashboard leaderboard shows both ⚠ neg and ◐ neutral badges.

Phase 3 — Selling GEO improvement (revenue lever)

Recommendations alone aren't enough — we want to charge for execution.

Feature Status Notes
TODO — "Done‑for‑you" tier: we run outreach to get you into target listicles Real GEO business — manual + tooling hybrid.
TODO — Wikidata / Wikipedia setup service Strongest single lever for GPT + Gemini.
TODO — Schema.org markup audit + generated snippets Concrete deliverable, easy to package.
TODO — Reddit / forum presence playbook Highest Perplexity ROI.
DONE — Tracked recommendations: "did rank improve after action X?" app/api/actions/, migration 005_tracked_actions.sql, RecommendationList component with "Mark done" toggle per rec.
DONE — Weekly digest email with rank changes + new opportunities app/api/digest/route.ts using Resend. Requires RESEND_API_KEY + RESEND_FROM_EMAIL. Call via cron (Vercel Cron or GitHub Actions).

Phase 4 — Engines & data depth

Feature Status Notes
DONE — Add Claude (Anthropic) as a 4th engine lib/engines/claude.ts using claude-haiku-4-5-20251001. Requires ANTHROPIC_API_KEY. Full GEO levers + missing diagnosis added.
DONE — Add ChatGPT search (browse mode) as a 5th engine lib/engines/chatgptSearch.ts — gpt-4o-mini + Responses API web_search tool. Returns real citation URLs like Perplexity. Reuses OPENAI_API_KEY, no new env var. Wired into dashboard engine picker as chatgpt_search.
TODO — Add Google AI Overviews scraping Where most consumers will actually see AI answers.
TODO — Authority‑weighted scoring (cite domain DA, not just engine) Better global score.
TODO — Geo‑aware scanning (auto‑expand by city / neighborhood) Local search is most of the demand.

Phase 5 — Distribution / growth

Feature Status Notes
TODO — Public "AI visibility report" landing page for sample brands SEO + lead magnet.
DONE — CSV export of scan + recommendations exportCSV() in dashboard. Includes global leaderboard, per-engine leaderboards, citation domains, citation gaps. "Export CSV" button in analytics header.
TODO — White‑label dashboard for agencies Higher ACV.
DONE — Slack alerts on rank change lib/slackAlert.ts. Fires after scan if slack_webhook_url set in user settings. Configurable in dashboard Notifications panel.
TODO — API access (charge per scan) Developer tier.

Cross‑cutting tech debt

Item Status Notes
TODO — Real test coverage on scoring functions Currently no tests. Easy wins: globalScoring, consensusEngine, keywordInsights.
DONE — Rate limiting on /api/scan beyond quota lib/rateLimit.ts — sliding window, 5 req/min per IP. Per-instance (no Redis); sufficient for burst protection.
DONE — Name normalization improvements lib/keywordInsights.ts — strips leading "The", strips common suffixes (LLC, Inc, Restaurant, Cafe, etc.) before comparison.
DONE — Cache scan results for the same query within a TTL (24h) lib/scanCache.ts — in-memory Map keyed by query::engines_sorted. Cache hit skips quota decrement. force_refresh param bypasses cache.
IDEA — Move scoring to a Postgres function / materialized view If scan history grows large.
DONE — Landing page copy audit: removed fictional feature claims + duplicate pricing bug Marketing copy advertised GA4 integration, a "Copilot" 6th engine, a "5M+ prompt library", GPTBot/Claudebot detection, and a real-time "Competitor Battlemap" — none built. Pricing.tsx also showed the identical €89/mo on both Starter and Pro. Replaced with real shipped features and dropped fabricated prices. See md/progress.md 2026-07-17 entry.
TODO — Delete orphaned lib/geo/ directory + dead top-level files lib/geo/* (6 files) is unwired leftover from an incomplete refactor — nothing outside it imports from it. Also lib/queryGenerator.ts, lib/analyze.ts, lib/scoring.ts, lib/consensus.ts are unused, superseded by their current equivalents. Flagged, not yet deleted — confirm before removing.

Phase 6 — AEO (Answer Engine Optimization) track

Competitor intelligence shows every serious GEO buyer also wants AEO. This is the next major surface to add depth on.

Feature Status Notes
TODO — Per-prompt citation share tracking (AEO) Track citation % across ChatGPT, Perplexity, Gemini, AI Overviews, Copilot for a defined prompt set Core AEO KPI — not just "did we rank" but "were we cited in the AI answer"
TODO — Prompt cluster management Define top 20–50 brand/category prompts; group by funnel stage (awareness, comparison, decision) Powers AEO dashboard
TODO — AEO content scoring on existing pages Score each page for direct-answer paragraph structure, entity density, FAQPage schema coverage Show which pages are AEO-ready vs missing
TODO — AEO-aware page recommendations When citation share drops for a prompt, surface the pages that should be serving those citations + what's wrong Close the tracker-to-optimizer gap
TODO — Sentiment classification on citations Being cited as "avoid" hurts; distinguish positive / neutral / negative citation contexts Competitor 1 has basic sentiment; Gauge AI has the best taxonomy

Phase 7 — MCP server (developer + agent tier)

Competitor 1 already has production MCP. This is the highest-leverage gap to close for developer/agency adoption.

Feature Status Notes
TODO — MCP server exposing core primitives track_visibility(), audit_brand(), get_recommendations() as LLM-readable MCP tools Works with Claude, ChatGPT agents, any MCP-compatible agent framework
TODO — Per-agent auth scoping Each agent credential limited to specific tools + rate limits; full audit log Required for enterprise/agency security
TODO — Structured error responses for agent retry Errors include context: "cache miss, retry in 5s" vs "quota exceeded, upgrade required" Not just HTTP status codes
TODO — Developer tier pricing Charge per scan via API; MCP access as paid add-on Unlocks agency and builder market
TODO — Agent workflow documentation Example: agent that monitors citation share daily + triggers content review when threshold drops Drives adoption of the MCP tier

Phase 8 — pSEO (programmatic page generation)

Lower priority than AEO + MCP but a natural expansion once the citation tracking layer is solid.

Feature Status Notes
IDEA — pSEO batch page generator Generate location/comparison/category pages at scale from structured datasets Per-page research agent model (not template substitution) to avoid HCU risk
IDEA — Schema-as-build-output FAQPage, Article, LocalBusiness generated dynamically per page during pSEO build Ensures AEO-readiness for every generated page
IDEA — IndexNow integration for generated pages Submit pages to Bing IndexNow at generation time; sitemap management Faster indexation for programmatic batches
IDEA — Near-duplicate detection Score each batch for semantic uniqueness before publishing; flag near-duplicate clusters Prevents pSEO penalties

Phase 9 — Reddit marketing (execution track)

Reddit is the single highest-weighted citation source for Perplexity (md/engines.md) and, per competitor scrapes, ~46–68% of cited sources for Perplexity/AI-answer generation broadly (md/competitor_airix.md, md/competitor_reddgrow.md). Closest reference products: md/competitor_scaloom.md (Reddit posting/warmup automation, no citation feedback loop) and md/competitor_reddgrow.md (scan → match → draft → cited loop, the shape to beat).

Feature Status Notes
IDEA — Reddit thread discovery: find threads our engines already cite for target keywords Reuses existing scan pipeline (lib/citationAggregator.ts) — filter cited URLs to reddit.com domains instead of building new scanning.
IDEA — AI-drafted, on-brand comment generation for matched threads Read the actual thread content before drafting (LinkDR/Scaloom/ReddGrow pattern) — no generic templates.
IDEA — Human-in-the-loop approval flow before posting Reddit-native audiences penalize obvious marketing; every competitor in this space (Scaloom, ReddGrow) treats one-click approval as the core trust mechanic, not optional.
IDEA — Account warmup / ban-avoidance safeguards Required if we post on the user's behalf at all — gradual karma-building, pacing limits per account.
IDEA — Subreddit discovery + match scoring Rank candidate subreddits by relevance to the brand/niche (Scaloom does this over 50k+ subreddits).
IDEA — Post-action re-scan: did the comment/post actually get cited afterward? The gap every competitor leaves open (Scaloom tracks karma/replies but never citation outcome; ReddGrow tracks citation growth but only within Reddit). Closing this loop with our existing scan pipeline is the differentiator — prove the Reddit activity moved AI visibility, not just engagement.
IDEA — Chrome extension for ad-hoc commenting outside the dashboard Lower priority; ReddGrow ships this, useful for one-off opportunistic replies.
IDEA — Community management / subreddit moderation via AI + knowledge base Further-out, retention/expansion play once a brand has its own active subreddit — not core to the citation loop.

Open product questions

These aren't bugs — they're decisions that change the shape of the product.

  • Per‑business vs per‑keyword pricing? Most GEO buyers think in "I'm a restaurant, track my brand across 50 keywords." Quota by keyword could be more natural than by scan.
  • Who is the buyer? Local SMBs (low ACV, high volume) vs marketing agencies (high ACV, demands white‑label) vs in‑house brand teams (mid ACV, demands deeper analytics). Pick one before building Phase 3.
  • How do we prove ROI? Tracked recommendations + before/after rank delta is the answer. Until we ship that, churn risk is real.
  • GEO-depth vs 4-track breadth? Competitor 1 goes broad across SEO + AEO + GEO + pSEO. We go deep on GEO. Hold the GEO depth advantage while adding AEO tracking — that's the wedge. Don't build a shallow AEO tab; build AEO that's as deep as our GEO layer.
  • MCP as paid tier or included? Developer/agency market expects API access. Charge per scan via API; bundle MCP access with Growth plan to drive adoption before monetizing separately.