This document explains the functional behavior of the Hellcats MVP application from both a regular user perspective and an administrator perspective.
The documentation is intentionally explicit. Every visible action, button, rule, and scoring decision is described so the system remains transparent and predictable for all participants.
The application tracks a set of participants (persons). Over time, events are recorded. Each event represents one session of play (or one evaluation period) and includes placements for up to ten participants.
Based on accumulated event placements and balancing rules, the system proposes a “Next MVP” candidate. The system is designed to be transparent and deterministic: if two users look at the app at the same time, they should see the same state and the same computed result.
Each person contains the following fields and meaning:
The goal is balancing and fairness. Average placement reflects performance, MVP count prevents one person from dominating repeatedly, cooldown forces rotation, title allows manual balancing, and blocked is a strict exclusion mechanism for special cases.
The “Add Person” section creates a new participant. The person starts with:
The “Title” action toggles the title flag. When enabled, a fixed penalty is applied to the person’s MVP score. This is a balancing tool. It allows you to reduce the probability of selecting the same person repeatedly, even if they consistently perform well.
The “Block” action toggles the blocked flag. When blocked, the person is excluded from MVP selection regardless of performance. This is stronger than cooldown or title penalty.
Removing a person deletes the participant from the state. This also removes their historical placements and MVP count. Use this carefully because it is not reversible unless you restore from backup or undo (if the removal was part of a restored state).
An event represents one session. The interface provides ten placement slots (Place 1 to Place 10). You select participants for each slot. Each participant can appear only once in the top ten for that event.
Participants not selected in the top ten automatically receive a default placement value of 15. This ensures that all persons get a placement for every event, which is required for meaningful averages.
The default value is intentionally not extreme. It represents “outside the top ten” performance without being infinite or undefined. The numeric choice can be adjusted later if your group’s event size changes.
Cooldown is a fairness mechanism. After a person receives MVP, their cooldown counter is set to the configured MVP cooldown value. While cooldownLeft is greater than zero, the person is not eligible for MVP selection.
The cooldown value is configured globally and applies to everyone equally.
Cooldown decreases when MVP is awarded (not automatically per event). Each time an MVP is given, every person with cooldownLeft > 0 is decremented by 1. The newly awarded person then receives cooldownLeft = mvpCooldown.
Clicking the “MVP” button on a person applies two effects:
This makes MVP assignment a discrete event that updates the fairness state of the whole system.
When calculating the next MVP candidate, the system filters out ineligible participants:
If no eligible persons remain, the result is “Not enough eligible persons”.
The score formula is intentionally simple and interpretable. It combines performance (average placement) and fairness (MVP history and title penalty).
avgPlace = sum(placements.place) / count(placements)
score =
(20 - avgPlace) * 3
+ (10 - mvpCount)
if title:
score -= TITLE_PENALTYInterpretation:
For a given state document, the score computation is purely functional: the same input always yields the same output. No randomness is involved.
Admin mode enables operations that can overwrite or erase data. For safety, these operations are disabled for regular users and require admin unlock.
Admin mode is session-based: unlocking admin affects only your browser session and does not grant privileges globally to all users.
Export creates a JSON file containing the entire state of the application. It is the recommended method to preserve a snapshot before major changes.
Import replaces the entire state with the contents of the uploaded JSON file. This can be used to restore from backup or migrate data.
Import is restricted to admin mode. Before import is applied, the system automatically stores an undo snapshot.
Reset clears the entire system state (persons, events, cooldown). It is intended for season restarts or complete reinitialization.
Reset is restricted to admin mode. Before reset is applied, the system automatically stores an undo snapshot.
Undo restores the system state to exactly what it was before the last import or reset. It does not merge changes; it simply overwrites the shared state with the stored snapshot.