Cómo leer una página de arquitectura

Objetivo

Al terminar sabrás abrir cualquier página de /arquitecturas/, entender qué muestra cada pestaña y reproducir un flujo para contarte, paso a paso, qué hace el sistema en un caso concreto. Usaremos como ejemplo la página de claude-kit, que tiene 12 contenedores, 18 llamadas y 4 flujos.

Por qué

Un diagrama de cajas y flechas dice qué está conectado con qué, pero no en qué orden ni para qué. Quien lo mira reconstruye la historia de memoria y casi siempre la reconstruye mal. Las páginas de arquitectura viva resuelven eso con dos ideas: un diagrama de contenedores al estilo C4 (cada caja se despliega por separado) y flujos que se animan sobre ese mismo diagrama. Cada llamada dibujada corresponde a código que se puede señalar, así que lo que ves es lo que el proyecto hace, no lo que se quisiera que hiciera.

Pasos

1. Abre una página. Entra a /arquitecturas/ y elige una tarjeta. Cada tarjeta indica cuántos contenedores, llamadas y flujos tiene el proyecto y en qué máquinas corre. Empieza por una pequeña.
2. Mira primero la pestaña de contenedores (C4). Los actores quedan a la izquierda; los almacenes y servicios externos, a la derecha. El color indica de quién es la pieza: propia del proyecto, propia pero de otro repositorio, o externa. Una caja con borde punteado existe fuera del proyecto.
3. Haz clic en una caja. Aparece su ficha: qué responsabilidad tiene, con qué tecnología está hecha y datos como la máquina donde corre, sus entradas y sus salidas. En claude-kit, por ejemplo, la caja de la barra de estado explica que recibe el JSON de la sesión por stdin y devuelve texto.
4. Lee las flechas. Cada línea es una llamada con su etiqueta: protocolo y lo que viaja (por ejemplo, git pull --ff-only). Una línea punteada marca un adaptador elegido por configuración.
5. Reproduce un flujo. Sobre el diagrama están los botones “reproducir flujo”, uno por caso de uso. Al pulsar uno, la llamada de cada paso se enciende y viaja un paquete de origen a destino. A la derecha aparecen los pasos numerados; el activo corresponde a la llamada encendida.
6. Distingue pasos, respuestas y notas. En la pestaña de secuencias el mismo flujo se dibuja como diagrama UML. Una flecha continua con su etiqueta es la llamada. Una flecha punteada, sin etiqueta, es la respuesta (de destino a origen). Un paso que le ocurre a una sola caja aparece como un bucle sobre su línea de vida y la caja pulsa en el C4. Una nota ámbar abarca varias líneas de vida y resalta las cajas implicadas. La numeración salta las notas.
7. Revisa las pestañas restantes. Solo existen si aportan: estados (una máquina de estados con el camino feliz y las transiciones de error en rojo y punteado), datos (entidad-relación o estructura de carpetas, con el linaje cuando el proyecto lo tiene), despliegue y decisiones con la alternativa descartada. Si una pestaña falta, es porque el proyecto no tiene ese aspecto, no porque se olvidó.
8. Pruébala en el móvil. Por debajo de 600 px de ancho, las secuencias dejan de ser un diagrama y se muestran como una lista vertical numerada con el formato origen → destino: texto. El mismo reproductor la ilumina paso a paso.