6.2 KiB
Technical Decisions
Decision 001: frontend simple HTML/CSS/JS
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 implementacion futura se realizara en Python.
Decision 003: estructura preparada para orquestacion por agentes
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 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 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.
Decision 012: historico de scoreboards reales separado del estado A2S
La capa historica del proyecto debe tomar como fuente inicial las dos paginas de scoreboard reales ya usadas por la comunidad:
https://scoreboard.comunidadhll.es/gameshttps://scoreboard.comunidadhll.es:5443/games
Esta fuente historica no debe mezclarse conceptualmente con los snapshots A2S de estado actual. A2S sigue siendo la fuente del panel live; el scoreboard pasa a ser la fuente base para partidas, jugadores y metricas agregadas.
La primera analitica prioritaria sera top kills de la ultima semana por servidor, por lo que el dominio historico debe organizarse alrededor de
servidor, partida, jugador, participacion y metricas por jugador en partida.
La definicion de fuente, identidad, deduplicacion y riesgos queda documentada
en docs/historical-stats-domain-model.md.