Initial SEO-INTEL documentation: architecture, scoring, code structure
Add comprehensive documentation for the dual-engine performance evaluation system: - System architecture and data flow - Score calculation methodology (0-100 approximation from CWV thresholds) - Detailed metrics reference (LCP, FCP, CLS, TBT, TTFB) - Testing engines comparison (Sitespeed vs PSI) - Complete code structure map (file-by-file breakdown) - Case study: rds.ink 77 score with actionable fixes - Quick reference guides for interpreting results Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
160
README.md
Normal file
160
README.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user