Clean up README and organize documentation

2026-10-06 23:51:41 -04:00
parent 75b6a0a783
commit 8fcabe27fc
38 changed files with 687 additions and 1249 deletions
@@ -0,0 +1,46 @@
+# Leaderboard query benchmark
+
+The benchmark and measurements below describe the earlier SQL optimization,
+before the worker and revision caches were added. They are historical results,
+not measurements of the current HTTP implementation.
+
+Run the deterministic, isolated benchmark with:
+
+```sh
+node scripts/benchmark-leaderboard.mjs --scenario all --baseline-ref eac9ad4 --runs 3 --json /tmp/leaderboard-benchmark.json
+```
+
+The script creates temporary SQLite databases, loads the actual query modules,
+checks complete-response parity against the selected Git revision, and reports
+timings, source hashes and query plans. It never opens the application database.
+The small fixture has 2,000 matches and 8,000 participation rows; the large fixture
+has 50,000 matches and 200,000 participation rows. Both include completed,
+active, interrupted and nonqualifying records.
+
+On the local Intel i5-8279U / Node 25.9.0 / SQLite 3.49.2 test environment, three
+measured runs after warmup gave these median query times on the large fixture:
+
+| Request | Before | After |
+| --- | ---: | ---: |
+| Highest round, all games | 1,717 ms | 829 ms |
+| Total kills, all games | 1,555 ms | 858 ms |
+| One game | 899 ms | 491 ms |
+| One map | 345 ms | 224 ms |
+| Player search | 1,515 ms | 757 ms |
+| Deep page | 1,421 ms | 752 ms |
+| Headshot percentage | 1,444 ms | 760 ms |
+| Exact player rank | 1,524 ms | 554 ms |
+
+The small fixture's unfiltered request fell from 41 to 30 ms. All 150 additional
+small-fixture parity cases and 22 timed small/large request cases matched the
+baseline's complete responses, including ratios and record evidence. Timings
+include SQL preparation and evidence lookup, exclude HTTP/browser rendering, and
+use a warm filesystem cache with alternating implementation order. These are
+local synthetic measurements, not production latency guarantees. SQL queries
+run synchronously within the report worker; larger histories still affect
+report latency and worker capacity.
+
+Validation for that optimization passed 1,019 unit tests, Svelte checking with no errors
+or warnings, and a production build. Isolated Firefox walkthroughs at 1440px and
+390px checked completed-only totals, record links, efficiency qualification,
+scoped ranks/history, preserved navigation, empty scopes and mobile expansion.