Tool Listing & Ranking Strategy

rankScore Formula

The score is a weighted sum of engagement signals plus editorial bonuses and a time-decay recency boost. Computed in computeRankScore() inside src/tools/tool.service.ts.

Signal Weights Explained

Editorial Badge Bonuses

These are flat point bonuses added to the score. All three flags are admin-only — set via PATCH /api/tools/:id/status. They give the editorial team a lever to boost quality tools independent of engagement volume.

Recency Decay

A brand-new tool has no views, no clicks, no upvotes. Without a boost it would always sink to the bottom of every listing. The recency term gives every tool a head start that fades naturally:

The decay is continuous — it is recomputed on every call to updateRankScore(), meaning a tool's score naturally drops over time even with no new engagement events, as long as some engagement event triggers the next recompute. A completely inactive tool (no clicks, no new upvotes, nothing) will not have its score updated. Run the admin backfill endpoint periodically if you want stale scores refreshed.

When rankScore Updates

There is no cron job. rankScore is updated event-driven — every action that changes an input signal triggers a recompute. Two update modes are used:

Featured Section

The featured section uses the same GET /api/tools/featured endpoint as before, but the ordering changed. Previously it used a raw SQL join to rank by Plan.order (subscription tier). Now it orders by rankScore DESC, publishedAt DESC:

Auto-Rotate — What It Means & How It Would Work

Why not just always show all featured tools? At 3–5 featured tools it doesn't matter. At 15–30 it becomes a wall. Rotation keeps scarcity (which maintains the value of the featured badge) without the admin having to log in every week to manually swap tools in and out.

Cold Start (New Tools)

A newly published tool has upvoteCount = 0, clickCount = 0, viewCount = 0, rating = 0, reviewCount = 0. Without intervention it would always be at the bottom. Two mechanisms prevent this:

1. Recency boost (up to +30 points) — applied automatically in the formula for all tools based on publishedAt. On the day of publish: ~30 pts. Decays to near-zero over ~30 days. This gives every new tool a temporary lift above older tools with similar (low) engagement.
2. Initial rankScore on createTool() — updateRankScore() is called immediately after creation. So the tool enters the DB with a non-zero score (recency boost + any editorial badges if set) rather than defaulting to 0.

Backfill & Recovery

The rankScore column was added in migration 0009_add_rank_score.sql. All existing tools default to 0 until recalculated. The admin backfill endpoint handles this:

Also use this endpoint after changing the formula weights in computeRankScore() — existing stored scores reflect the old weights and need to be refreshed.

KV Cache Strategy

Because rankScore is pre-computed and written to the DB on each engagement event, list pages can be cached aggressively. The cached result is the sorted list — not a live DB query on every request.

Cache invalidation uses a version key pattern: a single tools:v integer in KV. Every tool write increments it. All list cache keys embed the current version (tools:list:{version}:{query}), so bumping the version orphans all prior cache entries without needing pattern-based key deletion (which KV does not support). Orphaned entries expire naturally via their TTL.

Frequently Asked Questions

Common questions about how rankScore behaves, answered with exact numbers so there is no ambiguity.

Three components contribute to the score even when all engagement stats are zero:

Example breakdown — tool with featured=true, verified=true, trending=false, published 17 days ago, all engagement at 0:

This is correct behaviour. Editorial badges are a deliberate head-start for curated tools. A featured + verified tool with no engagement still outranks an uncurated tool with a handful of views, which is exactly the intent. Engagement will grow and eventually overtake the fixed badge bonuses.

There is no hard ceiling. The formula is intentionally unbounded upward so that organic engagement eventually always wins over editorial curation. Badges give a bootstrapping advantage, not a permanent ceiling.

Yes — but only when updateRankScore() is triggered by an engagement event. The recency decay term (30 / (days + 1)) is recomputed every time the score is written. A completely inactive tool (no clicks, no upvotes, nothing) will not have its score recalculated automatically; the score stays frozen at whatever it was last written. Use POST /api/tools/admin/recalculate-rankings to force a refresh of all stale scores.

Decision Summary