Guía de Patrones de Diseño Fullstack

¿Qué hace Guía de Patrones de Diseño Fullstack?

Usa esta habilidad para asesorar, arquitecturar y refactorizar sistemas fullstack de extremo a extremo. Aplica los patrones estrictamente para resolver fricciones arquitectónicas identificables, no para abstracciones especulativas.

Principios Fundamentales

1. Selección Basada en Problemas: Nunca introduzcas un patrón de diseño sin una fricción arquitectónica explícita o un olor a código (por ejemplo, prop drilling, componentes dios inflados, acoplamiento estricto de API, lógica no testeable, fallos en cascada de red).
2. Límites Arquitectónicos Claros: Mantén límites claros entre:
   • Vista / Presentación: Componentes declarativos y tontos impulsados por props.
   • Estado e Interacción del Cliente: Hooks sin cabeza, stores centralizados y caché de estado del servidor.
   • Capa de API / Contrato: Esquemas tipados, adaptadores DTO y capas de anticorrupción.
   • Dominio y Acceso a Datos: Reglas de negocio desacopladas y acceso a base de datos respaldado por repositorios.
3. Evita la Sobreingeniería: No apliques abstracciones empresariales complejas (como micro-frontends, CQRS o pub/sub distribuido) a páginas CRUD simples o aplicaciones web estándar.

---

Matriz de Decisión de Patrones y Heurísticas de Disparo

Capa	Síntoma / Fricción en el Código	Patrón Recomendado	Límite Arquitectónico
UI Frontend	Componente dios que mezcla obtención de API, formato y maquetación JSX	Contenedor / Presentacional	Separar renderizado UI de la obtención de datos
UI Frontend	Estilos fuertemente acoplados dentro de componentes interactivos (modales, desplegables)	Componente sin Cabeza / Hooks Personalizados	Aislar estado y lógica de teclado/interacción
UI Frontend	APIs de componentes rígidas que necesitan subelementos flexibles	Componentes Compuestos	Compartición de estado padre-hijo declarativa (ej., Tabs, Select)
UI Frontend	Prop drilling profundo o estados de UI multi-componente desincronizados	Observador / Store (Zustand/Redux/Context)	Centralizar estado compartido del cliente
API Fullstack	Los cambios en el esquema de la API backend rompen componentes de UI frontend	Patrón Adaptador (Mapeador de Datos)	Capa de Anticorrupción que traduce DTO a Modelo de Vista
API Fullstack	La UI espera a redes lentas antes de confirmar la acción del usuario	UI Optimista con Rollback	Respuesta inmediata de UI respaldada por rollback transaccional
Backend	Consultas SQL/ORM dispersas dentro de manejadores de ruta o servicios	Patrón Repositorio	Desacoplar consultas de persistencia de reglas de negocio
Backend	Instanciar diferentes SDKs de terceros usando if-else en línea	Patrón Fábrica	Centralizar creación de objetos y clientes
Backend	if-else / switch en cascada para calcular precios, autenticación o algoritmos	Patrón Estrategia	Encapsular algoritmos intercambiables detrás de una interfaz
Backend / Distribuido	Una acción de negocio central desencadena 5+ efectos secundarios no relacionados	Observador / Basado en Eventos (Pub/Sub)	Desacoplar efectos secundarios mediante eventos de dominio o colas de mensajes
Backend / Distribuido	Latencia de API externa que causa inanición de hilos y caídas en cascada	Circuito de Corte (Circuit Breaker)	Fallo rápido, respuesta de respaldo y sondeo de salud de servicios posteriores

---

Análisis Profundo: Patrones Fullstack y Reglas de Implementación

1. Frontend: Patrón Contenedor / Presentacional

• Contexto: Componentes que crecen más allá de 200 líneas al combinar useEffect, consultas, transformaciones de datos y maquetación JSX.
• Reglas:
  • Componente Presentacional: Recibe datos y callbacks solo a través de props; puro, fácilmente testeable en Storybook sin mocks de API.
  • Contenedor (o Hook de Página): Obtiene datos del servidor, gestiona estados de carga/error y pasa datos transformados hacia abajo.

2. Frontend: Patrón Componente sin Cabeza y Hook Personalizado

• Contexto: Comportamientos interactivos complejos (autocompletado, asistentes de varios pasos, acordeón) que requieren reutilización en diferentes diseños visuales.
• Reglas:
  • Extrae estado, manejadores de teclado y atributos ARIA en un hook personalizado sin cabeza (ej., useAutocomplete, useDisclosure).
  • Mantén el estilo y el marcado DOM completamente en manos del consumidor.

3. Frontend: Componentes Compuestos

• Contexto: Componentes con subpartes profundamente relacionadas que necesitan un estado interno cohesivo sin pasar docenas de props de configuración.
• Reglas:
  • Aprovecha React Context para comunicarse implícitamente entre padre e hijo (<Acordeon><Acordeon.Item /><Acordeon.Panel /></Acordeon>).

4. Integración: Patrón Adaptador (Capa de Anticorrupción)

• Contexto: Cargas útiles de REST/GraphQL de terceros que se filtran directamente en las props de componentes UI o modelos de dominio centrales.
• Reglas:
  • Nunca permitas que las claves DTO del backend sin procesar dicten la forma de las props de los componentes frontend.
  • Crea funciones de mapeo explícitas (ej., toUserViewModel(dto: UserApiDto): UserVM) para proteger los componentes UI de los cambios de esquema.

5. Integración: UI Optimista con Rollback

• Contexto: Interacciones frecuentes del usuario (me gusta, alternar, completar tareas, reordenar) donde la latencia de red perjudica la capacidad de respuesta.
• Reglas:
  • Actualiza el estado local inmediatamente tras la interacción.
  • Pon en cola la mutación del servidor; si se rechaza, retrocede a la instantánea anterior y notifica al usuario de forma no intrusiva.

6. Backend: Patrón Repositorio

• Contexto: Lógica de negocio entrelazada con consultas ORM (Prisma, TypeORM, Drizzle, SQL).
• Reglas:
  • Los servicios interactúan únicamente con una interfaz (ej., OrderRepository).
  • Mantén la lógica de dominio fuera de los repositorios; mantén la construcción de consultas fuera de los servicios.

7. Backend: Patrones Estrategia y Fábrica

• Contexto: Proveedores intercambiables (pasarelas de pago, canales de notificación, almacenamiento de archivos).
• Reglas:
  • Estandariza el comportamiento a través de una interfaz común (PaymentGateway).
  • Usa una Fábrica/Registro para resolver implementaciones concretas según la configuración o el inquilino.

8. Backend: Patrón Circuito de Corte (Circuit Breaker)

• Contexto: Microservicios externos o APIs de terceros que sufren tiempo de inactividad intermitente o latencia severa.
• Reglas:
  • Rastrea umbrales de fallo. Transiciones: Cerrado (normal) -> Abierto (fallo rápido, devuelve caché/respaldo) -> Semiabierto (sondeo canario).

---

Flujo de Trabajo de Salida del Agente

Cuando se te pida asesorar sobre arquitectura o refactorizar código fullstack:

1. Identifica el Límite y el Cuello de Botella: Determina si la fricción se encuentra en el renderizado UI, la sincronización de estado, la discrepancia del contrato de API o el acoplamiento backend.
2. Selecciona el Patrón Correspondiente: Propón el patrón con una justificación clara que aborde el olor a código específico.
3. Proporciona Ejemplos de Antes y Después: Ofrece fragmentos de código concisos e idiomáticos que demuestren responsabilidades desacopladas.
4. Destaca la Testabilidad y Mantenibilidad: Explica cómo la refactorización simplifica las pruebas unitarias/de componentes y protege contra cambios futuros.