Una arquitectura que solo existe en la cabeza de su autor es una arquitectura perdida. Documentarla es lo que permite que el equipo la entienda, que los nuevos miembros se incorporen rápido, que el negocio confíe en lo que se construye y que las decisiones sobrevivan a la rotación de personas. Pero documentar bien es difícil: los diagramas suelen quedar obsoletos, mezclar niveles de detalle o resultar incomprensibles para quien no los dibujó. En esta lección aprenderás dos herramientas fundamentales: el clásico modelo de vistas 4+1 de Philippe Kruchten y, sobre todo, el moderno modelo C4 de Simon Brown, una forma sencilla y pragmática de diagramar arquitecturas con cuatro niveles de zoom: Contexto, Contenedor, Componente y Código.

1. Por qué documentar y para quién
2. El modelo 4+1 de vistas
3. El modelo C4: la idea del zoom
4. Nivel 1: diagrama de Contexto
5. Nivel 2: diagrama de Contenedores
6. Nivel 3: diagrama de Componentes
7. Nivel 4: Código
8. Buenas prácticas y herramientas

Documentar no es producir cientos de páginas que nadie leerá. Es comunicar de forma eficaz a distintas audiencias. La regla principal: documenta lo justo, para una audiencia concreta y con un propósito claro.

Un error clásico es usar un único diagrama gigante para todas las audiencias: acaba siendo demasiado detallado para el negocio y demasiado superficial para el desarrollador. La solución es ofrecer distintas vistas a distintos niveles.

Propuesto por Philippe Kruchten en 1995, el modelo 4+1 parte de la idea de que ninguna vista única captura toda la arquitectura. Propone cuatro vistas más una transversal.

Este diagrama Mermaid sitúa los escenarios en el centro, conectados (con ---, líneas sin dirección) a las cuatro vistas. La idea es que los casos de uso clave "atan" y validan las demás vistas: cada escenario importante debe poder recorrerse a través de la vista lógica, de procesos, de desarrollo y física. El modelo 4+1 sigue siendo conceptualmente valioso, pero en la práctica diaria muchos equipos prefieren hoy el C4 por su sencillez y su mapeo directo a cómo se construye realmente el software.

El modelo C4, creado por Simon Brown, se basa en una analogía con los mapas: igual que usas distintos niveles de zoom (mundo, país, ciudad, calle), una arquitectura se entiende mejor con distintos niveles de detalle. C4 define cuatro niveles, cada uno un "zoom" sobre el anterior:

Conceptos básicos de C4:

• Persona: un usuario humano del sistema (cliente, administrador...).
• Sistema de software: lo que construyes (o un sistema externo con el que te integras).
• Contenedor: no es necesariamente un contenedor Docker; es algo que se ejecuta y se despliega de forma independiente: una aplicación web, una API, una base de datos, una single-page app, un broker.
• Componente: una agrupación lógica de funcionalidad dentro de un contenedor.

Una regla de oro de C4: la mayoría de los equipos solo necesitan los niveles 1 y 2 de forma habitual, y el 3 ocasionalmente. El nivel 4 casi nunca se dibuja a mano, porque lo genera el IDE.

Es el nivel más alto. Muestra tu sistema como una sola caja, rodeado de sus usuarios y de los sistemas externos con los que se relaciona. Su propósito es que cualquiera, incluido el negocio, entienda el panorama general.

Este diagrama de Contexto muestra una única caja para "Sistema de Banca Online", rodeada de una persona (el Cliente) y dos sistemas externos (Email y Core Bancario). Las flechas etiquetadas describen qué hace cada relación, no cómo. Fíjate en que no aparece ninguna tecnología ni detalle interno: a este nivel solo importa el alcance del sistema y sus interacciones con el exterior. Es el diagrama ideal para empezar cualquier conversación, también con personas no técnicas.

Hacemos zoom dentro de nuestro sistema. Mostramos las unidades desplegables que lo componen y cómo se comunican, indicando ya las tecnologías principales.

Aquí, dentro del sistema de banca online vemos tres contenedores propios: una aplicación web single-page en React, una API en Java con Spring Boot y una base de datos PostgreSQL; más el sistema externo (Core Bancario). Cada flecha indica el protocolo de comunicación (HTTPS, JSON, SQL). Este nivel es el más útil en el día a día técnico: muestra de un vistazo la arquitectura de despliegue, las tecnologías elegidas y los flujos de comunicación. Recuerda: "contenedor" aquí significa unidad desplegable, no necesariamente un contenedor Docker.

Ahora hacemos zoom dentro de un único contenedor —por ejemplo, la API de Banca— para ver cómo se organiza internamente en componentes.

Este diagrama usa un subgraph para representar las fronteras de la API de Banca y muestra tres componentes internos: el controlador REST que recibe las peticiones, el servicio que contiene la lógica de negocio y el repositorio que accede a los datos. Es la clásica separación en capas (presentación, negocio, datos) dentro de un contenedor. Este nivel es valioso para que los desarrolladores entiendan la estructura interna, pero conviene dibujarlo solo para los contenedores no triviales, no para todos.

El último nivel detalla cómo se implementa un componente concreto, normalmente con un diagrama de clases UML. En la práctica, casi nunca se dibuja a mano: lo genera automáticamente el IDE o herramientas de documentación, porque cambia constantemente y mantenerlo manualmente es trabajo perdido.

Este código muestra cómo se materializa el componente "Servicio de Transferencias" en clases concretas. La recomendación de C4 es no dibujar este nivel manualmente: si necesitas verlo, deja que tu IDE genere el diagrama de clases a partir del código real. Mantener diagramas de código a mano es la causa número uno de documentación obsoleta.

Resumen de las notaciones y prácticas recomendadas por C4:

• Cada diagrama, autoexplicativo: con título, leyenda y elementos claramente etiquetados.
• Etiqueta las relaciones: describe qué hace cada flecha y, si aplica, con qué tecnología/protocolo.
• Un nivel por diagrama: no mezcles contexto con código.
• No abuses del nivel 3 ni del 4: dibuja solo lo que aporta valor.
• Documentación como código (diagrams as code): define los diagramas en texto para versionarlos junto al código y evitar que queden obsoletos.

Herramientas habituales:

Ejemplo del mismo diagrama de contexto en PlantUML con la extensión C4:

Este fragmento PlantUML usa la librería oficial C4_Context. Las macros Person, System y System_Ext (sistema externo) crean los elementos con su nombre y descripción, y Rel define las relaciones etiquetadas. La ventaja frente a Mermaid es que PlantUML con C4 conoce la semántica del modelo (distingue personas de sistemas, internos de externos) y aplica un estilo coherente automáticamente. Al ser texto, se versiona junto al código y se regenera sin esfuerzo.

• El "diagrama plato de espaguetis". Un solo diagrama con todo mezclado no comunica nada. Separa por niveles y audiencias.
• Diagramas sin leyenda ni etiquetas. Si las cajas y flechas no se explican, cada lector interpreta lo que quiere. Etiqueta todo.
• Documentación que envejece. Los diagramas dibujados a mano quedan obsoletos enseguida. Usa diagrams as code y genera el nivel de código automáticamente.
• Exceso de detalle. No dibujes los niveles 3 y 4 para todo. La mayoría de equipos vive feliz con los niveles 1 y 2.
• Consejo: empieza siempre por el Contexto. En cualquier conversación de arquitectura, arranca con el diagrama de contexto; alinea a todos antes de bajar al detalle.

Ejercicio 1. Asocia cada elemento con su nivel C4: (a) "una base de datos Redis"; (b) "el cliente y el sistema de pago externo"; (c) "la clase ServicioPedidos"; (d) "el controlador, el servicio y el repositorio dentro de la API".

Ejercicio 2. Dibuja (en Mermaid o PlantUML) un diagrama de Contexto para un sistema de gestión de una biblioteca, con al menos una persona y un sistema externo.

Ejercicio 3. Explica por qué C4 recomienda no dibujar el nivel de Código manualmente y qué alternativa propone.

Solución 1. (a) Contenedor (nivel 2): una base de datos es una unidad desplegable. (b) Contexto (nivel 1): personas y sistemas externos. (c) Código (nivel 4): una clase concreta. (d) Componente (nivel 3): agrupaciones lógicas dentro de un contenedor.

Solución 2. Ejemplo en Mermaid:

Este diagrama de Contexto muestra dos personas (Socio y Bibliotecario), el sistema propio y un sistema externo de Email, con relaciones etiquetadas que describen qué hace cada interacción, sin entrar en tecnologías ni en la estructura interna.

Solución 3. Porque el código cambia continuamente y mantener a mano un diagrama de clases lo convierte rápidamente en documentación obsoleta y poco fiable, lo que genera más confusión que ayuda. La alternativa que propone C4 es generar este nivel automáticamente desde el propio código (con el IDE o herramientas de documentación) cuando realmente se necesite, en lugar de dibujarlo manualmente.

Has aprendido por qué y para quién se documenta una arquitectura, el clásico modelo de vistas 4+1 y, en profundidad, el modelo C4 con sus cuatro niveles de zoom (Contexto, Contenedor, Componente y Código), además de las prácticas y herramientas para mantener la documentación viva mediante diagrams as code. Con esto cierras el Módulo 1, Fundamentos de la Arquitectura de Aplicaciones: ya sabes qué es la arquitectura y sus ámbitos, quién es el arquitecto, cómo se especifican los atributos de calidad, cómo se toman y documentan las decisiones con sus trade-offs, y cómo comunicar todo ello con claridad. Sobre estos cimientos, los siguientes módulos profundizarán en los estilos y patrones arquitectónicos concretos con los que materializar estas ideas.