Arquitectura Hexagonal: Separando el Juego del Tablero

Imaginá que estás programando un juego de ajedrez.
Las reglas del juego son siempre las mismas: cómo se mueve el alfil, qué pasa si hay jaque mate, etc.
Pero podés jugarlo en:

• Un tablero físico.
• Una app web.
• Un bot que juega solo.
• Una terminal.

El medio cambia, pero las reglas no.

Esa es la idea base de la arquitectura hexagonal

La arquitectura hexagonal (basado en algo llamado “ports and adapters”) parte de una idea simple pero poderosa:

Separar el núcleo del sistema de todo lo que está afuera.

Esto permite que tus reglas no dependan de si estás usando Express, React, PostgreSQL o una API externa.

¿Qué es el “núcleo” y qué es el “exterior”?

La arquitectura hexagonal divide el sistema en tres conceptos clave:

⚙️ Dominio: Las Reglas del Juego

Es el corazón del sistema.
Acá vive la lógica que no cambia aunque cambies la base de datos, el framework o el frontend.

En nuestro ejemplo de ajedrez, sería:

• Cómo se mueven las piezas.
• Qué es un jaque mate.
• Cuándo termina el juego.

En una app real, sería:

• Qué significa que una tarea esté “completa”.
• Qué condiciones tiene que cumplir un usuario para aprobar un curso.
• Qué reglas definen una compra válida.

El dominio no debería tener ni una línea de código que diga “fetch”, “axios”, “SQL”, “res.send()” o “console.log()”. Es puro conocimiento del negocio.

🧠 Aplicación: El Coordinador

Es quien orquesta las acciones. No decide las reglas, pero las usa.

• Recibe una intención (por ejemplo, “completar tarea”).
• Coordina a los objetos del dominio.
• Llama a servicios externos si hace falta (pero a través de interfaces).

No contiene reglas del negocio en sí, pero sabe cómo aplicar esas reglas en orden correcto.

🌍 Infraestructura: Los Conectores con el Mundo

Es el “tablero” donde se juega.
Incluye todo lo que conecta nuestro sistema con el exterior:

• Frameworks como Express o Fastify.
• Bases de datos como PostgreSQL o MongoDB.
• Servicios como Stripe o Auth0.
• Archivos, emails, logs, APIs externas, etc.

Todo esto debería estar en la periferia del sistema, y no mezclado con el dominio.

¿Por Qué Es Tan Potente Esta Separación?

Separar estos mundos trae muchos beneficios:

• ✅ Podés testear el dominio sin levantar servidores ni tocar la base de datos.
• ✅ Cambiar la base de datos no cambia el núcleo.
• ✅ Podés agregar una nueva interfaz (ej: API GraphQL, CLI, bot) sin duplicar lógica.
• ✅ El código es más fácil de leer, entender y mantener.

¿Y Por Qué “Hexagonal”?

El nombre viene de un diagrama original que mostraba al núcleo con varios “puertos” conectados por adaptadores alrededor, como un hexágono.

Pero el concepto no depende de la forma.
Podríamos llamarla “arquitectura cebolla”, “arquitectura de capas claras”, o simplemente “arquitectura con sentido común”.

Conclusión: No Es Magia, Es Separación de Roles

La arquitectura hexagonal no es un framework ni una librería.
Es una forma de pensar tu código que pone las reglas en el centro, y deja todo lo demás como accesorio.