ADR-03 · Un solo BFF para web y móvil

Estado: aceptada · Impacto: alto

Contexto

Hay dos clientes con necesidades distintas: la web de escritorio muestra tablas densas con muchos campos; la app de campo muestra tarjetas con lo esencial.

Decisión

Un único BFF GraphQL. Cada cliente pide los campos que necesita.

Por qué

Con REST, dos clientes con necesidades distintas llevan a una de estas tres salidas, y las tres son malas:

• Una API por plataforma → la lógica se duplica y se desincroniza.
• Endpoints que devuelven todo → el móvil descarga datos que no usa.
• Endpoints a medida por pantalla → la API crece sin control.

GraphQL resuelve exactamente eso: el móvil pide menos, la tabla pide más, y la lógica vive en un solo sitio.

Consecuencias

• El contrato (schema.graphql) es la fuente única de verdad. El servidor lo implementa; los clientes generan sus tipos desde él.
• Hacen falta DataLoaders: resolver ticket.customer en una lista de 50 tickets no puede ser 50 consultas.
• La paginación es por desplazamiento, no por cursor: la tabla de escritorio y el scroll infinito del móvil la necesitan igual, y los cursores tienen coste sin beneficio a este tamaño.

Relacionado: Contrato GraphQL · Backend