# 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](docs/01-architecture.md)** — Data flow, engines, database schema
- **[Score Calculation](docs/02-score-calculation.md)** — How the 0-100 performance score is derived
- **[Performance Metrics Reference](docs/03-metrics-reference.md)** — What each CWV metric means and thresholds
- **[Testing Engines](docs/04-testing-engines.md)** — Sitespeed vs PSI detailed comparison

### Code References
- **[Code Structure Map](code-refs/file-structure.md)** — Every file and what it does
- **[Database Schema](code-refs/database-schema.md)** — Four tables, all fields, relationships
- **[API Endpoints](code-refs/api-endpoints.md)** — HTTP routes and payloads
- **[Configuration & Thresholds](code-refs/thresholds.md)** — Hard-coded scoring rules

### Guides & Troubleshooting
- **[How to Interpret a Score](guides/interpreting-scores.md)** — Why is my page 77? What do I fix?
- **[Testing Workflow](guides/testing-workflow.md)** — Click-by-click guide through a test run
- **[Diagrams](diagrams/)** — Visual architecture, data flow, scoring algorithm

### Case Studies
- **[Case: rds.ink/drawings-of-endangered-animals-series/ = 77](case-studies/rds-77-score.md)** — 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](guides/interpreting-scores.md)** and the **[Case Study](case-studies/rds-77-score.md)**. You'll learn what each number means and how to explain fixes to clients.

### I'm a Developer
Read **[System Architecture](docs/01-architecture.md)**, then dive into **[Code Structure](code-refs/file-structure.md)** and **[Database Schema](code-refs/database-schema.md)**. Everything you need to modify the system is there.

### I'm a DevOps Engineer
Check **[Testing Engines](docs/04-testing-engines.md)** (Docker setup), **[API Endpoints](code-refs/api-endpoints.md)** (how to trigger tests), and **[Configuration](code-refs/thresholds.md)** (what to tune).

### I Just Want to Fix My Site's Score
Go straight to **[How to Interpret a Score](guides/interpreting-scores.md)** 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