comunidadhll/ai/tasks/done/TASK-005-frontend-backend-contract.md

TASK-005-frontend-backend-contract

Goal

Definir el contrato inicial entre frontend y backend para el proyecto HLL Vietnam, estableciendo endpoints, formatos de respuesta y convenciones mínimas sin implementar todavía integraciones reales con Discord, servidores de juego o base de datos.

Context

El proyecto ya dispone de una landing mínima funcional y de un backend Python bootstrap con verificación básica de estado. Antes de añadir lógica real, es importante fijar un contrato claro entre frontend y backend para evitar improvisación posterior y permitir que futuras tasks implementen endpoints y consumo de datos de forma consistente.

Steps

1. Revisar la estructura actual del frontend y del backend.
2. Revisar el estado actual del backend bootstrap y el endpoint de salud existente.
3. Definir el conjunto mínimo de endpoints previstos a corto plazo, aunque algunos queden documentados como futuros. Incluir al menos:
   • GET /health
   • GET /api/community
   • GET /api/trailer
   • GET /api/discord
   • GET /api/servers
4. Para cada endpoint, documentar:
   • propósito
   • método HTTP
   • ruta
   • formato de respuesta
   • ejemplo JSON
   • estado actual: implementado, previsto o placeholder
5. Definir convenciones básicas de respuesta:
   • nombres de campos
   • estructura JSON
   • uso de status
   • tratamiento mínimo de errores
6. Documentar cómo debería consumir el frontend estos endpoints más adelante, sin implementarlo todavía.
7. Añadir o actualizar documentación técnica para que el contrato quede claro dentro del repositorio.
8. Si detectas incoherencias pequeñas entre documentación y bootstrap actual, corrígelas sin salirte del alcance.

Files to Read First

• README.md
• AGENTS.md
• docs/project-overview.md
• docs/roadmap.md
• docs/decisions.md
• ai/repo-context.md
• ai/architecture-index.md
• backend/README.md
• backend/app/init.py
• backend/app/main.py
• frontend/index.html
• frontend/assets/js/main.js

Expected Files to Modify

• docs/project-overview.md
• docs/decisions.md
• backend/README.md
• ai/architecture-index.md
• opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
  • docs/frontend-backend-contract.md

Constraints

• No implementar todavía endpoints reales adicionales.
• No integrar Discord real.
• No integrar servidores de juego reales.
• No introducir base de datos.
• No cambiar el comportamiento visible del frontend.
• No añadir frameworks ni dependencias nuevas.
• No hacer cambios destructivos.
• Mantener la solución clara, pequeña y útil para futuras tasks.

Validation

• Existe documentación clara del contrato inicial frontend-backend.
• GET /health queda reflejado correctamente como endpoint actual.
• Los endpoints futuros quedan documentados con ejemplos coherentes.
• El contrato usa convenciones consistentes de respuesta JSON.
• El repositorio queda preparado para que siguientes tasks implementen endpoints reales de forma ordenada.

Change Budget

• Preferir menos de 5 archivos modificados o creados.
• Preferir menos de 220 líneas cambiadas.

Outcome

• Se añadió docs/frontend-backend-contract.md como referencia central del contrato inicial frontend-backend.
• Se actualizaron docs/project-overview.md, docs/decisions.md y backend/README.md para reflejar el contrato y el estado actual de GET /health.
• No se implementaron endpoints nuevos ni se cambió el comportamiento visible del frontend.

Validation Result

• Verificado con python -c "from app.main import build_health_payload; print(build_health_payload())" en backend/.
• Resultado comprobado: {'status': 'ok', 'service': 'hll-vietnam-backend', 'phase': 'bootstrap'}.
• No aplican integration tests para este alcance documental.