Diagramas de arquitectura estilo AWS
Resumen
Produce diagramas que siguen las convenciones de los diagramas de arquitectura de referencia de AWS: nombres de servicios precisos, límites de cuenta/Región/VPC etiquetados, etiquetas de flujo cortas y un lienzo sin desorden. "Estilo AWS" describe esas convenciones; no requiere por sí mismo iconos oficiales de AWS ni Graphviz.
Mermaid y Graphviz DOT son formatos de autoría equivalentes. Mermaid suele ser adecuado para documentación en línea, que admite temas y es revisable en texto; DOT suele ser adecuado para activos de iconos AWS locales exactos, composición controlada y SVG/PNG listos para presentación. Usa uno cuando satisfaga el contrato de entrega completo y ambos cuando audiencias o artefactos distintos justifiquen el mantenimiento adicional.
Cuándo usarlo
Usa esta habilidad para diagramas de arquitectura AWS respaldados por evidencia, topología, contexto de sistema o flujo de datos. No la uses para un visual que no sea de AWS o cuando una tabla por sí sola comunique más claramente los hechos solicitados.
Racionalizaciones comunes
- "Estilo AWS significa DOT" ignora los renderizadores de Mermaid que cumplen con el contrato real.
- "Ambos formatos son más seguros" crea costos de sincronización sin dos consumidores nombrados.
- "El servicio probablemente se conecta aquí" no es evidencia para un borde.
Banderas rojas
Detente y resuelve recursos o relaciones no compatibles, un renderizador objetivo ambiguo, derechos o activos de iconos faltantes, evidencia fuente conflictiva, o una Región solicitada fuera del ámbito autorizado antes de dibujar o consultar infraestructura en vivo.
La regla que supera la estética
Dibuja solo lo que la fuente establece. Cada nodo, borde, límite, Región y protocolo debe rastrearse hasta algo real: Terraform, CloudFormation, CDK, configuración desplegada o una declaración escrita del propietario. Un diagrama es un artefacto de evidencia que resulta ser visual.
Nunca agregues un servicio, conexión, Zona de Disponibilidad, VPC o Región porque la imagen se ve desequilibrada sin él. Si la fuente no establece un límite, déjalo fuera; un diagrama honesto y disperso supera a uno decorativo y completo. Cuando algo está desplegado pero deshabilitado, indícalo en el nodo (WEB_PUSH_ENABLED=false, "Desplegado, deshabilitado en lanzamiento") en lugar de dibujarlo como si estuviera activo, y marca lo que pertenece a otro equipo para que un lector no piense que lo controlas.
Indica la procedencia en el propio diagrama: un subtítulo que nombre la fuente, como "rastreado a <iac-dir>/*.tf en <revision>" o "inventario de solo lectura en vivo, <fecha>" — y repítelo en un comentario de encabezado en la fuente DOT.
Nombra el recurso, no solo el servicio
Un icono de servicio por sí solo no identifica nada. Un glifo de DynamoDB de color magenta etiquetado como "Operaciones" podría ser una tabla, un flujo o un índice, y un lector no tiene forma de encontrarlo en la consola. Cada nodo declara tres hechos:
- Cómo se llama en AWS. El nombre real desplegado —
acme-orders-events, no un alias amigable como "Pedidos". Escribe un ID de cuenta como<cuenta>en lugar de los dígitos; nunca pongas un secreto, token o endpoint en un diagrama. - Qué tipo de recurso es. Escrito, en gris, debajo del nombre: "tabla DynamoDB", "bucket S3", "función Lambda", "API HTTP de API Gateway", "WAFv2 web ACL", "identidad de correo SES v2".
- Para qué sirve. Una línea, y solo donde un lector no pueda inferirlo.
Para salida de Graphviz, usa un icono de recurso donde AWS publique uno — Res_Amazon-DynamoDB_Table, Res_Amazon-Simple-Storage-Service_Bucket, Res_AWS-Lambda_Lambda-Function — y un icono de servicio (Arch_) para todo lo demás. El icono refuerza la identidad; nunca debe ser lo único que la lleve, porque un icono no es legible en escala de grises, en tamaño miniatura ni por un lector de pantalla.
Elige el formato según los requisitos
No hay un ganador global ni un formato predeterminado. Respeta un formato fuente solicitado explícitamente a menos que entre en conflicto con otro criterio de aceptación. De lo contrario, compara las necesidades reales de entrega:
| Requisito | Mermaid suele ser mejor | Graphviz DOT suele ser mejor |
|---|---|---|
| Revisión en repositorio | Renderizado Markdown en línea, diferencias textuales compactas | Fuente textual revisable más artefactos renderizados por separado |
| Tipo de diagrama | Secuencia, flujo, estado, dependencia y vistas de arquitectura sencillas | Topología densa, límites anidados y gráficos que necesitan enrutamiento deliberado de bordes |
| Visuales AWS | Nombres, límites, colores estilo AWS o paquetes de iconos proporcionados por el renderizador | Activos de iconos AWS publicados exactos y locales en el repositorio |
| Diseño | Diseño responsivo gestionado por el renderizador y adaptación de tema | Rangos precisos, puertos, clústeres, espaciado y composición fija |
| Entrega | Documentación que debe renderizarse donde se escribe | SVG/PNG controlados para presentaciones, documentos y superficies de presentación |
| Herramientas | El renderizador objetivo ya soporta la sintaxis y versión de Mermaid requeridas | Graphviz y los activos locales requeridos están disponibles en el entorno de construcción o autoría |
Si el contenido solicitado es realmente tabular, usa una tabla Markdown en lugar de convertirlo en una imagen. Para un intercambio ordenado de participantes, sequenceDiagram de Mermaid suele ser el ajuste natural; esto es una ventaja de tipo de diagrama, no una preferencia general por Mermaid.
Mermaid soporta diagramas de arquitectura y paquetes de iconos configurables, pero no se puede asumir que un renderizador alojado proporcione activos AWS locales, registro de paquetes personalizados o la misma versión de Mermaid que un renderizador local controlado. Graphviz puede cargar activos de imagen locales directamente, por lo que es la elección confiable cuando los activos de iconos exactos y la composición exportada fija son criterios de aceptación, no solo porque la solicitud diga "estilo AWS".
Cuenta las compensaciones de ambos lados. Mermaid puede variar entre versiones de renderizadores, paquetes de iconos disponibles y temas del host. DOT agrega un paso de renderizado y artefactos generados que deben permanecer sincronizados con la fuente editable. Selecciona el formato cuyos costos coincidan con el repositorio y el destino, en lugar de tratar las fortalezas de cualquiera de las herramientas como universales.
Si el soporte del renderizador, la fidelidad de los iconos, la composición fija o los archivos de salida esperados cambiarían materialmente el resultado y la solicitud es ambigua, aclara el contrato de entrega. De lo contrario, selecciona el formato que satisfaga los requisitos conocidos con la menor maquinaria específica del proyecto.
Cuando se seleccione Mermaid, conserva las reglas de evidencia, procedencia, nomenclatura de recursos y accesibilidad anteriores, valida la fuente en su renderizador objetivo y detente antes del flujo de trabajo específico de Graphviz a continuación.
Cuando ambos formatos están justificados
Produce Mermaid y DOT cuando satisfagan diferentes requisitos reales, como revisión en línea del repositorio más salida de presentación exacta con iconos AWS. La entrega dual no es automáticamente mejor: está justificada solo cuando ambos artefactos tienen un consumidor nombrado o un criterio de aceptación.
Ninguna fuente es canónica por defecto. Deriva ambas del mismo inventario verificado de recursos y relaciones, lleva la misma procedencia y verifica que los nodos, bordes, límites, Regiones, propiedad e incertidumbre coincidan. Un formato puede agregar estructura específica de presentación sin cambiar la arquitectura que afirma. Nombra un formato como autoritativo solo cuando el usuario o la política del repositorio le asignen explícitamente ese rol.
Para un mapa de sistema completo inusualmente denso que necesite iconos AWS exactos, composición fija o colocación de conectores a nivel de puerto, DOT junto con su SVG y PNG pueden servir como el artefacto de presentación e iconos AWS. Una representación de Mermaid puede servir como el acompañante mantenible y revisable en línea cuando eso también sea requerido. Para un flujo enfocado sin esos requisitos específicos de DOT, Mermaid solo puede satisfacer el contrato. Estas son elecciones basadas en requisitos, no una razón para producir ambos formatos para cada diagrama.
Flujo de trabajo de Mermaid
1. Selecciona el tipo de diagrama de Mermaid
Usa architecture-beta o un diagrama de flujo para arquitectura y topología, un sequenceDiagram para intercambios ordenados y un diagrama de estado solo para transiciones de estado reales. Confirma que el renderizador objetivo soporte la sintaxis seleccionada y cualquier paquete de iconos; no asumas que GitHub, un sitio de documentación y un CLI de Mermaid local ejecutan la misma versión o configuración. Cuando uses símbolos de Iconify, mantén el nombre completo del recurso AWS y el tipo en texto; un icono nunca debe ser el único identificador del recurso.
2. Codifica el inventario verificado
Representa los límites de cuenta, Región, VPC, Zona de Disponibilidad, subred y propiedad de AWS solo cuando la evidencia los establezca. Usa nombres y tipos de recursos completos, bordes etiquetados cortos y anotaciones visibles para relaciones permitidas o inferidas. Mantén la procedencia en Markdown cercano y, cuando la sintaxis lo permita, en un comentario de fuente.
3. Renderiza e inspecciona en el entorno objetivo
Usa el comando de Mermaid fijado del repositorio o la compilación de documentación. Valida el bloque delimitado exacto o la fuente .mmd que se enviará, luego inspecciona el resultado renderizado en su ancho y tema previstos. Verifica etiquetas recortadas, bordes superpuestos, iconos o sintaxis no compatibles, contraste inaccesible y desviación semántica del inventario verificado. Corrige la fuente editable y vuelve a renderizar hasta que sea legible.
Registra explícitamente los paquetes de iconos no integrados. Para el CLI de Mermaid, una representación reproducible de símbolos AWS puede usar:
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
Trata un fallback ? como un renderizado fallido, no una degradación cosmética. El soporte de paquetes de iconos puede variar según la versión de Mermaid y el renderizador de diseño; verifica la salida real visual y estructuralmente. Si un renderizador compatible pierde iconos registrados, usa otro renderizador compatible que los preserve y documenta la compensación de diseño. No reclames portabilidad en línea a menos que el host objetivo también registre el paquete requerido.
4. Entrega los artefactos requeridos
Mantén Mermaid en línea cuando ese sea el contrato del repositorio. Cuando se requieran salidas SVG o PNG independientes, renderízalas de forma determinista con la versión de Mermaid fijada del repositorio y documenta el comando de reproducción.
Flujo de trabajo de Graphviz
1. Establece la arquitectura desde la fuente
Lee la IaC e inventaria lo que realmente existe antes de dibujar nada. Encuentra el directorio donde este proyecto lo mantiene — infra/, terraform/, deploy/, una aplicación CDK — en lugar de asumir un diseño:
iac_dir=infra # lo que este repositorio realmente use
grep -hoE '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
Luego extrae los detalles que hacen reales los bordes y los nombres que van en los nodos: nombres de funciones, nombres de tablas, nombres de buckets, reglas de eventos y sus horarios, notificaciones de S3, autorizadores y cualquier concesión entre cuentas o entre stacks. Resuelve los nombres a través de sus variables y locales hasta el valor realmente desplegado. Anota la Región desde la variable que la establece, no desde una suposición.
1b. Cuando no hay IaC, o la IaC es solo parte del patrimonio
A veces, lo que hay que diagramar es una cuenta en ejecución para la que nadie tiene Terraform, o Terraform cubre solo una fracción de lo que está desplegado. Entonces, la fuente es la cuenta en vivo, de solo lectura, y el diagrama debe ser explícito sobre que eso es lo que es.
Comienza desde un predicado de etiqueta en lugar de un barrido servicio por servicio, porque es la única forma de delimitar "qué pertenece a este sistema":
aws resourcegroupstaggingapi get-resources --region <region> \
--tag-filters 'Key=<clave>,Values=<v1>,<v2>'
Varias claves de etiqueta necesitan una solicitud cada una, unidas por ARN después — pasar dos claves en una solicitud aplica Y, eliminando silenciosamente todo lo que lleva solo una de ellas. Registra el conteo y la fecha resultantes; es una instantánea, no un hecho.
La API de etiquetado no devuelve todos los tipos de recursos, y las etiquetas no son propiedad. Por lo tanto, la consulta de etiquetas te da el conjunto de nodos, y las relaciones provienen de las APIs que realmente las modelan:
| Para establecer | Lee |
|---|---|
| Cableado de entrada | elbv2 describe-load-balancers, describe-target-groups |
| Qué rutas están permitidas | ec2 describe-security-groups, describe-vpcs |
| Qué puede llamar un nivel de cómputo | iam get-instance-profile, luego get-policy-version |
| Forma y réplicas del nivel de datos | rds describe-db-instances, elasticache describe-* |
| Cableado asíncrono | políticas de redrive de colas, notificaciones de S3, reglas de eventos |
Resuelve cada CIDR que encuentres a una VPC nombrada antes de dibujarlo; un 10.16.0.0/16 no resuelto en un diagrama no le dice nada a un lector.
1c. Di en qué tipo de evidencia descansa cada borde
Esto es más importante al leer una cuenta en vivo, donde es tentador dibujar una línea porque dos recursos comparten un prefijo de nombre. Separa las clases visualmente y defínelas en el diagrama y su prosa:
- Cableado que AWS mismo informa — los destinos de un grupo de destino, la fuente de una réplica. La clase más fuerte; AWS está modelando la relación por ti.
- Una ruta que algo permite — una regla de grupo de seguridad, una política de bucket. Esto establece que una llamada puede ocurrir, no que ocurra. Anota cuando una regla tiene alcance CIDR en lugar de alcance de grupo de seguridad: autoriza un rango completo, no la única carga de trabajo a la que dibujaste la flecha.
- Una concesión que una identidad posee — una declaración de política de IAM. Misma precaución, además de que la concesión no es el permiso efectivo hasta que se evalúen SCP, límites de permiso y políticas de recursos.
- Inferencia de nombres o etiquetas — dibuja con línea discontinua, etiqueta con la incertidumbre, o déjalo fuera. Nunca sólido.
La ausencia también es un hallazgo que vale la pena dibujar. Cuando un rol que "obviamente" habla con una cola resulta no tener ninguna acción sqs:* en absoluto, un nodo que lo diga es más útil que una flecha faltante, porque elimina la suposición incorrecta en lugar de dejarla...