# Stats Database Schema Foundation

## Objective

Definir una base de almacenamiento simple y reutilizable para snapshots de
servidores y estadisticas iniciales, sin comprometer todavia una base de datos
productiva concreta.

## Design Principles

- naming generico reutilizable para HLL actual y futuro HLL Vietnam
- separacion entre identidad de servidor y observaciones historicas
- persistir primero solo lo necesario para reconstruir actividad basica
- dejar espacio para multiples fuentes sin acoplar el modelo a una integracion
  unica

## Proposed Core Entities

### `game_sources`

Proposito:
describir el contexto del juego o dominio de origen de los datos.

Campos principales:

- `id`
- `slug`
- `display_name`
- `provider_kind`
- `is_active`
- `created_at`
- `updated_at`

Notas:

- `slug` puede tomar valores como `current-hll` y en el futuro otros contextos
  mas cercanos a HLL Vietnam.
- Esta entidad evita incrustar el juego en cada nombre de tabla.

### `servers`

Proposito:
mantener la identidad estable de cada servidor observado.

Campos principales:

- `id`
- `game_source_id`
- `external_server_id` nullable
- `server_name`
- `region` nullable
- `first_seen_at`
- `last_seen_at`
- `created_at`
- `updated_at`

Claves y relaciones:

- primary key en `id`
- foreign key a `game_sources.id`
- unique recomendado sobre `game_source_id` + `external_server_id` cuando el
  origen entregue identificador externo fiable

Notas:

- `server_name` no debe usarse como clave unica porque puede cambiar.
- `last_seen_at` resume la ultima observacion conocida sin sustituir a los
  snapshots historicos.

### `server_snapshots`

Proposito:
registrar cada captura puntual normalizada de un servidor.

Campos principales:

- `id`
- `server_id`
- `captured_at`
- `status`
- `players`
- `max_players`
- `current_map` nullable
- `source_name`
- `raw_payload_ref` nullable
- `created_at`

Claves y relaciones:

- primary key en `id`
- foreign key a `servers.id`
- index recomendado sobre `server_id` + `captured_at`

Notas:

- `status`, `players`, `max_players` y `current_map` son la base a persistir
  desde la primera fase.
- `raw_payload_ref` queda como referencia opcional para trazabilidad futura si
  el backend decide guardar artefactos crudos fuera de esta tabla.

## Initial Statistics Layer

No es necesario persistir metricas complejas desde el inicio. La primera capa
de estadisticas puede documentarse como derivada de `server_snapshots`.

Vistas o agregaciones recomendadas para una siguiente fase:

- ultima observacion por servidor
- pico de jugadores por servidor en una ventana temporal
- numero de snapshots online por servidor
- ultima vez visto online

Si mas adelante aparecen necesidades de rendimiento o cuadros de mando
persistentes, podra anadirse una tabla de agregados sin cambiar la base del
modelo.

## What To Persist First

Persistir por snapshot:

- `server_id`
- `captured_at`
- `status`
- `players`
- `max_players`
- `current_map` cuando exista
- `source_name`

Puede derivarse despues:

- tendencias
- medias por periodo
- picos historicos
- porcentaje de disponibilidad
- rankings

## Technology Position

El repositorio todavia no fija una tecnologia de persistencia productiva. La
base del esquema debe entenderse como modelo logico compatible con el backend en
Python y trasladable despues a la opcion de almacenamiento que se valide en una
task especifica.

En esta fase no se anaden migraciones, ORM ni ficheros de base de datos.

## Open Questions For Future Tasks

- que fuente aportara un identificador externo suficientemente estable
- con que frecuencia debe capturarse un snapshot
- si conviene guardar payload crudo completo o solo referencias
- cuando merece la pena materializar agregados persistentes