¿Cómo sabes que tu comprensión del problema realmente refleja lo que deberías entender, y que estás diseñando soluciones en la dirección correcta? Comunicando. Y la mejor forma de comunicar arquitectura de software es con diagramas bajo una notación estándar como el modelo C4, complementado con UML cuando hace falta más detalle.
Esa es la base sobre la que vas a construir tus entregables como arquitecto, y aquí te muestro cómo hacerlo sin caer en la trampa de inventar tu propia notación.
¿Por qué necesitas un estándar de diagramación en arquitectura?
Mucha gente diagrama de forma libre. Eso tiene una ventaja obvia: puedes contar tu historia a tu manera. Pero el costo aparece después, cuando alguien nuevo entra al equipo y se encuentra con notaciones personales que nadie más puede leer.
El problema más común que vas a ver es la inconsistencia en las flechas de relación. ¿Esa flecha significa dependencia, agregación, comunicación? Nadie lo sabe con certeza. Y ahí empieza el caos.
¿Qué problema resuelve usar una notación estándar? Elimina las ambigüedades en cómo representas relaciones, dependencias y componentes, y permite que cualquier persona del equipo o externa lea tus diagramas sin aprender un lenguaje nuevo cada vez.
Para el proyecto del Banco Interamericano de Desarrollo, la herramienta elegida es draw.io: gratuita, con una paleta amplia y se integra bien con sistemas de documentación. Pero recuerda algo importante: la herramienta no importa, lo que importa es que te expreses correctamente.
¿Qué es el modelo C4 y cómo funciona por niveles?
El C4 es un modelo deductivo. Empiezas desde un nivel altísimo de abstracción y vas haciendo zoom in iterativamente, como si dieras doble clic en cada capa.
Los cuatro niveles son:
- Contexto: el nivel más alto, donde defines el sistema y sus actores externos.
- Contenedores: unidades desplegables del sistema, como microservicios, bases de datos o capas de almacenamiento.
- Componentes: las piezas internas dentro de cada contenedor.
- Código o detalle concreto: aquí entran notaciones como UML para profundizar.
En la notación se usa un código de colores muy simple: gris para entidades fuera del alcance del diseño actual y colores brillantes para los componentes que sí son parte de la discusión. Eso le ahorra mucho tiempo al lector.
¿Qué elementos incluye la paleta estándar de C4?
La paleta es corta y por eso es poderosa. Tienes:
- Actores del sistema bajo el control del contexto.
- Actores externos relacionados pero que no son stakeholders directos.
- Contenedores para unidades desplegables.
- Contenedores para capas de almacenamiento de datos.
- Microservicios y servicios a implementar.
- Manejo de trabajo asíncrono o patrones producer-consumer.
Con pocos símbolos, cubres prácticamente todo lo que necesitas representar.
¿Cuándo usar diagramas concretos en lugar de abstractos?
C4 es abstracto, y eso a veces obliga al lector a hacer un esfuerzo para aterrizarlo. Por eso una mejora natural es complementar con diagramas concretos, que muestran las herramientas específicas detrás de la abstracción.
Ejemplo claro: cuando hablas de un contenedor con unidades desplegables, en concreto te refieres a una herramienta de un proveedor cloud como AWS, conectada por acceso público o privado a otra unidad desplegable. Ese tipo de diagrama es mucho más fácil de seguir para perfiles técnicos y sirve de puente entre la arquitectura de alto nivel y la implementación.
También puedes apoyarte en diagramas más específicos como los diagramas de estado, que son un aporte clásico de UML.
¿Qué es diagrams-as-code y cuándo conviene usarlo?
No todos los diagramas se hacen con point and click. Existe una técnica intermedia llamada diagrams-as-code, donde generas dibujos a partir de un lenguaje específico de dominio. Un ejemplo muy usado es Mermaid.
¿Qué es diagrams-as-code? Es una técnica donde describes diagramas usando un lenguaje de texto, como Mermaid, en lugar de arrastrar y soltar elementos. El diagrama se genera automáticamente desde el código.
Hay diseñadores, arquitectos y líderes técnicos que se sienten más cómodos escribiendo que arrastrando. La elección depende de las capacidades de tu equipo, y debe convertirse en un estándar que puedas validar y promover internamente.
¿Por qué la consistencia evita el problema de la Torre de Babel?
Un problema común con la diagramación es que cada quien usa su propia versión. Eso tiene costos a largo plazo que como arquitecto debes evitar. Mantener notación consistente entre diagramas y entregables trae beneficios concretos:
- Facilita la comprensión a miembros existentes, nuevos y no técnicos.
- Promueve la sistematización, lo que permite generar entregables consistentes con workflows o agentes.
- Reduce la carga cognitiva de aprender una notación nueva cada vez.
Piensa en el ejemplo de la natación. El estilo mariposa es conocido por todos en el contexto de la natación. Pero si cada persona tuviera su propia descripción del estilo mariposa, terminarías con muchas versiones no comparables que tendrías que aprender una por una. Eso es exactamente lo que pasa cuando cada equipo inventa su propia notación.
Con diagramas de contexto, sistema, contenedores y diagramas concretos bien estandarizados, cada diseño se puede comparar y versionar en el tiempo. Eso permite que más adelante, cuando el proyecto crezca, alguien nuevo pueda revisar la historia y la evolución de las decisiones arquitectónicas sin perderse.
Existen alternativas como el modelo 4+1, los storyboards o los diagramas como código. Elige la que sea más fácil de mantener y de mantener consistente para tu equipo. ¿Tú qué notación estás usando hoy en tus proyectos?
