Files

ajaysi e54aaa7a3e chore: bulk commit of local changes across blog writer, SEO dashboard, scheduler, docs-site, and frontend

2026-06-05 12:40:30 +05:30

18 KiB

Raw Blame History

GSC Strategy Insights Service - SEO Dashboard Integration Guide

Date: May 27, 2026
Phase: SEO Dashboard Integration (Post-Blog Writer)
Status: ✅ Core Service & API Endpoints Complete

📚 Overview

The GSC Strategy Insights Service adapts the GSC Brainstorm technology for SEO Dashboard use cases. While Blog Writer focuses on "What should I blog about?", the dashboard focuses on "What's my overall SEO status and what should I prioritize?"

Key Difference from Blog Writer

Aspect	Blog Writer (GSCBrainstormService)	SEO Dashboard (GSCStrategyInsightsService)
Question	"What blog post should I write?"	"What should I prioritize for SEO?"
Context	Content creation focus	Strategic monitoring focus
Time Horizon	Next post (0-2 weeks)	Ongoing (3-12 months)
Audience	Writers	SEO managers, strategists
Primary Output	5 categories of suggestions	ROI-ranked opportunities + health metrics
Integration	Modal in Blog Writer	Dashboard panels & widgets
Refresh	On-demand	Automated (hourly/daily)

🏗️ Architecture

Service Layer

File: backend/services/seo_tools/gsc_strategy_insights_service.py

Main Class: GSCStrategyInsightsService

Key Methods:

get_dashboard_strategy(user_id, site_url, ...)
- Main entry point for dashboard
- Orchestrates all analysis tasks
- Returns: Comprehensive strategy data
_get_ranked_opportunities(site_url, top_n)
- Returns ROI-weighted ranked opportunities
- Uses formula: 40% traffic + 30% ease + 20% competitive + 10% momentum
- Severity levels: CRITICAL, HIGH, MEDIUM, LOW, WATCH
_calculate_health_metrics(site_url)
- Health score (0-100)
- Position distribution
- CTR benchmarking
- Growth indicators
_generate_quick_summary(site_url)
- Text summary for dashboard display
- Key metric highlights
- One-liner insights
_analyze_performance_trends(site_url) [Phase 2]
- Historical trend analysis
- Seasonal pattern detection
- Momentum scoring
_analyze_competitive_positioning(site_url) [Phase 2]
- Competitor keyword analysis
- Market gap identification
- Competitive benchmarks

API Layer

File: backend/routers/seo_tools.py

New Endpoints:

1. `POST /api/seo/gsc/strategy-insights`

Request:
{
  "site_url": "https://example.com",
  "include_trends": true,
  "include_competitive": false,
  "top_n": 20
}

Response:
{
  "status": "success",
  "data": {
    "opportunities": [...],
    "health_metrics": {...},
    "quick_summary": "..."
  }
}

Purpose: Get comprehensive dashboard strategy

2. `POST /api/seo/gsc/opportunity-ranking`

Request:
{
  "site_url": "https://example.com",
  "ranking_metric": "roi_score",
  "severity_filter": "critical",
  "limit": 20
}

Response:
{
  "status": "success",
  "data": {
    "opportunities": [
      {
        "type": "quick_win",
        "keyword": "Python async",
        "roi_score": 87.5,
        "priority": 1,
        "effort_hours": 2,
        "timeline_weeks": 1,
        "severity": "critical",
        ...
      }
    ],
    "total_opportunities": 45
  }
}

Purpose: Get ROI-ranked opportunities (filterable by severity/metric)

3. `POST /api/seo/gsc/health-metrics`

Request:
{
  "site_url": "https://example.com",
  "include_distribution": true,
  "include_trends": true
}

Response:
{
  "status": "success",
  "data": {
    "health_score": 68,
    "health_trend": "stable",
    "total_keywords": 250,
    "page_1_keywords": 145,
    "avg_position": 7.2,
    "avg_ctr": 2.8,
    "ctr_vs_benchmark": -0.3,
    ...
  }
}

Purpose: Get health metrics for dashboard widget

4. `POST /api/seo/gsc/trend-analysis`

Request:
{
  "site_url": "https://example.com",
  "metric": "all",
  "days_back": 90
}

Response:
{
  "status": "pending",
  "message": "Trend analysis requires historical data collection",
  "note": "To be implemented in Phase 2"
}

Purpose: Analyze performance trends (Phase 2 feature)

📊 Data Models

Request Models

class GSCStrategyInsightsRequest(BaseModel):
    site_url: HttpUrl
    include_trends: bool = True
    include_competitive: bool = False
    top_n: int = 20  # 5-100

class GSCOpportunityRankingRequest(BaseModel):
    site_url: HttpUrl
    ranking_metric: str = "roi_score"  # roi_score/effort/impact/timeline
    severity_filter: Optional[str] = None  # critical/high/medium/low/watch
    limit: int = 20  # 5-100

class GSCHealthMetricsRequest(BaseModel):
    site_url: HttpUrl
    include_distribution: bool = True
    include_trends: bool = True

class GSCTrendAnalysisRequest(BaseModel):
    site_url: HttpUrl
    metric: str = "all"  # position/impressions/clicks/ctr/all
    days_back: int = 90  # 7-365

Response Models

@dataclass
class StrategyOpportunity:
    type: StrategyType  # quick_win, keyword_gap, content_opportunity, etc.
    keyword: str
    description: str
    roi_score: float  # 0-100
    priority: int  # 1-10
    effort_hours: float
    timeline_weeks: int
    current_position: float
    impressions: int
    current_ctr: float
    estimated_impact: float  # Monthly clicks gained
    severity: OpportunitySeverity  # CRITICAL, HIGH, MEDIUM, LOW, WATCH
    recommendations: List[str]
    related_keywords: List[str]
    timestamp: datetime

@dataclass
class HealthMetrics:
    health_score: int  # 0-100
    score_trend: str  # up/down/stable
    score_change: float  # Percentage
    total_keywords: int
    page_1_keywords: int
    avg_position: float
    avg_ctr: float
    total_impressions: int
    total_clicks: int
    opportunities_count: int
    timestamp: datetime

🎯 ROI Scoring Formula

ROI_Score = 0.40 × traffic_impact + 
            0.30 × ease_of_implementation + 
            0.20 × competitive_advantage + 
            0.10 × momentum_score

where:
  traffic_impact = (estimated_clicks_gained / max_possible) × 100
  ease_of_implementation = 100 × (inverse of effort hours)
  competitive_advantage = keyword relevance to market gaps
  momentum_score = current_trend direction and acceleration

Severity Levels

Severity	ROI Score	Priority	Timeline
CRITICAL	80-100	1-2 (immediate)	0-2 weeks
HIGH	60-79	3-4 (high)	1-4 weeks
MEDIUM	40-59	5-6 (medium)	2-8 weeks
LOW	20-39	7-8 (low)	1-3 months
WATCH	<20	9-10 (monitoring)	3+ months

🔌 Frontend Integration

Hook: `useGSCStrategyInsights()`

const {
  // State
  strategyInsights,
  healthMetrics,
  opportunities,
  isLoading,
  error,
  
  // Methods
  fetchStrategyInsights,
  fetchOpportunities,
  fetchHealthMetrics,
  refetchInsights,
  
  // Helpers
  getOpportunitiesBySeverity,
  filterByMetric,
  calculateROI,
} = useGSCStrategyInsights({
  siteUrl: 'https://example.com',
  autoRefresh: true,
  refreshInterval: 3600000, // 1 hour
});

Components

1. StrategyInsightsPanel

<StrategyInsightsPanel
  opportunities={opportunities}
  healthMetrics={healthMetrics}
  onOpportunityClick={(opp) => navigateToDetails(opp)}
  isLoading={isLoading}
/>

2. HealthMetricsWidget

<HealthMetricsWidget
  score={healthMetrics.health_score}
  trend={healthMetrics.score_trend}
  keywords={{
    total: healthMetrics.total_keywords,
    page1: healthMetrics.page_1_keywords,
  }}
/>

3. OpportunitiesList

<OpportunitiesList
  opportunities={opportunities}
  ranking="roi_score"
  filterBySeverity="critical"
  onSelectOpportunity={(opp) => showDetails(opp)}
/>

4. TrendChart

<TrendChart
  metric="position"
  data={trendData}
  timeRange={90}
  onPeriodSelect={(period) => updateChart(period)}
/>

📈 Dashboard Layout

SEO Dashboard - GSC Insights Tab

┌─────────────────────────────────────────────────────────────────┐
│ GSC Strategy Insights                      🔄 Refresh | ⚙️ Filter │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│ ┌──────────────────────┬──────────────────────┬─────────────────┐ │
│ │ Health Score         │ Opportunities        │ Top Keywords    │ │
│ │                      │ CRITICAL: 3          │ 1. Python async │ │
│ │   68/100            │ HIGH: 7              │ 2. FastAPI      │ │
│ │   ↓ 5% (was 73)     │ MEDIUM: 12           │ 3. Async/await  │ │
│ │                      │ LOW: 8               │ 4. LLM tutorial │ │
│ └──────────────────────┴──────────────────────┴─────────────────┘ │
│                                                                   │
│ ┌─────────────────────────────────────────────────────────────┐  │
│ │ Quick Wins (Positions 4-10) - Click to expand            │  │
│ ├─────────────────────────────────────────────────────────────┤  │
│ │ 🔴 CRITICAL - Python productivity tools (Pos 7)          │  │
│ │    ROI: 87 | Effort: 2h | Impact: +45/mo                 │  │
│ │    → Update title & meta description                      │  │
│ │                                                           │  │
│ │ 🔴 CRITICAL - FastAPI tutorial (Pos 6)                    │  │
│ │    ROI: 84 | Effort: 3h | Impact: +32/mo                │  │
│ │    → Improve content depth                                │  │
│ │                                                           │  │
│ │ 🟠 HIGH - JavaScript promises (Pos 5)                    │  │
│ │    ROI: 72 | Effort: 4h | Impact: +28/mo                 │  │
│ │    → Enhance examples and explanations                    │  │
│ └─────────────────────────────────────────────────────────────┘  │
│                                                                   │
│ ┌─────────────────────────────────────────────────────────────┐  │
│ │ Keyword Gaps (Positions 11-20) - Click to expand         │  │
│ ├─────────────────────────────────────────────────────────────┤  │
│ │ 🟠 HIGH - Machine learning basics (Pos 15)               │  │
│ │    ROI: 76 | Effort: 12h | Impact: +120/mo               │  │
│ │    → Create comprehensive beginner's guide                │  │
│ │                                                           │  │
│ │ 🟡 MEDIUM - Python concurrency (Pos 18)                  │  │
│ │    ROI: 58 | Effort: 20h | Impact: +85/mo                │  │
│ │    → Build topical authority                              │  │
│ └─────────────────────────────────────────────────────────────┘  │
│                                                                   │
│ ┌─────────────────────────────────────────────────────────────┐  │
│ │ Performance Trend (Last 90 days) [Phase 2]               │  │
│ │ [Chart: Position trend, Impressions, Clicks, CTR]        │  │
│ └─────────────────────────────────────────────────────────────┘  │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Color Coding

🔴 CRITICAL (80-100 ROI): Red, highest priority
🟠 HIGH (60-79 ROI): Orange, important
🟡 MEDIUM (40-59 ROI): Yellow, should do
🟢 LOW (20-39 ROI): Green, nice to have
⚪ WATCH (<20 ROI): Gray, monitoring

🔄 Data Flow

User Opens SEO Dashboard (GSC Insights Tab)
  ↓
useGSCStrategyInsights() Hook
  ↓
POST /api/seo/gsc/strategy-insights
  ↓
GSCStrategyInsightsService.get_dashboard_strategy()
  ├─ GSCBrainstormService.brainstorm_topics() [reuse existing]
  ├─ _get_ranked_opportunities() [ROI ranking]
  ├─ _calculate_health_metrics() [Health score]
  └─ _generate_quick_summary() [Text summary]
  ↓
Response with:
  - Ranked opportunities
  - Health metrics
  - Quick summary
  ↓
Frontend Components Update:
  - StrategyInsightsPanel
  - HealthMetricsWidget
  - OpportunitiesList
  ↓
User selects opportunity or filters
  ↓
Frontend state updates or new API call

✅ Implementation Status

Phase 1: Core Service ✅ COMPLETE

GSCStrategyInsightsService class
ROI scoring formula
Opportunity ranking
Health metrics calculation
Service initialization & error handling
API endpoint integration
Request/response models

Phase 2: Frontend (This Sprint)

useGSCStrategyInsights() hook
StrategyInsightsPanel component
HealthMetricsWidget component
OpportunitiesList component
TrendChart component (Phase 2B)
Mobile responsive views
Integration with SEO Dashboard tabs

Phase 3: Advanced Features (Future)

Trend analysis with historical data
Competitive positioning analysis
Impact forecasting
Smart alerts & notifications
Export functionality
Scheduled reports

🧪 Testing

Unit Tests

# Test ROI scoring formula
def test_roi_score_calculation():
    service = GSCStrategyInsightsService()
    roi = service._calculate_roi_score(
        traffic_impact=80,
        ease=70,
        competitive=60,
        momentum=50
    )
    assert 0 <= roi <= 100
    assert roi == expected_value

# Test severity classification
def test_severity_classification():
    assert service._get_severity(85) == OpportunitySeverity.CRITICAL
    assert service._get_severity(70) == OpportunitySeverity.HIGH
    assert service._get_severity(50) == OpportunitySeverity.MEDIUM
    assert service._get_severity(25) == OpportunitySeverity.LOW
    assert service._get_severity(10) == OpportunitySeverity.WATCH

Integration Tests

# Test full strategy insights flow
async def test_get_dashboard_strategy():
    service = GSCStrategyInsightsService()
    result = await service.get_dashboard_strategy(
        user_id="test_user",
        site_url="https://example.com",
        top_n=20
    )
    assert result['status'] == 'success'
    assert 'opportunities' in result['data']
    assert 'health_metrics' in result['data']

API Tests

# Test endpoint
def test_strategy_insights_endpoint(client):
    response = client.post(
        "/api/seo/gsc/strategy-insights",
        json={"site_url": "https://example.com"}
    )
    assert response.status_code == 200
    assert response.json()['success'] == True

📋 API Reference

Endpoints Summary

Endpoint	Method	Purpose	Response Time
`/gsc/strategy-insights`	POST	Dashboard strategy	4-8s
`/gsc/opportunity-ranking`	POST	ROI-ranked opportunities	4-8s
`/gsc/health-metrics`	POST	Health metrics	2-4s
`/gsc/trend-analysis`	POST	Trend analysis (Phase 2)	3-6s

Error Responses

{
  "success": false,
  "message": "Error in get_gsc_strategy_insights: ...",
  "error_type": "ValueError",
  "error_details": "Site URL not valid",
  "timestamp": "2026-05-27T10:30:45.123Z"
}

🎓 Usage Examples

Example 1: Get Strategy Insights

curl -X POST http://localhost:8000/api/seo/gsc/strategy-insights \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://example.com",
    "include_trends": true,
    "top_n": 20
  }'

Example 2: Filter Critical Opportunities

curl -X POST http://localhost:8000/api/seo/gsc/opportunity-ranking \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://example.com",
    "severity_filter": "critical",
    "limit": 10
  }'

Example 3: Get Health Metrics

curl -X POST http://localhost:8000/api/seo/gsc/health-metrics \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://example.com",
    "include_distribution": true
  }'

🚀 Deployment Checklist

Service class created
API endpoints implemented
Request/response models defined
Frontend hook created
Frontend components built
Integration tests written
Documentation complete
Performance tested
Error handling verified
Deployed to staging
User acceptance testing
Deployed to production

📞 Support & Questions

Service Location: backend/services/seo_tools/gsc_strategy_insights_service.py
Router Location: backend/routers/seo_tools.py
Documentation: [This file]

Status: ✅ Core Implementation Complete
Next Step: Frontend Hook & Components Development

18 KiB Raw Blame History Unescape Escape