Cómo hacer un diagrama de arquitectura de software: guía paso a paso

Cuando te sientas a hacer tu primer diagrama de arquitectura, lo difícil no es dibujar cajas, sino decidir qué dejas fuera. Esta guía trata de diagramas de arquitectura de software y de sistemas: servicios, bases de datos, colas, zonas de red y las conexiones entre ellos. Tanto si es tu primer diagrama de arquitectura de software como si es el décimo de tu equipo, estos pasos te ayudan a crear uno que se entienda y que siga vigente.

Empieza por el lector y la pregunta

Un buen diagrama responde a una sola pregunta. «Todo nuestro sistema» no es una pregunta: es un inventario, y los inventarios van en una tabla.

Antes de dibujar nada, escribe dos frases:

• ¿Quién lo va a leer? Una desarrolladora recién llegada, el SRE de guardia, una revisión de seguridad, un product manager, un auditor externo.
• ¿Qué pregunta responde? «¿Por qué servicios pasa una petición de pedido?», «¿Qué está expuesto a internet?», «¿A dónde va el tráfico si cae una región?»

Esas dos frases fijan el alcance. Alguien nuevo en el equipo necesita un nivel de detalle distinto al del equipo de redes. Si intentas servir a ambos con una sola imagen, no sirves a ninguno.

Elige el tipo de diagrama

Con la pregunta clara, el tipo casi se elige solo. El modelo C4 es un buen punto de partida: divide un sistema en niveles de zoom llamados context, container, component y code (detalles en c4model.com).

Si dudas, empieza por un diagrama de contexto. Deja claros el límite del sistema y sus dependencias externas, y sirve de marco para todos los diagramas que vengan después.

Cómo hacer un diagrama de arquitectura, paso a paso

1. Define el alcance y el límite

Escribe qué queda dentro del diagrama y qué queda fuera. Los componentes de tu equipo van dentro del límite; un proveedor de pagos, un proveedor de identidad o el servicio de otro equipo quedan fuera. Muestra cada sistema externo como una sola caja: su interior no te toca dibujarlo.

2. Lista los componentes

Haz una lista antes de dibujar: servicios, bases de datos, colas, cachés, APIs externas, tipos de usuario. Usa los nombres que el equipo usa de verdad; si coinciden con el nombre del repo o del deployment, mejor. Si la lista es demasiado larga para abarcarla de un vistazo, probablemente tienes material para dos diagramas.

3. Dibuja las relaciones con flechas dirigidas y etiquetadas

Una línea sin etiqueta solo dice que dos cosas están «relacionadas de algún modo». Dale a cada flecha una dirección y al menos dos datos: protocolo e intención. Añade sync o async cuando importe.

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

La flecha va de quien llama a quien recibe. No dibujes una segunda flecha para la respuesta: duplica las líneas sin aportar nada. Si el orden de peticiones y respuestas importa, para eso está el diagrama de secuencia.

4. Agrupa con frames

Los grupos son la segunda capa de lectura. Mete los componentes en límites que signifiquen algo:

• Zonas de red: subred pública, subred privada, DMZ, red on-premise
• Namespaces de Kubernetes: payments, platform, observability
• Regiones y cuentas: eu-central-1, us-east-1, cuentas de prod y staging
• Límites de confianza: dónde se autentica el tráfico que llega de internet

Puedes anidar (región > VPC > subred), pero cada nivel extra hace el diagrama más difícil de leer.

5. Añade una leyenda

Si un color, un tipo de línea o un icono significa algo, la leyenda tiene que decirlo. ¿Una línea discontinua es un mensaje async? ¿Un marco rojo es el alcance PCI? Lo que es obvio para quien lo dibujó no lo es para quien lo lee seis meses después.

6. Añade título, fecha y responsable

Pon tres datos en una esquina de cada diagrama: un título que diga qué muestra («Checkout — vista de containers, prod»), la fecha de la última actualización y el equipo responsable. Nadie sabe si un diagrama sin fecha está al día, y nadie actualiza un diagrama sin responsable.

7. Revísalo con alguien que no lo haya dibujado

Enséñale el diagrama a alguien que no lo haya dibujado y hazle la pregunta que escribiste al principio. Si encuentra la respuesta sin que se la expliques, el diagrama funciona. Si no paras de decir «aquí lo que quería decir es…», mete esa explicación en el propio diagrama.

Errores comunes

• Meterlo todo en un diagrama. Contexto, despliegue y detalle de red en una sola imagen: al final no se lee nada.
• Flechas sin etiqueta o de doble sentido. No queda claro quién llama a quién, que es justo lo que se busca durante un incidente.
• Niveles de abstracción mezclados. Si una caja es «Sistema de pagos» y la de al lado «pod de Redis», el lector pierde la escala.
• Colores sin explicar. Los colores que no están en la leyenda son decoración o se malinterpretan.
• Sin responsable ni fecha. Un diagrama en la wiki sin autor conocido acaba siendo una fuente de información errónea.

Mantener el diagrama al día

Un diagrama solo sirve mientras la gente confía en él. Algunos hábitos ayudan:

• Guarda el diagrama cerca de la documentación del sistema y enlázalo desde el README o el runbook.
• Añade «¿diagrama actualizado?» a la checklist de los pull requests que cambian la arquitectura.
• Conserva una revisión antes de cambios grandes, para que «¿cómo era el trimestre pasado?» tenga respuesta.
• Agenda una revisión periódica en el calendario del equipo responsable, por ejemplo una vez por trimestre.

Cómo hacer un diagrama de arquitectura de software en Archboard

Archboard es un espacio de trabajo de arquitectura alojado en la nube para equipos de plataforma y de producto. Los pasos anteriores sirven con cualquier herramienta; en Archboard se ven así:

1. Inicia sesión. Entra desde la página de inicio de sesión con Google o GitHub. El primer inicio de sesión crea tu cuenta y tu organización; no hace falta tarjeta de crédito.
2. Elige tus packs. Archboard tiene 27 packs integrados con 223 tipos de nodos. Para un primer diagrama suelen bastar estos:
   • C4 Model: Person, Software System, Container, Component, Database y boundaries, para vistas de contexto y de containers.
   • Kubernetes: Namespace (se dibuja como frame), Deployment, Pod, Service, Ingress, ConfigMap, Secret, PVC, HPA, NetworkPolicy y más.
   • Cloud: para infraestructura cloud, con un nodo k8s-cluster para mapas multicuenta.
   • Network: para zonas de red y enlaces.
3. Conecta puertos. Los nodos son nodos de primera clase con puertos, no formas genéricas. Arrastra una conexión de puerto a puerto y etiquétala con protocolo e intención.
4. Agrupa con frames. Usa el Frame del pack Core para zonas de red y regiones, el Namespace de Kubernetes para namespaces y los boundaries de C4 para el límite del sistema.
5. Añade título y leyenda. Pon un bloque Markdown o una Table en el canvas para tener título, fecha, responsable y leyenda en un mismo sitio.
6. Comparte. Envía el enlace público a quien vaya a revisarlo (con la marca de Archboard en Free). En Pro y Enterprise puedes incrustar el diagrama en tu sitio de documentación con un iframe.
7. Exporta. Exporta en SVG o PNG (con marca de agua en Free); Pro añade JPEG, PDF y GIF / WebM animados, todo sin marca de agua. También puedes exportar el documento del diagrama como JSON estructurado.

Los cambios se guardan automáticamente y cada diagrama conserva revisiones: las 5 últimas en Free, un año de historial en Pro y un historial sin límite de tiempo en Enterprise. Free incluye todos los packs integrados, 3 diagramas y 15 nodos de diagrama más 150 notas, textos, pegatinas y temas de mapa mental por diagrama, de sobra para un primer diagrama de contexto; Pro desbloquea diagramas y nodos ilimitados para mapas de despliegue completos. Consulta los detalles en precios.

Antes de empezar, recorre la galería de ejemplos: abre un ejemplo público y cópialo a tu espacio de trabajo con Usar este ejemplo (cuenta en tu cuota de diagramas). Para detalles de C4 y Kubernetes, consulta las páginas del caso de uso C4 y del caso de uso Kubernetes. Las primeras ideas también pueden empezar en el mismo canvas: Archboard tiene sticky notes y mapas mentales junto a los packs de arquitectura.

Checklist y preguntas frecuentes

Antes de publicar:

• El lector y la pregunta están por escrito
• El límite está claro y los sistemas externos son cajas únicas
• Cada flecha tiene dirección y etiqueta de protocolo + intención
• Los grupos muestran límites reales: zonas de red, namespaces, regiones
• Hay leyenda, título, fecha y responsable
• Alguien que no lo dibujó pudo responder la pregunta

¿Qué diferencia hay entre un diagrama de arquitectura y un diagrama de flujo? Un diagrama de arquitectura muestra estructura: qué componentes existen y cómo se conectan. Un diagrama de flujo (flowchart) muestra los pasos y puntos de decisión de un proceso. Si importa el orden de una petición en el tiempo, usa un diagrama de secuencia.

¿Cuántos diagramas debería hacer? Uno por cada par lector-pregunta. Para la mayoría de sistemas, un diagrama de contexto, uno de containers y uno de despliegue son un buen comienzo.

¿Qué herramienta debería usar? Una que conozca los conceptos que dibujas. Archboard ofrece los conceptos de Kubernetes, C4 y cloud como nodos listos con puertos, así que tu diagrama se mantiene legible y fácil de actualizar. Elijas lo que elijas, la prueba real es si el diagrama responde a tu pregunta.

Empieza gratis — un seat, sin tarjeta de crédito.