---
id: TASK-190-design-weekly-monthly-ranking-snapshots
title: Design weekly monthly ranking snapshots
status: done
type: documentation
team: Arquitecto de Base de Datos
supporting_teams:
  - Backend Senior
  - PM
roadmap_item: foundation
priority: high
---

# TASK-190 - Design weekly monthly ranking snapshots

## Goal

Design a weekly/monthly ranking snapshot read model, equivalent in philosophy to the annual snapshot model, so public ranking requests do not depend on expensive runtime aggregation.

## Context

Annual ranking already follows a snapshot-backed read path, but weekly/monthly public ranking still depends on runtime aggregation over materialized match stats. HLL Vietnam needs a documented snapshot model for weekly and monthly ranking windows that preserves the current RCON-first policy, keeps annual behavior intact and defines a controlled fallback strategy during transition.

Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.

## Steps

1. Read the listed files first.
2. Use the performance audit and the annual snapshot runbook as reference points.
3. Define the proposed tables, keys, metadata and item payload needed for weekly/monthly ranking snapshots.
4. Define refresh cadence and lifecycle rules for current and closed windows.
5. Define the public fallback policy without reintroducing heavy recomputation on every request.

## Files to Read First

- `AGENTS.md`
- `ai/repo-context.md`
- `ai/architecture-index.md`
- `docs/ranking-stats-performance-audit.md`
- `docs/global-ranking-page-plan.md`
- `docs/annual-ranking-snapshot-runbook.md`
- `backend/app/rcon_historical_leaderboards.py`
- `backend/app/rcon_annual_rankings.py`

## Expected Files to Modify

- `docs/ranking-snapshot-read-model-plan.md`
- `ai/tasks/done/TASK-190-design-weekly-monthly-ranking-snapshots.md`

## Constraints

- Documentación-only.
- No modificar backend.
- No modificar frontend.
- No crear migraciones.
- No implementar snapshots todavía.
- No reactivar Elo/MMR.
- No reintroducir Comunidad Hispana #03.
- Mantener el diseño alineado con Python backend y con el snapshot anual existente.

## Validation

Before completing the task ensure:

- the plan defines `ranking_snapshots`
- the plan defines `ranking_snapshot_items`
- the model covers:
  - `timeframe` weekly/monthly/annual
  - `server_id`
  - `metric`
  - `window_start` and `window_end`
  - `generated_at`
  - `source`
  - `snapshot_status`
  - `item_count`
  - `limit_size`
  - `ranking_position`
  - `player_id`
  - `player_name`
  - `metric_value`
  - `matches_considered`
  - `kills`
  - `deaths`
  - `teamkills`
  - `kd_ratio`
  - `kills_per_match`
- the refresh policy is explicit:
  - weekly current every 5-15 minutes
  - monthly current every 15-30 minutes
  - previous week/month closed and stable
  - annual manual or daily
- the fallback policy is explicit:
  - serve snapshot if present
  - return controlled missing or use runtime fallback only by configuration if missing
  - never recalculate by default on every public request
- the plan names impacted endpoints and expected response metadata
- `git diff --name-only` stays within scope

## Outcome

- Snapshot design documented in `docs/ranking-snapshot-read-model-plan.md`.
- Proposed read model uses:
  - `ranking_snapshots`
  - `ranking_snapshot_items`
- The plan explicitly covers:
  - `timeframe` weekly/monthly/annual
  - `server_id`
  - `metric`
  - `window_start`
  - `window_end`
  - `generated_at`
  - `source`
  - `snapshot_status`
  - `item_count`
  - `limit_size`
  - per-item ranking and player fields
- Refresh policy defined:
  - weekly current every `5` to `15` minutes
  - monthly current every `15` to `30` minutes
  - previous week/month stable once closed
  - annual manual or daily
- Fallback policy defined:
  - serve snapshot when `ready`
  - return controlled `missing` or use runtime fallback only by configuration when snapshot is absent
  - never recalculate by default on every public request
- Transition notes prepared for `TASK-191`:
  - weekly/monthly snapshot-first read path
  - annual remains on the existing annual snapshot implementation until a dedicated migration task consolidates storage

## Change Budget

- Prefer fewer than 5 modified files.
- Prefer changes under 200 lines when feasible.
- Split the work into follow-up tasks if limits are exceeded.