Internal Service — This is not an HTTP endpoint. It’s called by the ranking-score route.
Purpose
Generates 4 fake competitor scores that are displayed alongside the user’s score. Creates the impression of a competitive landscape.
Function Signature
def generate_competitor_scores(user_score: int) -> List[int]
Parameters
| Parameter | Type | Description |
|---|
user_score | int | The user’s ranking score |
Returns
List[int] - 4 competitor scores, sorted descending (highest first)
Rules
| Rule | Description |
|---|
| Ranking | 50% chance user ranks 5th (all 4 higher), 50% chance user ranks 4th |
| Max score | No score exceeds 86 |
| Uniqueness | All scores must be unique |
| Close competitor | One competitor is always within 2-4 points of user |
Example Output
For a user score of 38:
{
"score": 38,
"competitor_scores": [72, 65, 58, 42]
}
Why This Design?
- Close competitor - Shows the user they’re “almost” beating someone
- Higher scores - Creates urgency (“competitors are ahead”)
- Sorted descending - Easy to display as a leaderboard
- Randomized ranking - Some users rank 4th (hope), some rank 5th (urgency)
Code Location
src/website/ranking_score/routes.py
# Lines 49-129: generate_competitor_scores()
