seo-intel-docs/README.md

SEO-INTEL Performance Evaluation System

Complete technical documentation for the dual-engine performance measurement platform running at http://192.168.0.117:8765/performance/.

Overview

SEO-INTEL is a custom-built performance evaluation system that measures web page speed across your portfolio using two independent engines:

• Sitespeed.io — Real browser testing with HAR waterfall capture
• Google PageSpeed Insights — Official Lighthouse audits

This repo documents how the system works, how scores are calculated, what each component does, and how to interpret results.

Quick Navigation

Understanding the System

• System Architecture — Data flow, engines, database schema
• Score Calculation — How the 0-100 performance score is derived
• Performance Metrics Reference — What each CWV metric means and thresholds
• Testing Engines — Sitespeed vs PSI detailed comparison

Code References

• Code Structure Map — Every file and what it does
• Database Schema — Four tables, all fields, relationships
• API Endpoints — HTTP routes and payloads
• Configuration & Thresholds — Hard-coded scoring rules

Guides & Troubleshooting

• How to Interpret a Score — Why is my page 77? What do I fix?
• Testing Workflow — Click-by-click guide through a test run
• Diagrams — Visual architecture, data flow, scoring algorithm

Case Studies

• Case: rds.ink/drawings-of-endangered-animals-series/ = 77 — Real example with actionable fixes

Key Facts

Aspect	Detail
UI Location	http://192.168.0.117:8765/performance/
Code Location	/home/help4bis/seo-intel/
Database	SQLite at seo-intel/data/seo-intel.db
Test Engines	Sitespeed.io (Docker v40.4.0) + Google PSI API
Score Range	0–100 (approximated from CWV thresholds)
Testing Latency	~90s per URL (sitespeed 60s + PSI 30s)
Portfolio Coverage	13 sites, ~6 URLs each, tested weekly
Tables	perf_runs, perf_audits, perf_opportunities, perf_resources

The Score Explained (TL;DR)

Your performance score is the average of five metrics, each scored 0–100:

Performance Score = Average(LCP_score, FCP_score, CLS_score, TBT_score, TTFB_score)

Where each metric is scored based on:
  ≤ Good threshold  = 100 points
  ≥ Poor threshold  = 30 points
  Between           = linear interpolation

Example: TBT of 1,807ms
  Good: 200ms  |  Poor: 600ms
  1,807 is way beyond 600 → score = 30 points ← killer metric

For Different Audiences

I'm a Performance Marketer

Start with How to Interpret a Score and the Case Study. You'll learn what each number means and how to explain fixes to clients.

I'm a Developer

Read System Architecture, then dive into Code Structure and Database Schema. Everything you need to modify the system is there.

I'm a DevOps Engineer

Check Testing Engines (Docker setup), API Endpoints (how to trigger tests), and Configuration (what to tune).

I Just Want to Fix My Site's Score

Go straight to How to Interpret a Score with your site's name. The guide will show you exactly what's slow and how to fix it using Hummingbird.

Key Insight: Two Different Scores

Score	Source	What It Measures	Use For
Sitespeed Score (77)	Approximated from CWV	Trend tracking	Internal comparisons, weekly monitoring
PSI Score (unknown)	Official Google Lighthouse	Official Google score	Client benchmarking, official audits
Individual Metrics (TBT=1,807ms)	Real browser via Browsertime	Root cause diagnosis	Finding bottlenecks, prioritising fixes

The individual metrics are most important — they tell you exactly what's broken.

Project Structure

docs/                    — Concept guides (how things work)
├── 01-architecture.md
├── 02-score-calculation.md
├── 03-metrics-reference.md
└── 04-testing-engines.md

code-refs/              — Technical reference (what the code does)
├── file-structure.md
├── database-schema.md
├── api-endpoints.md
└── thresholds.md

guides/                 — How-to guides (what to do with results)
├── interpreting-scores.md
└── testing-workflow.md

diagrams/               — Visual explanations
├── architecture-diagram.txt
├── data-flow.txt
└── scoring-algorithm.txt

case-studies/           — Real examples
└── rds-77-score.md     (why it scores 77, how to fix it)

Quick Reference: Metric Thresholds

All thresholds are hard-coded in /home/help4bis/seo-intel/src/perf/sitespeed.py lines 53–60:

LCP (Largest Contentful Paint)
  Good: ≤ 2,500ms  |  Poor: ≥ 4,000ms

FCP (First Contentful Paint)
  Good: ≤ 1,800ms  |  Poor: ≥ 3,000ms

CLS (Cumulative Layout Shift)
  Good: ≤ 0.1      |  Poor: ≥ 0.25

TBT (Total Blocking Time)
  Good: ≤ 200ms    |  Poor: ≥ 600ms   ← Most common problem

TTFB (Time to First Byte)
  Good: ≤ 800ms    |  Poor: ≥ 1,800ms

Green (✓) = score ≥ 90 | Amber (⚠️) = 50–89 | Red (❌) = < 50

Common Questions

Q: Why does my site show 77 but Google PageSpeed says 95? A: Different scoring methods. Sitespeed's 77 is approximated; PSI's 95 is official Lighthouse. The individual metrics (like TBT=1,807ms) are what matter — that's the real problem.

Q: How do I re-test a URL? A: Click "Test Now" on the performance dashboard. It queues a background job (sitespeed + PSI on mobile + desktop). Results appear after ~90 seconds when you refresh.

Q: What's the difference between Mobile and Desktop scores? A: Mobile uses 4G throttling + Moto G4 emulation. Desktop uses native connectivity + 1366x768 viewport. Your mobile score is usually lower because of network + device constraints.

Q: Can I change the thresholds? A: Yes, but they're hard-coded in src/perf/sitespeed.py. Edit those thresholds, rebuild the Docker container, and the next test will use the new values.

Q: Why does it take 90 seconds per URL? A: Sitespeed runs 3 iterations (takes ~60s), PSI takes ~30s. Both run in parallel for mobile + desktop = 4 concurrent tests.

---

Last updated: 2026-05-14 | Repository version: 1.0.0