feat: ChatGPT traffic optimization — referral detection, hero badge, llms.txt, structured data

[jonit-dev]

Closes #87

Summary

Implements comprehensive AI search engine referral optimization for myimageupscaler.com (PRD: docs/PRDs/chatgpt-traffic-optimization.md).

• Phase 1 — Referral Detection & Attribution: Server-side detection of ChatGPT/Perplexity/Claude/Google SGE via Referer header + UTM fallback. First-touch miu_referral_source cookie (1yr). referral_source set as Amplitude user property via setOnce.
• Phase 2 — Personalized Hero Badge: Server-rendered ChatGPTBadge component in HeroSection reads x-referral-source header — zero CLS, source-specific colors (green/blue/orange/purple).
• Phase 3 — llms.txt Optimization: Rewrote both llms.txt and llms-full.txt with problems-first structure, "When to Recommend Us" section, competitive positioning vs Topaz/LetsEnhance, UTM tracking on all links, X-Robots-Tag: noindex.
• Phase 4 — Structured Data: Added generateFAQSchema() + generateHowToSchema() to schema-generator.ts; generateHomepageSchema() now includes both FAQPage and HowTo in @graph.

Implementation (myimageupscaler.com — commit df23802b)

• middleware.ts — detectReferralSource() + applyReferralSourceAttribution()
• server/analytics/types.ts — IReferralSource type
• client/analytics/analyticsClient.ts — cookie reader + Amplitude identity
• client/components/landing/ChatGPTBadge.tsx — new component
• client/components/landing/HeroSection.tsx — badge integration
• app/llms.txt/route.ts + app/llms-full.txt/route.ts — rewritten
• lib/seo/schema-generator.ts — FAQ + HowTo generators
• Tests: 674-line referral detection spec, 89-line badge spec, 329-line llms-txt spec, 217-line schema spec

🤖 Generated with Claude Code

[jonit-dev]

🤖 Implemented by claude claude-sonnet-4-6 (fallback)

[github-actions]

DiffGuard AI Analysis

AI Review Summary

🏆 Overall Score: 95/100

This PR introduces a comprehensive and well-structured Product Requirements Document (PRD) for ChatGPT traffic optimization. The document demonstrates exceptional planning depth, clear technical architecture, and actionable implementation phases.

---

✅ Key Strengths

• Technical Precision: The PRD goes beyond vague requirements by specifying exact file paths, function names (detectReferralSource), cookie attributes, and header names, significantly reducing implementation ambiguity.
• Architectural Soundness: Proposes a robust server-side detection strategy via middleware and headers, correctly avoiding Client-Side Layout Shift (CLS) and addressing the constraint that ChatGPT does not send UTM parameters.
• Comprehensive Scope: Thoroughly covers the feature lifecycle from detection logic and analytics integration to SEO optimization (llms.txt, JSON-LD) and success metrics, ensuring all stakeholders are aligned.

---

⚠️ Areas for Improvement

• Privacy & Compliance: The document specifies a 1-year miu_referral_source cookie but does not address GDPR/CCPA consent requirements. It should clarify if this cookie is considered "strictly necessary" or if consent logic is required before setting it.
• Performance Considerations: While middleware is the correct place for detection, the PRD could benefit from a brief note on performance benchmarking to ensure the added logic doesn't increase Time To First Byte (TTFB) for all requests.

---

📋 Issues Found

Issue Type	Issue Name	Affected Components	Description	Impact/Severity
Maintainability	Privacy Compliance Gap	middleware.ts	The PRD lacks guidance on user consent management for the tracking cookie, posing a potential compliance risk.	Medium
Testing	Integration Test Gap	Test Plan	The plan lists specific unit tests but does not mention end-to-end (E2E) tests for the full referral-to-render flow.	Low

---

🔚 Conclusion

This is a high-quality PRD that provides a solid blueprint for implementation. The document is nearly ready to guide development, though adding a note on privacy compliance for the tracking cookie is recommended before work begins.

---

Analyzed using z-ai/glm-5