sistema A2S

docs/current-hll-data-ingestion-plan.md

@@ -0,0 +1,130 @@
+# Current HLL Data Ingestion Plan
+
+## Objective
+
+Definir una estrategia tecnica reutilizable para ingerir datos del Hell Let
+Loose actual como banco de pruebas del futuro ecosistema HLL Vietnam, sin
+implementar todavia una ingesta productiva completa.
+
+## Initial Data Scope
+
+Los primeros campos a capturar deben cubrir el bloque provisional de
+servidores y preparar historicos minimos:
+
+- `server_name`
+- `status`
+- `players`
+- `max_players`
+- `current_map` si la fuente lo permite
+- `captured_at`
+- `source`
+- `external_server_id` o identificador equivalente si la fuente lo ofrece
+
+Campos como `queue`, `ping`, `rotation` o `notes` quedan como opcionales para
+fases posteriores y no deben bloquear el bootstrap.
+
+## Snapshot Concept
+
+Un snapshot representa el estado observado de un servidor en un momento
+concreto. No es un perfil estatico del servidor, sino una captura puntual con
+timestamp.
+
+Cada snapshot debe permitir:
+
+- reconstruir una serie temporal simple por servidor
+- detectar cambios de estado online u offline
+- medir evolucion basica de jugadores y capacidad
+- conservar la procedencia de la captura
+
+El identificador estable del servidor y el `captured_at` deben separar la
+identidad del servidor de cada observacion historica.
+
+## Ingestion Source Options
+
+### Phase-safe controlled payload
+
+- Fuente recomendada para el inicio.
+- Permite probar el pipeline con datos mock o manuales servidos por backend.
+- Fija el contrato de entrada y la normalizacion sin depender de terceros.
+
+### Public external source
+
+- Puede ser una API publica o un listado mantenido por terceros.
+- Acerca el banco de pruebas a datos reales.
+- Exige validar formato, disponibilidad, limites de uso y estabilidad antes de
+  consolidarlo.
+
+### Direct server query or intermediary adapter
+
+- Puede ofrecer datos mas cercanos al estado real del servidor.
+- Introduce mayor complejidad tecnica, posibles timeouts y dependencia del
+  protocolo soportado.
+- Debe encapsularse detras de un adaptador backend, no exponerse al frontend.
+
+## Normalization Baseline
+
+La captura y la fuente no deben definir el contrato interno final. La
+arquitectura debe separar:
+
+1. lectura de datos crudos
+2. normalizacion a un modelo comun
+3. produccion de snapshots consistentes
+
+La normalizacion inicial debe garantizar:
+
+- naming estable en `snake_case`
+- `status` reducido a valores controlados como `online`, `offline` o `unknown`
+- enteros para `players` y `max_players` cuando existan
+- `captured_at` generado en backend
+- conservacion del nombre de fuente para trazabilidad
+
+## Risks And Limits
+
+- Disponibilidad de terceros: una fuente publica puede dejar de responder sin
+  aviso.
+- Cambios de formato: scraping o APIs no oficiales pueden romper el adaptador.
+- Rate limits: las consultas frecuentes pueden exigir cache o polling mas
+  espaciado.
+- Latencia: una consulta lenta no debe trasladarse directamente al frontend.
+- CORS: el frontend no debe llamar a fuentes externas para este flujo.
+- Fiabilidad: diferentes fuentes pueden discrepar en jugadores, mapa o estado.
+- Dependencia no oficial: una integracion fragil no debe convertirse en pieza
+  critica del producto.
+
+## Phased Architecture
+
+### Phase 1: controlled payload and stable structure
+
+- Mantener un payload controlado como base de `/api/servers`.
+- Definir el modelo normalizado esperado para servidores y snapshots.
+- No almacenar historico real todavia.
+
+### Phase 2: snapshot collector with real or near-real source
+
+- Introducir un colector backend desacoplado de la fuente concreta.
+- Permitir ejecucion manual o periodica en entorno de desarrollo.
+- Generar snapshots consistentes listos para futura persistencia.
+
+### Phase 3: historical use and basic statistics
+
+- Persistir snapshots.
+- Calcular metricas iniciales como actividad por servidor, picos de jugadores o
+  ultima vez visto online.
+- Mantener el modelo generico para reutilizarlo con HLL Vietnam cuando existan
+  datos mas representativos.
+
+## Explicitly Out Of Scope Now
+
+- ingesta real completa en produccion
+- scraping productivo
+- base de datos funcional
+- tareas periodicas operativas
+- metricas avanzadas o paneles analiticos
+- cambios visibles en frontend
+
+## Handoff To Following Tasks
+
+- `TASK-019` debe convertir este plan en una base de esquema para persistir
+  servidores y snapshots.
+- `TASK-020` debe preparar un bootstrap pequeno del colector en Python con
+  separacion entre fuente, normalizacion y snapshot.

docs/current-hll-servers-source-plan.md

@@ -0,0 +1,130 @@
+# Current HLL Servers Source Plan
+
+## Objective
+
+Definir como mostrar en la web de HLL Vietnam un bloque provisional con
+servidores actuales de Hell Let Loose sin presentarlos como si fueran datos de
+HLL Vietnam ni depender todavia de una integracion real externa.
+
+## Product Framing
+
+- El bloque debe presentarse como referencia provisional para la comunidad.
+- El copy debe mencionar de forma explicita "servidores actuales de Hell Let
+  Loose" y evitar formulas ambiguas como "servidores HLL Vietnam".
+- La UI debe dejar claro que el bloque sirve mientras no existan datos propios o
+  mas cercanos al contexto final de HLL Vietnam.
+- Si no hay datos disponibles, el estado vacio debe ser neutral y honesto, sin
+  simular actividad inexistente.
+
+## Recommended Fields For This Phase
+
+Campos utiles para un bloque pequeno y entendible:
+
+- `server_name`
+- `status`
+- `players`
+- `max_players`
+- `current_map`
+- `region`
+
+Campos opcionales solo si una fuente futura los ofrece de forma estable:
+
+- `queue`
+- `ping`
+- `notes`
+- `last_updated`
+
+## Source Options
+
+### Public external source
+
+- Puede ser una API publica especializada, un listado publico o una consulta de
+  servidor compatible con el juego actual.
+- Ventaja: acerca la web a datos mas reales.
+- Riesgo: cambios de formato, limites de uso, CORS, disponibilidad y dependencia
+  de terceros.
+
+### Controlled placeholder data
+
+- Fuente recomendada para la primera implementacion.
+- El backend expone un payload manual con forma realista y semantica estable.
+- Permite validar UI, contrato y estados de error sin acoplar la web a una
+  fuente externa todavia no validada.
+
+### Stronger future integration
+
+- Un adaptador backend dedicado podra sustituir el placeholder cuando exista una
+  fuente fiable o un dataset controlado mantenido por la comunidad.
+- La sustitucion debe preservar el contrato JSON para no romper al frontend.
+
+## Risks And Restrictions
+
+- Disponibilidad: una fuente externa puede caer o degradarse sin aviso.
+- CORS: el frontend no debe depender de llamadas directas a terceros.
+- Rate limits: una API publica puede limitar frecuencia o volumen.
+- Formato: scraping o endpoints no oficiales pueden cambiar sin contrato.
+- Mantenimiento: una integracion fragil crearia coste operativo prematuro.
+- Identidad: el bloque no puede inducir a pensar que HLL Vietnam ya dispone de
+  servidores propios o datos oficiales.
+
+## Phased Strategy
+
+### Phase 1: controlled mock
+
+- `GET /api/servers` devuelve datos manuales con estructura estable.
+- El payload debe incluir una marca de contexto provisional para indicar que los
+  datos pertenecen al HLL actual.
+- La landing puede consumir el endpoint con fallback local si el backend no esta
+  disponible.
+
+### Phase 2: backend adapter
+
+- Sustituir el mock por un adaptador backend desacoplado de la fuente concreta.
+- Mantener el mismo contrato principal de `items`.
+- Introducir validacion basica de campos y fallback controlado si falla la
+  fuente.
+
+### Phase 3: replacement toward HLL Vietnam
+
+- Reemplazar o mezclar progresivamente el bloque cuando existan datos mas
+  representativos del contexto HLL Vietnam.
+- Revisar naming, copy y campos para no arrastrar supuestos del juego actual.
+
+## Explicitly Out Of Scope Now
+
+- Integrar una fuente externa real.
+- Hacer scraping.
+- Consultar servidores reales desde el frontend.
+- Anadir base de datos, cache o panel administrativo.
+- Presentar el bloque como caracteristica definitiva del producto.
+
+## Recommended Contract Shape
+
+Ejemplo minimo de respuesta provisional:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "title": "Servidores actuales de Hell Let Loose",
+    "context": "current-hll-reference",
+    "source": "controlled-placeholder",
+    "items": [
+      {
+        "server_name": "HLL ESP Tactical Rotation",
+        "status": "online",
+        "players": 74,
+        "max_players": 100,
+        "current_map": "Sainte-Marie-du-Mont",
+        "region": "EU"
+      }
+    ]
+  }
+}
+```
+
+## Handoff To Following Tasks
+
+- Backend task: preparar el adaptador placeholder estable sobre este contrato.
+- Frontend task: anadir un panel visual sobrio con etiqueta provisional y
+  fallback seguro si el endpoint falla o no devuelve items.

docs/decisions.md

@@ -2,20 +2,84 @@
 
 ## Decision 001: frontend simple HTML/CSS/JS
 
-Se adopta una base estática con HTML, CSS y JavaScript puro para priorizar simplicidad, velocidad de arranque y compatibilidad total al abrir el frontend directamente en navegador.
+Se adopta una base estatica con HTML, CSS y JavaScript puro para priorizar simplicidad, velocidad de arranque y compatibilidad total al abrir el frontend directamente en navegador.
 
 ## Decision 002: backend previsto en Python
 
-La estructura del repositorio reserva desde el inicio una carpeta de backend porque la implementación futura se realizará en Python.
+La estructura del repositorio reserva desde el inicio una carpeta de backend porque la implementacion futura se realizara en Python.
 
-## Decision 003: estructura preparada para orquestación por agentes
+## Decision 003: estructura preparada para orquestacion por agentes
 
-Se incluye una carpeta `ai/` y un documento `AGENTS.md` para facilitar una futura organización del trabajo por roles, tareas y orquestación.
+Se incluye una carpeta `ai/` y un documento `AGENTS.md` para facilitar una futura organizacion del trabajo por roles, tareas y orquestacion.
 
 ## Decision 004: branding militar Vietnam
 
-La dirección visual inicial se alinea con una estética sobria, táctica y militar inspirada en el contexto Vietnam para mantener coherencia temática desde la primera iteración.
+La direccion visual inicial se alinea con una estetica sobria, tactica y militar inspirada en el contexto Vietnam para mantener coherencia tematica desde la primera iteracion.
 
 ## Decision 005: AI Development Platform integrada de forma adaptada
 
-Se integra una capa de orquestación por tasks inspirada en la plantilla de AI Development Platform, pero adaptada al contexto real de HLL Vietnam y sin arrastrar supuestos genéricos de otros stacks. La plataforma se usa como soporte operativo del repositorio, no como funcionalidad del producto.
+Se integra una capa de orquestacion por tasks inspirada en la plantilla de AI Development Platform, pero adaptada al contexto real de HLL Vietnam y sin arrastrar supuestos genericos de otros stacks. La plataforma se usa como soporte operativo del repositorio, no como funcionalidad del producto.
+
+## Decision 006: contrato API pequeno antes de integraciones reales
+
+Antes de implementar endpoints de comunidad o integraciones externas, se fija un contrato JSON minimo entre frontend y backend para evitar que la landing y el backend evolucionen con supuestos incompatibles.
+
+La unica ruta implementada hoy es `GET /health`. Las rutas `/api/community`, `/api/trailer`, `/api/discord` y `/api/servers` quedan definidas como contrato previsto o placeholder en `docs/frontend-backend-contract.md`, manteniendo el backend en Python y sin introducir todavia Discord real, servidores reales ni base de datos.
+
+## Decision 007: estrategia por fases para Discord y servidores
+
+Los datos de Discord y de servidores de juego se incorporaran por fases para evitar dependencias prematuras de credenciales, APIs externas o consultas de red todavia no validadas.
+
+La fase inicial debe usar datos manuales o placeholder controlados por el backend para mantener estable el contrato del frontend. Una fase intermedia podra anadir una integracion limitada con fuentes publicas o consultas tecnicas de bajo riesgo. Solo una fase posterior evaluara integraciones mas reales, siempre que queden claras las restricciones de seguridad, disponibilidad, latencia y mantenimiento.
+
+La estrategia detallada de bloques de datos, fuentes posibles, riesgos y orden recomendado de implementacion queda documentada en `docs/discord-and-server-data-plan.md`.
+
+## Decision 008: consumo frontend progresivo con fallback estatico
+
+El frontend no debe depender de datos dinamicos para renderizar la landing base mientras el proyecto siga en fase fundacional.
+
+Cuando se incorporen endpoints del backend, el consumo debe hacerse con `fetch` y JavaScript simple, priorizando bloques independientes y manteniendo contenido estatico o placeholders visuales si falla una llamada. `GET /health` queda reservado para comprobaciones tecnicas y no debe bloquear el render principal.
+
+La estrategia detallada de prioridades de endpoints, estados de carga, errores y orden de migracion queda en `docs/frontend-data-consumption-plan.md`.
+
+## Decision 009: servidores actuales de HLL como referencia provisional
+
+Mientras no existan datos reales o representativos de HLL Vietnam, la web puede
+mostrar un bloque provisional con servidores actuales de Hell Let Loose siempre
+que quede claramente etiquetado como referencia temporal.
+
+La primera version de ese bloque debe salir de un payload controlado del backend
+Python, no de una integracion directa desde frontend ni de scraping prematuro.
+Esto permite fijar campos utiles, preservar el tono del producto y evitar que la
+landing dependa de una fuente externa aun no validada.
+
+La estrategia de campos, riesgos, fases y sustitucion futura queda documentada
+en `docs/current-hll-servers-source-plan.md`.
+
+## Decision 010: ingesta por snapshots y adaptadores desacoplados
+
+La evolucion desde payloads placeholder hacia datos mas realistas debe hacerse
+con una arquitectura de snapshots de servidor, no conectando el frontend a una
+fuente externa ni acoplando el backend a una integracion unica desde el inicio.
+
+La unidad tecnica base sera un snapshot con `captured_at` y campos normalizados
+como estado, jugadores, capacidad y mapa actual cuando exista. La lectura de
+fuente, la normalizacion y la produccion del snapshot deben quedar separadas
+para poder sustituir mocks por una fuente publica o consulta tecnica posterior
+sin romper el contrato interno.
+
+La estrategia detallada de fuentes, riesgos, fases y limites queda documentada
+en `docs/current-hll-data-ingestion-plan.md`.
+
+## Decision 011: modelo de almacenamiento logico antes de fijar tecnologia
+
+Antes de introducir una base de datos concreta, el proyecto debe fijar un
+modelo logico minimo para identidad de servidores y snapshots historicos.
+
+La base inicial se apoya en entidades genericas como `game_sources`, `servers`
+y `server_snapshots`. Las metricas iniciales deben derivarse primero de esos
+snapshots en vez de materializar agregados prematuros. Esto mantiene el diseno
+reutilizable para HLL actual y para futuras fuentes mas cercanas a HLL Vietnam.
+
+El modelo base y las preguntas abiertas quedan documentados en
+`docs/stats-database-schema-foundation.md`.

docs/discord-and-server-data-plan.md

@@ -0,0 +1,119 @@
+# Discord And Server Data Plan
+
+## Objective
+
+Definir una base tecnica para exponer en la web datos de Discord y de futuros servidores de juego sin implementar todavia integraciones reales ni depender de servicios externos en esta fase.
+
+## Discord Data Candidates
+
+Bloques con sentido para la web:
+
+- `invite_url`: enlace principal para entrar en la comunidad.
+- `community_name`: nombre visible de la comunidad o del servidor.
+- `cta_label`: texto de llamada a la accion para el boton de acceso.
+- `approx_presence`: presencia aproximada o estado publico solo si existe una fuente publica fiable.
+- `public_summary`: breve descripcion publica, reglas resumidas o mensaje de bienvenida.
+
+## Game Server Data Candidates
+
+Bloques con sentido para la web:
+
+- `server_name`: nombre visible del servidor.
+- `status`: online u offline.
+- `current_map`: mapa actual si la fuente lo permite.
+- `rotation`: rotacion o proximo mapa si la fuente es estable.
+- `players`: jugadores conectados.
+- `max_players`: capacidad maxima.
+- `ping`: latencia aproximada si la consulta la devuelve.
+- `region` o `notes`: metadatos operativos simples para la comunidad.
+
+## Possible Discord Sources
+
+### Public widget
+
+- Util para obtener datos publicos basicos si el servidor lo tiene habilitado.
+- Bueno para presencia aproximada o nombre visible.
+- Limitado por la configuracion del propio servidor y por el alcance real del widget.
+
+### External API or third-party integration
+
+- Puede simplificar algunas lecturas, pero introduce dependencia de terceros, cambios de servicio y posibles limites de uso.
+- Debe considerarse solo si aporta estabilidad y evita exponer credenciales en frontend.
+
+### Own bot
+
+- Da mas control a largo plazo.
+- Exige credenciales, despliegue, permisos y operacion continua.
+- No encaja en la fase actual del repositorio.
+
+### Manual configured data
+
+- Fuente mas segura para la primera fase.
+- Sirve para `invite_url`, nombre de comunidad y textos publicos.
+- Permite validar el contrato API y el consumo frontend sin depender de Discord real.
+
+## Possible Game Server Sources
+
+### Direct server queries
+
+- Pueden dar estado, jugadores, mapa o ping segun el protocolo disponible.
+- Exigen validar compatibilidad real con el juego, frecuencia de consulta y tolerancia a timeouts.
+
+### External API
+
+- Puede simplificar el acceso si existe una fuente especializada.
+- Introduce dependencia externa, disponibilidad ajena y posible coste o rate limit.
+
+### Mock or placeholder data
+
+- Opcion recomendada para la primera fase.
+- Permite fijar formato JSON, estados y experiencia de frontend sin acoplarse a infraestructura real.
+
+### Manual updates
+
+- Util para mostrar estado controlado o informacion operativa minima mientras no exista integracion tecnica fiable.
+- Reduce riesgo en una etapa donde el backend aun es preparatorio.
+
+## Risks And Restrictions
+
+- Credenciales: bots o APIs privadas requieren secretos y una estrategia de almacenamiento segura.
+- Rate limits: Discord o terceros pueden limitar frecuencia de consulta.
+- Availability: widgets, APIs o consultas de servidor pueden fallar o cambiar sin previo aviso.
+- Security: nunca debe exponerse en frontend una credencial ni una ruta administrativa.
+- CORS: el frontend no deberia depender de llamadas directas a servicios externos si eso obliga a resolver CORS en cliente.
+- Latency: consultas en tiempo real pueden degradar la web si no se amortiguan en backend.
+- External dependency: cada integracion nueva aumenta coste operativo y puntos de fallo.
+
+## Phased Strategy
+
+### Phase 1: controlled placeholders
+
+- Backend Python devuelve datos manuales o mock para `/api/discord` y `/api/servers`.
+- La web usa esos datos solo cuando futuras tasks lo indiquen.
+- No hay consultas reales a Discord ni a servidores.
+
+### Phase 2: limited technical integration
+
+- Evaluar una unica fuente publica o consulta sencilla por dominio.
+- Mantener fallback manual si la fuente falla.
+- Introducir observabilidad minima antes de ampliar alcance.
+
+### Phase 3: real integration if justified
+
+- Considerar bot propio, polling controlado o una integracion mas rica solo si aporta valor real a la comunidad.
+- Revisar seguridad, operacion, cache y mantenimiento antes de consolidarlo.
+
+## What Is Explicitly Out Of Scope Now
+
+- Integrar Discord real.
+- Consultar servidores reales de juego.
+- Anadir base de datos.
+- Implementar autenticacion o panel administrativo.
+- Hacer llamadas directas desde el frontend a servicios externos.
+
+## Recommended Implementation Order
+
+1. Consolidar placeholders backend para `community`, `discord`, `trailer` y `servers`.
+2. Definir consumo frontend con fallbacks visuales y orden de prioridad.
+3. Validar una fuente publica o consulta tecnica pequena para Discord o servidores.
+4. Decidir si merece la pena ampliar integraciones reales.

docs/frontend-backend-contract.md

@@ -0,0 +1,250 @@
+# Frontend Backend Contract
+
+## Objetivo
+
+Definir un contrato inicial y pequeno entre la landing actual y el futuro backend Python sin implementar todavia integraciones reales ni comprometer detalles de infraestructura antes de tiempo.
+
+## Estado actual
+
+- Frontend: landing estatica sin consumo de API
+- Backend: bootstrap Python con `GET /health`
+- Integraciones reales: no implementadas
+
+## Convenciones generales
+
+- Todas las respuestas usan JSON.
+- Los nombres de campos usan `snake_case`.
+- `status` es obligatorio en todas las respuestas.
+- Las respuestas exitosas usan `status: "ok"`.
+- Las respuestas de error usan `status: "error"` y un campo `message`.
+- Cuando un endpoint sea solo placeholder o aun no tenga datos reales, puede responder datos controlados o quedar documentado como previsto hasta una task posterior.
+
+## Estructura base de respuesta
+
+Respuesta correcta:
+
+```json
+{
+  "status": "ok",
+  "data": {}
+}
+```
+
+Respuesta de error minima:
+
+```json
+{
+  "status": "error",
+  "message": "Route not found"
+}
+```
+
+## Endpoints
+
+### `GET /health`
+
+- Proposito: comprobar que el backend bootstrap esta levantado.
+- Metodo HTTP: `GET`
+- Ruta: `/health`
+- Estado actual: implementado
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "service": "hll-vietnam-backend",
+  "phase": "bootstrap"
+}
+```
+
+### `GET /api/community`
+
+- Proposito: devolver contenido resumido de presentacion de la comunidad para bloques de texto o estadisticas futuras.
+- Metodo HTTP: `GET`
+- Ruta: `/api/community`
+- Estado actual: previsto
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "title": "Comunidad Hispana HLL Vietnam",
+    "summary": "Punto de encuentro para jugadores, escuadras y comunidad.",
+    "discord_invite_url": "https://discord.com/invite/PedEqZ2Xsa"
+  }
+}
+```
+
+### `GET /api/trailer`
+
+- Proposito: exponer la informacion del trailer que hoy esta fija en la landing.
+- Metodo HTTP: `GET`
+- Ruta: `/api/trailer`
+- Estado actual: previsto
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "video_url": "https://www.youtube.com/embed/JzYzYNVWZ_A",
+    "title": "Trailer HLL Vietnam",
+    "provider": "youtube"
+  }
+}
+```
+
+### `GET /api/discord`
+
+- Proposito: centralizar la informacion publica del acceso a Discord sin integrar todavia datos reales del servidor.
+- Metodo HTTP: `GET`
+- Ruta: `/api/discord`
+- Estado actual: placeholder
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "invite_url": "https://discord.com/invite/PedEqZ2Xsa",
+    "label": "Unirse al Discord",
+    "availability": "manual"
+  }
+}
+```
+
+### `GET /api/servers`
+
+- Proposito: exponer un bloque provisional de servidores actuales de Hell Let Loose como referencia temporal para la comunidad.
+- Metodo HTTP: `GET`
+- Ruta: `/api/servers`
+- Estado actual: placeholder implementado
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "title": "Servidores actuales de Hell Let Loose",
+    "context": "current-hll-reference",
+    "source": "controlled-placeholder",
+    "items": [
+      {
+        "server_name": "HLL ESP Tactical Rotation",
+        "status": "online",
+        "players": 74,
+        "max_players": 100,
+        "current_map": "Sainte-Marie-du-Mont",
+        "region": "EU"
+      }
+    ]
+  }
+}
+```
+
+Notas del placeholder actual:
+
+- El contenido representa servidores actuales de Hell Let Loose, no servidores de HLL Vietnam.
+- `context` permite al frontend etiquetar el bloque como referencia provisional.
+- `source` indica que la respuesta actual sale de datos controlados del backend.
+
+### `GET /api/servers/latest`
+
+- Proposito: devolver el ultimo snapshot conocido por servidor desde la persistencia local.
+- Metodo HTTP: `GET`
+- Ruta: `/api/servers/latest`
+- Estado actual: implementado para validacion tecnica
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "title": "Ultimo estado conocido de servidores",
+    "context": "current-hll-history",
+    "source": "local-snapshot-storage",
+    "items": [
+      {
+        "server_id": 1,
+        "external_server_id": "hll-esp-tactical-rotation",
+        "server_name": "HLL ESP Tactical Rotation",
+        "region": "EU",
+        "captured_at": "2026-03-20T08:45:20.802006Z",
+        "status": "online",
+        "players": 74,
+        "max_players": 100,
+        "current_map": "Sainte-Marie-du-Mont"
+      }
+    ]
+  }
+}
+```
+
+### `GET /api/servers/history`
+
+- Proposito: devolver una ventana simple de snapshots recientes desde la persistencia local.
+- Metodo HTTP: `GET`
+- Ruta: `/api/servers/history`
+- Parametros opcionales: `limit` entre `1` y `100`
+- Estado actual: implementado para validacion tecnica
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "title": "Historial reciente de servidores",
+    "context": "current-hll-history",
+    "source": "local-snapshot-storage",
+    "limit": 20,
+    "items": []
+  }
+}
+```
+
+### `GET /api/servers/{id}/history`
+
+- Proposito: devolver una historia basica de snapshots para un servidor concreto.
+- Metodo HTTP: `GET`
+- Ruta: `/api/servers/{id}/history`
+- Parametros opcionales: `limit` entre `1` y `100`
+- Identificadores aceptados: `server_id` numerico interno o `external_server_id`
+- Estado actual: implementado para validacion tecnica
+
+Ejemplo JSON:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "title": "Historial por servidor",
+    "context": "current-hll-history",
+    "source": "local-snapshot-storage",
+    "server_id": "hll-esp-tactical-rotation",
+    "limit": 20,
+    "items": []
+  }
+}
+```
+
+## Consumo previsto desde frontend
+
+- El frontend deberia llamar primero a `GET /health` solo para comprobaciones tecnicas o entornos de desarrollo, no para condicionar el render basico de la landing.
+- Los endpoints de contenido (`/api/community`, `/api/trailer`, `/api/discord`, `/api/servers`) deberian consumirse con `fetch`.
+- Si una llamada falla, la landing debe conservar un fallback estatico mientras exista contenido fijo en `index.html`.
+- La futura migracion debe reemplazar valores hardcoded de forma incremental, endpoint por endpoint.
+
+## Notas de alcance
+
+- Este contrato no introduce autenticacion.
+- Este contrato no define base de datos.
+- Este contrato no integra Discord ni servidores reales.
+- La implementacion de estos endpoints queda para tasks posteriores.

docs/frontend-data-consumption-plan.md

@@ -0,0 +1,73 @@
+# Frontend Data Consumption Plan
+
+## Objective
+
+Definir como evolucionara la landing de HLL Vietnam desde contenido estatico hacia bloques alimentados por el backend sin romper simplicidad, branding ni compatibilidad al abrir `frontend/index.html` directamente.
+
+## Current Frontend Blocks With Future Dynamic Potential
+
+- Hero principal: titulo, resumen y CTA de Discord podran leer `community` y `discord`.
+- Bloque de trailer: podra leer `trailer` para desacoplar video y titulo del HTML.
+- Estado de servidores: queda reservado para una futura seccion y no debe forzarse en la landing actual.
+
+## Recommended Consumption Strategy
+
+- Usar `fetch` nativo cuando una task habilite consumo real.
+- Mantener JavaScript simple en `frontend/assets/js/main.js` o dividir en modulos ligeros solo si el numero de bloques dinamicos ya lo justifica.
+- Centralizar la URL base del backend en una configuracion minima si el frontend deja de ser puramente estatico en un entorno concreto.
+- No llamar a servicios externos desde el navegador; el frontend debe hablar con el backend Python.
+
+## UI State Rules
+
+### Loading
+
+- No bloquear el render inicial de la landing.
+- Mostrar skeletons o placeholders ligeros solo en bloques futuros que ya dependan del backend.
+
+### Error
+
+- Si falla una llamada, conservar el contenido estatico existente o un mensaje tactico breve y no intrusivo.
+- Registrar el error en consola durante desarrollo sin degradar toda la pagina.
+
+### Empty state
+
+- Si `servers.items` llega vacio, mostrar un estado neutral de "informacion disponible mas adelante".
+- Si un bloque opcional no tiene datos, ocultarlo o dejar un placeholder discreto en lugar de mostrar errores tecnicos.
+
+### Fallback
+
+- Mantener el Discord CTA hardcoded hasta que `/api/discord` sea estable.
+- Mantener el iframe del trailer fijo hasta validar `/api/trailer`.
+- No hacer depender el hero de `/health`.
+
+## Endpoint Priority
+
+1. `/api/community`
+2. `/api/trailer`
+3. `/api/discord`
+4. `/api/servers`
+5. `/health` solo para checks tecnicos o diagnostico en desarrollo
+
+## Progressive Migration Path
+
+### Step 1
+
+- Introducir una capa minima de lectura para `community` y `trailer`.
+- Reutilizar el HTML actual como fallback.
+
+### Step 2
+
+- Sustituir el CTA de Discord por datos de `/api/discord` cuando el placeholder backend sea estable.
+- Mantener la URL actual como respaldo local.
+
+### Step 3
+
+- Anadir una seccion de servidores solo cuando exista diseno, contrato y placeholder suficientemente claros.
+- Evitar reservar complejidad en la landing antes de que ese bloque aporte valor real.
+
+## Explicitly Out Of Scope Now
+
+- Implementar `fetch` real.
+- Cambiar el comportamiento visible de la landing.
+- Introducir librerias de estado o frameworks frontend.
+- Conectar el navegador directamente con Discord o con APIs de servidores.

docs/project-overview.md

@@ -2,7 +2,7 @@
 
 ## Vision del proyecto
 
-HLL Vietnam busca convertirse en la base de una web de comunidad para centralizar la presencia digital de una comunidad hispana alrededor del juego, con una identidad visual sobria, táctica y coherente con el universo Vietnam.
+HLL Vietnam busca convertirse en la base de una web de comunidad para centralizar la presencia digital de una comunidad hispana alrededor del juego, con una identidad visual sobria, tactica y coherente con el universo Vietnam.
 
 ## Objetivo inicial
 
@@ -11,10 +11,10 @@ Publicar una landing simple que permita presentar la comunidad, mostrar el trail
 ## Alcance actual
 
 - Estructura inicial del repositorio.
-- Landing estática en HTML, CSS y JavaScript.
-- Documentación base para organizar el crecimiento del proyecto.
-- Preparación de carpetas para backend y orquestación futura.
-- Plataforma de tasks y orquestación integrada para coordinar trabajo técnico.
+- Landing estatica en HTML, CSS y JavaScript.
+- Documentacion base para organizar el crecimiento del proyecto.
+- Preparacion de carpetas para backend y orquestacion futura.
+- Plataforma de tasks y orquestacion integrada para coordinar trabajo tecnico.
 
 ## Stack actual
 
@@ -26,5 +26,17 @@ Publicar una landing simple que permita presentar la comunidad, mostrar el trail
 ## Stack futuro previsto
 
 - Backend principal en Python
-- Integraciones de comunidad y automatización
-- Posible ampliación de paneles administrativos y servicios internos
+- Integraciones de comunidad y automatizacion
+- Posible ampliacion de paneles administrativos y servicios internos
+
+## Contrato inicial frontend backend
+
+El repositorio define un contrato API inicial en `docs/frontend-backend-contract.md` para alinear la futura comunicacion entre la landing y el backend Python.
+
+En esta fase solo existe `GET /health` como endpoint implementado. Las rutas de comunidad, trailer, Discord y servidores quedan documentadas como contrato previsto para futuras tasks sin cambiar todavia el comportamiento visible del frontend.
+
+## Evolucion prevista del frontend
+
+La landing debe seguir siendo funcional al abrirse directamente en navegador mientras los datos dinamicos se introducen de forma incremental. La estrategia de consumo prevista usa `fetch` y JavaScript simple cuando una task lo requiera, siempre conservando fallbacks estaticos mientras se valida cada endpoint.
+
+La planificacion detallada de prioridades de consumo, estados de carga, errores y placeholders queda en `docs/frontend-data-consumption-plan.md`.

docs/roadmap.md

@@ -3,29 +3,33 @@
 ## Fase 1: base del repo
 
 - Crear estructura inicial profesional.
-- Definir documentación base del proyecto.
-- Publicar la primera landing estática.
+- Definir documentacion base del proyecto.
+- Publicar la primera landing estatica.
 
 ## Fase 2: landing mejorada
 
 - Incorporar branding definitivo y recursos visuales.
-- Añadir más secciones informativas de comunidad.
+- Anadir mas secciones informativas de comunidad.
 - Mejorar experiencia responsive y contenido.
 
 ## Fase 3: backend Python
 
 - Definir arquitectura del backend.
 - Incorporar servicios base en Python.
-- Preparar configuración, entornos y despliegue inicial.
+- Preparar configuracion, entornos y despliegue inicial.
 
-## Fase 4: integración de datos de Discord/servidores
+## Fase 4: integracion de datos de Discord/servidores
 
-- Estudiar integraciones viables con Discord.
-- Incorporar datos de comunidad o estado de servicios.
-- Añadir automatizaciones controladas y trazables.
+- Documentar el plan tecnico de datos para Discord y servidores antes de integrar fuentes reales.
+- Empezar por placeholders o datos manuales controlados desde el backend Python.
+- Incorporar integraciones limitadas y trazables solo despues de validar fuentes, limites y seguridad.
+- Diferenciar de forma explicita los servidores actuales de Hell Let Loose frente al futuro contexto HLL Vietnam.
+- Sustituir el bloque provisional de servidores actuales cuando existan datos mas cercanos al producto final.
+- Definir snapshots de servidores como unidad base para historicos y estadisticas basicas antes de persistir datos reales.
+- Separar por fases la ingesta, la normalizacion y la futura explotacion historica para no acoplar el frontend a fuentes externas.
 
-## Fase 5: panel/admin y automatización
+## Fase 5: panel/admin y automatizacion
 
 - Construir panel interno o administrativo.
-- Añadir flujos de gestión y publicación.
-- Integrar sistema de tareas y orquestación del proyecto.
+- Anadir flujos de gestion y publicacion.
+- Ampliar y madurar el sistema de tasks y orquestacion ya integrado en el repositorio.

docs/stats-database-schema-foundation.md

@@ -0,0 +1,151 @@
+# 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