feat: Brainstorm Topics with GSC + Issue #518 fixes + Blog Editor enhancements
Issue #518 - Subscription not updating after checkout: - Fix stale closure in SubscriptionContext checkout polling (use subscriptionRef) - Move checkout success polling from InitialRouteHandler into SubscriptionContext - Remove redundant polling code from InitialRouteHandler - Fix plan label: 'Free' instead of 'No Plan', proper capitalization - Add plan refresh button in UserBadge - Add 'View Costing Details' to UserBadge dropdown - Rename 'ALwrity Podcast Maker' to 'Podcast Creator' across UI - Clean subscription=success URL param after verification Blog Writer WYSIWYG Editor enhancements: - Per-section preview toggle (view/edit icons) - Enhanced hover-based toolbar - Circular SVG progress stats bar with detailed tooltip - Research tool chips in stats bar footer - Per-section TTS with useTextToSpeech hook (browser native) - Full blog preview modal with print/PDF support - PlayAllTTSButton: sequential playback with progress bar - OnThisPageNav: floating sidebar with scroll tracking - Section data attributes for scroll anchoring GSC Brainstorm Topics feature: - Backend: gsc_brainstorm_service.py (rule-based + LLM recommendations) - Backend: POST /gsc/brainstorm endpoint with 3-word minimum validation - Frontend: gscBrainstorm.ts API client - Frontend: useGSCBrainstormConnection hook (popup OAuth, no /onboarding redirect) - Frontend: useGSCBrainstorm hook (connect check + brainstorm call) - Frontend: GSCBrainstormModal (3-tab results: Opportunities, Gaps, AI Recs) - Frontend: BrainstormButton (visible at 3+ words, GSC connect overlay) - Wire BrainstormButton into ManualResearchForm and ResearchAction - Add blog_writer to gsc_auth router features for ALWRITY_ENABLED_FEATURES
This commit is contained in:
ajaysi
582
docs/SEO/MIGRATION_DETAILED_GAPS.md
Normal file
582
docs/SEO/MIGRATION_DETAILED_GAPS.md
Normal file
@@ -0,0 +1,582 @@
|
||||
# SEO Tools Migration: Detailed Implementation Gaps & Action Items
|
||||
|
||||
**Document Created**: May 19, 2026
|
||||
**Status**: Phase 2 Expansion Plan
|
||||
**Owner**: Development Team
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ HIGHEST PRIORITY: Enterprise SEO Suite Orchestration
|
||||
|
||||
### Current State
|
||||
- ✅ Basic service framework exists
|
||||
- ❌ Orchestration logic NOT implemented
|
||||
- ❌ Multi-tool workflow NOT functioning
|
||||
- ❌ Comprehensive audit NOT integrated
|
||||
|
||||
### Legacy Features That Need Implementation
|
||||
|
||||
```python
|
||||
# From enterprise_seo_suite.py - execute_complete_seo_audit()
|
||||
Phase 1: Technical SEO Audit
|
||||
Phase 2: Content Gap Analysis
|
||||
Phase 3: On-Page Optimization
|
||||
Phase 4: Performance Analysis
|
||||
Phase 5: Competitive Intelligence
|
||||
Phase 6: Strategic Recommendations with priority scoring
|
||||
Phase 7: Executive Summary generation
|
||||
```
|
||||
|
||||
### Specific Gaps
|
||||
|
||||
#### Gap 1: Multi-Tool Orchestration
|
||||
**Missing Logic**:
|
||||
- Sequential execution of 8 SEO services
|
||||
- Intelligent result aggregation
|
||||
- Cross-tool data correlation
|
||||
- Dependency management
|
||||
|
||||
**Implementation Needed**:
|
||||
```python
|
||||
# backend/services/seo_tools/enterprise_seo_service.py needs:
|
||||
|
||||
async def _run_technical_audit(website_url: str) -> Dict
|
||||
async def _run_content_analysis(website_url: str, competitors: List[str]) -> Dict
|
||||
async def _run_on_page_analysis(website_url: str) -> Dict
|
||||
async def _run_performance_analysis(website_url: str) -> Dict
|
||||
async def _run_competitive_analysis(website_url: str, competitors: List[str]) -> Dict
|
||||
|
||||
# Then aggregate all results with:
|
||||
_aggregate_audit_results(all_results) -> Dict
|
||||
_generate_priority_action_plan(aggregated_results) -> List[Action]
|
||||
_create_executive_summary(results) -> Dict
|
||||
```
|
||||
|
||||
#### Gap 2: Intelligent Recommendation Ranking
|
||||
**Missing Logic**:
|
||||
- Priority scoring for recommendations
|
||||
- Impact/effort matrix
|
||||
- Quick wins identification
|
||||
- Strategic initiatives classification
|
||||
|
||||
**Implementation Needed**:
|
||||
```python
|
||||
# Score each recommendation by:
|
||||
- Business impact (0-100)
|
||||
- Implementation difficulty (0-100)
|
||||
- Timeline (days)
|
||||
- Expected traffic improvement (%)
|
||||
- Resources required
|
||||
- Risk level
|
||||
```
|
||||
|
||||
#### Gap 3: Executive Reporting
|
||||
**Missing Features**:
|
||||
- Overall audit score (0-100)
|
||||
- Health status summary
|
||||
- Top issues breakdown
|
||||
- Action plan timeline
|
||||
- ROI projections
|
||||
- Implementation roadmap
|
||||
|
||||
**Implementation Needed**:
|
||||
```python
|
||||
class ExecutiveAuditReport:
|
||||
overall_score: int # 0-100
|
||||
health_status: str # Excellent/Good/Fair/Poor
|
||||
critical_issues: List[Dict] # Must fix immediately
|
||||
warnings: List[Dict] # Should fix soon
|
||||
recommendations: List[Dict] # Nice to have
|
||||
priority_actions: List[Dict] # Prioritized by impact
|
||||
estimated_timeline: str # Implementation timeframe
|
||||
estimated_traffic_gain: str # 20-50% improvement
|
||||
resource_requirements: Dict # Team, budget, tools
|
||||
```
|
||||
|
||||
**Estimated Effort**: 4-5 days
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ HIGH PRIORITY: Advanced GSC Integration
|
||||
|
||||
### Current State
|
||||
- ✅ Basic GSC connection exists
|
||||
- ✅ Raw data retrieval works
|
||||
- ❌ Advanced analysis NOT implemented
|
||||
- ❌ Content opportunity engine MISSING
|
||||
- ❌ Search intelligence workflows MISSING
|
||||
|
||||
### Legacy Features That Need Implementation
|
||||
|
||||
```python
|
||||
# From google_search_console_integration.py - analyze_search_performance()
|
||||
- Performance Overview Analysis
|
||||
- Keyword Performance Analysis
|
||||
- Page Performance Analysis
|
||||
- Content Opportunities Engine
|
||||
- Technical SEO Signals Analysis
|
||||
- Competitive Position Analysis
|
||||
- AI-Powered Recommendations
|
||||
```
|
||||
|
||||
### Specific Gaps
|
||||
|
||||
#### Gap 1: Comprehensive GSC Analyzer Service
|
||||
**Missing**: `backend/services/seo_tools/gsc_analyzer_service.py`
|
||||
|
||||
**Methods Needed**:
|
||||
```python
|
||||
class GSCAnalyzerService:
|
||||
|
||||
async def analyze_performance_overview(
|
||||
self, gsc_data: Dict, date_range: int = 90
|
||||
) -> Dict:
|
||||
# Overall metrics: clicks, impressions, CTR, avg position
|
||||
# Trend analysis: week-over-week, month-over-month
|
||||
# Performance breakdown by query, page, country, device
|
||||
|
||||
async def analyze_keyword_performance(
|
||||
self, gsc_data: Dict
|
||||
) -> Dict:
|
||||
# Keywords by impressions, clicks, CTR, position
|
||||
# High-impression/low-CTR keywords (meta optimization opportunities)
|
||||
# High-position keywords (page one candidates)
|
||||
# Low-position keywords (content improvement targets)
|
||||
|
||||
async def identify_content_opportunities(
|
||||
self, gsc_data: Dict, target_keywords: List[str] = None
|
||||
) -> List[Dict]:
|
||||
# CTR optimization: Position 2-10, high impressions
|
||||
# Position improvement: Position 11-20, boost to page 1
|
||||
# Content gaps: No data for target keywords
|
||||
# Trend analysis: Rising keywords, emerging trends
|
||||
# Scoring: 0-100 opportunity score
|
||||
|
||||
async def analyze_technical_seo_signals(
|
||||
self, gsc_data: Dict
|
||||
) -> Dict:
|
||||
# Mobile usability issues
|
||||
# Indexing problems
|
||||
# Crawl errors
|
||||
# AMP/mobile-first signals
|
||||
|
||||
async def analyze_competitive_position(
|
||||
self, gsc_data: Dict, competitors: List[str] = None
|
||||
) -> Dict:
|
||||
# Market positioning insights
|
||||
# Keyword share comparison
|
||||
# Ranking gaps vs competitors
|
||||
# Differentiation opportunities
|
||||
|
||||
async def generate_ai_recommendations(
|
||||
self, analysis_results: Dict
|
||||
) -> List[Dict]:
|
||||
# Prioritized action items
|
||||
# Expected impact estimation
|
||||
# Implementation recommendations
|
||||
# Timeline suggestions
|
||||
```
|
||||
|
||||
#### Gap 2: Content Opportunity Engine
|
||||
**Missing Logic**:
|
||||
- Identify high-volume/low-CTR keywords for meta description optimization
|
||||
- Find keywords ranking 11-20 for position improvement
|
||||
- Detect content gaps (queries with no ranking pages)
|
||||
- Analyze emerging trends
|
||||
|
||||
**Keywords from Legacy**:
|
||||
```python
|
||||
# High-impact opportunities scoring:
|
||||
- Impressions: volume metric
|
||||
- CTR: current performance
|
||||
- Position: improvement potential
|
||||
- Click value: estimated traffic gain
|
||||
- Difficulty: implementation complexity
|
||||
|
||||
# Opportunity Score Formula (0-100):
|
||||
# High impressions + Low CTR + High position = High opportunity
|
||||
# Would benefit most from meta description update
|
||||
```
|
||||
|
||||
#### Gap 3: Search Intelligence Workflows
|
||||
**Missing Workflows**:
|
||||
1. **CTR Optimization Workflow**
|
||||
- Find keywords with high impressions but low CTR
|
||||
- Recommend meta description updates
|
||||
- Track improvements
|
||||
|
||||
2. **Position Improvement Workflow**
|
||||
- Find keywords in positions 11-20
|
||||
- Recommend content enhancements
|
||||
- Track ranking changes
|
||||
|
||||
3. **Content Gap Analysis Workflow**
|
||||
- Identify target keywords with no ranking pages
|
||||
- Recommend new content creation
|
||||
- Plan content strategy
|
||||
|
||||
**Estimated Effort**: 5-7 days
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ MEDIUM PRIORITY: Schema/Structured Data Generator
|
||||
|
||||
### Current State
|
||||
- ❌ Not migrated
|
||||
- ✅ Legacy implementation complete
|
||||
|
||||
### Legacy Features to Migrate
|
||||
|
||||
```python
|
||||
# From seo_structured_data.py
|
||||
Support for schema types:
|
||||
- Article schema
|
||||
- Product schema
|
||||
- Recipe schema
|
||||
- Event schema
|
||||
- LocalBusiness schema
|
||||
- (expandable for others)
|
||||
```
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
#### Service Creation: `schema_markup_service.py`
|
||||
|
||||
```python
|
||||
class SchemaMarkupService:
|
||||
|
||||
async def generate_schema_markup(
|
||||
self,
|
||||
content_type: str, # Article, Product, Recipe, Event, LocalBusiness
|
||||
content_data: Dict[str, Any],
|
||||
page_url: str,
|
||||
enhance_with_ai: bool = True
|
||||
) -> Dict[str, Any]:
|
||||
# Generate structured data (JSON-LD)
|
||||
# Include all required and recommended fields
|
||||
# Add AI enhancements if requested
|
||||
# Return both JSON-LD script and validation results
|
||||
|
||||
async def validate_schema_markup(
|
||||
self, schema_data: Dict
|
||||
) -> Dict:
|
||||
# Validate against schema.org specifications
|
||||
# Check required fields
|
||||
# Recommend improvements
|
||||
# Check for common errors
|
||||
|
||||
async def enhance_schema_with_ai(
|
||||
self, schema_data: Dict, page_content: str
|
||||
) -> Dict:
|
||||
# Use AI to enhance schema completeness
|
||||
# Extract additional relevant data
|
||||
# Ensure accuracy and completeness
|
||||
```
|
||||
|
||||
#### Supported Schema Types
|
||||
1. **Article Schema**
|
||||
- headline, description, image, author, datePublished, dateModified
|
||||
|
||||
2. **Product Schema**
|
||||
- name, description, image, brand, price, rating, availability
|
||||
|
||||
3. **Recipe Schema**
|
||||
- name, description, image, prepTime, cookTime, totalTime, recipeYield, recipeIngredient, recipeInstructions
|
||||
|
||||
4. **Event Schema**
|
||||
- name, description, startDate, endDate, location, url
|
||||
|
||||
5. **LocalBusiness Schema**
|
||||
- name, description, address, telephone, url, image, priceRange
|
||||
|
||||
#### API Endpoint Needed
|
||||
```
|
||||
POST /api/seo/schema-markup
|
||||
Request:
|
||||
{
|
||||
"content_type": "Article",
|
||||
"content_data": {...},
|
||||
"page_url": "https://example.com/article",
|
||||
"enhance_with_ai": true
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"success": true,
|
||||
"schema_type": "Article",
|
||||
"json_ld": {...},
|
||||
"html_script": "<script>...</script>",
|
||||
"validation_results": {...},
|
||||
"ai_enhancements": {...}
|
||||
}
|
||||
```
|
||||
|
||||
**Estimated Effort**: 2-3 days
|
||||
|
||||
---
|
||||
|
||||
## 4️⃣ MEDIUM PRIORITY: Text Readability Integration
|
||||
|
||||
### Current State
|
||||
- ❌ Not migrated as separate tool
|
||||
- ✅ Should integrate into OnPageSEOService
|
||||
|
||||
### Legacy Features to Integrate
|
||||
|
||||
```python
|
||||
# From textstaty.py - 9 readability metrics
|
||||
- Flesch Reading Ease (0-100)
|
||||
- Flesch-Kincaid Grade Level
|
||||
- Gunning Fog Index
|
||||
- SMOG Index
|
||||
- Automated Readability Index
|
||||
- Coleman-Liau Index
|
||||
- Linsear Write Formula
|
||||
- Dale-Chall Readability Score
|
||||
- Readability Consensus
|
||||
```
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
#### Enhance OnPageSEOService
|
||||
|
||||
**Add to existing service**:
|
||||
```python
|
||||
class OnPageSEOService:
|
||||
|
||||
async def analyze_content_readability(
|
||||
self, page_content: str
|
||||
) -> Dict[str, Any]:
|
||||
# Calculate all 9 readability metrics
|
||||
# Provide overall readability score
|
||||
# Compare to target audience level
|
||||
# Recommend improvements
|
||||
|
||||
return {
|
||||
"flesch_reading_ease": 65, # 0-100: higher = easier
|
||||
"grade_level": 8.5, # US school grade level
|
||||
"readability_consensus": "Easy to read",
|
||||
"recommendations": [
|
||||
"Shorter sentences recommended",
|
||||
"Simplify technical terms",
|
||||
"Increase paragraph breaks"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Response Model
|
||||
|
||||
```python
|
||||
# In OnPageSEOAnalysisResponse:
|
||||
content_analysis: Dict # Add:
|
||||
├── word_count
|
||||
├── sentence_count
|
||||
├── average_word_length
|
||||
├── readability_metrics
|
||||
│ ├── flesch_reading_ease
|
||||
│ ├── grade_level
|
||||
│ ├── consensus
|
||||
│ └── recommendations
|
||||
└── quality_score (incorporate readability)
|
||||
```
|
||||
|
||||
#### Scoring Integration
|
||||
- Add readability score to overall content quality
|
||||
- Weight readability 15% of content quality score
|
||||
- Provide specific recommendations
|
||||
|
||||
**Estimated Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
## 5️⃣ LOW PRIORITY: Image Optimization Service
|
||||
|
||||
### Current State
|
||||
- ❌ Not migrated
|
||||
- ✅ Legacy implementation uses Tinify API
|
||||
|
||||
### Legacy Features to Migrate
|
||||
|
||||
```python
|
||||
# From optimize_images_for_upload.py
|
||||
- Image compression (Tinify)
|
||||
- Quality optimization
|
||||
- Format conversion (WebP)
|
||||
- Batch processing
|
||||
- EXIF preservation
|
||||
- Dimension resizing
|
||||
```
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
#### Service Creation: `image_optimization_service.py`
|
||||
|
||||
```python
|
||||
class ImageOptimizationService:
|
||||
|
||||
async def optimize_image(
|
||||
self,
|
||||
image_file: UploadFile,
|
||||
quality: int = 45,
|
||||
format: str = "auto", # jpg, png, webp, auto
|
||||
resize: Optional[Tuple[int, int]] = None,
|
||||
preserve_exif: bool = False
|
||||
) -> Dict[str, Any]:
|
||||
# Compress image
|
||||
# Convert format if needed
|
||||
# Return before/after stats
|
||||
|
||||
async def batch_optimize_images(
|
||||
self,
|
||||
image_files: List[UploadFile],
|
||||
quality: int = 45,
|
||||
format: str = "auto"
|
||||
) -> List[Dict[str, Any]]:
|
||||
# Process multiple images
|
||||
# Return optimization statistics
|
||||
|
||||
async def convert_to_webp(
|
||||
self, image_file: UploadFile
|
||||
) -> bytes:
|
||||
# Convert to modern WebP format
|
||||
# Better compression than JPEG/PNG
|
||||
```
|
||||
|
||||
#### API Endpoints Needed
|
||||
```
|
||||
POST /api/seo/optimize-image (single)
|
||||
POST /api/seo/optimize-images (batch)
|
||||
```
|
||||
|
||||
#### Dependencies
|
||||
- PIL/Pillow for image processing
|
||||
- Tinify SDK for compression (optional paid API)
|
||||
- Alternative: ImageMagick, ffmpeg
|
||||
|
||||
**Note**: Not critical path. Can use simpler image processing if Tinify not available.
|
||||
|
||||
**Estimated Effort**: 2-3 days
|
||||
|
||||
---
|
||||
|
||||
## Summary: Implementation Roadmap
|
||||
|
||||
### Week 1-2: Phase 2A (HIGH PRIORITY)
|
||||
- [ ] Day 1-2: Enterprise SEO Suite orchestration
|
||||
- [ ] Day 3-5: Advanced GSC Integration
|
||||
- [ ] Day 6-7: Testing & integration
|
||||
|
||||
### Week 3: Phase 2B (MEDIUM PRIORITY)
|
||||
- [ ] Day 1-2: Schema Markup Service
|
||||
- [ ] Day 3: Text Readability Integration
|
||||
- [ ] Day 4-5: Testing & documentation
|
||||
|
||||
### Week 4+: Phase 2C (LOW PRIORITY)
|
||||
- [ ] Optional: Image Optimization Service
|
||||
- [ ] Optional: Additional schema types
|
||||
- [ ] Optional: Performance optimizations
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Files Needing Creation/Modification
|
||||
|
||||
### Services to Create
|
||||
```
|
||||
backend/services/seo_tools/
|
||||
├── gsc_analyzer_service.py (NEW - HIGH PRIORITY)
|
||||
├── schema_markup_service.py (NEW - MEDIUM PRIORITY)
|
||||
└── image_optimization_service.py (NEW - LOW PRIORITY)
|
||||
```
|
||||
|
||||
### Services to Enhance
|
||||
```
|
||||
backend/services/seo_tools/
|
||||
├── enterprise_seo_service.py (MAJOR CHANGES - HIGH PRIORITY)
|
||||
└── on_page_seo_service.py (ADD READABILITY - MEDIUM PRIORITY)
|
||||
```
|
||||
|
||||
### API Routes to Update
|
||||
```
|
||||
backend/routers/seo_tools.py
|
||||
├── POST /api/seo/schema-markup (NEW)
|
||||
├── POST /api/seo/optimize-image (NEW)
|
||||
└── Existing endpoints (update enterprise workflow)
|
||||
```
|
||||
|
||||
### Database Models (if needed)
|
||||
```
|
||||
Models to add:
|
||||
- SchemaMarkupAnalysis
|
||||
- ImageOptimization
|
||||
- GSCAnalysis (detailed)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Enterprise Suite Testing
|
||||
- [ ] All 8 tools execute correctly in sequence
|
||||
- [ ] Results aggregate properly
|
||||
- [ ] Priority scoring works as expected
|
||||
- [ ] Executive summary generates correctly
|
||||
- [ ] Timing is acceptable (< 5 min for full audit)
|
||||
|
||||
### GSC Integration Testing
|
||||
- [ ] Connects to GSC API
|
||||
- [ ] Retrieves data correctly
|
||||
- [ ] Analyzes performance accurately
|
||||
- [ ] Identifies opportunities properly
|
||||
- [ ] Generates recommendations
|
||||
|
||||
### Schema Testing
|
||||
- [ ] Schema validates against schema.org
|
||||
- [ ] All field types supported
|
||||
- [ ] HTML output correct
|
||||
- [ ] AI enhancement works
|
||||
|
||||
### Readability Testing
|
||||
- [ ] All 9 metrics calculate correctly
|
||||
- [ ] Grade level accurate
|
||||
- [ ] Recommendations useful
|
||||
- [ ] Integration with on-page score works
|
||||
|
||||
### Image Testing
|
||||
- [ ] Compression effective
|
||||
- [ ] Format conversion works
|
||||
- [ ] Quality settings work
|
||||
- [ ] Batch processing functional
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Enterprise Suite ✅
|
||||
- Single endpoint for complete audit
|
||||
- Results from all 8 tools integrated
|
||||
- Actionable recommendations prioritized
|
||||
- Estimated timeline provided
|
||||
|
||||
### GSC Integration ✅
|
||||
- Advanced analytics on GSC data
|
||||
- Content opportunities identified
|
||||
- Search intelligence provided
|
||||
- Competitive analysis included
|
||||
|
||||
### Schema Markup ✅
|
||||
- 5+ schema types supported
|
||||
- Valid JSON-LD generation
|
||||
- Easy integration to pages
|
||||
- AI enhancement available
|
||||
|
||||
### Readability ✅
|
||||
- Integrated into on-page analysis
|
||||
- 9 metrics calculated
|
||||
- Grade level accurate
|
||||
- Useful recommendations provided
|
||||
|
||||
### Image Optimization ✅
|
||||
- Effective compression
|
||||
- Multiple format support
|
||||
- Before/after statistics
|
||||
- Batch processing available
|
||||
Reference in New Issue
Block a user