Diagrama de Arquitectura
Un diagrama se entiende cuando lo que muestra encaja en lo que el lector ya sabe. Un desarrollador senior lo lee para el flujo de alto nivel y para las uniones. Un bloque es una caja negra: su patrón de diseño, de qué es responsable, quién lo posee, y su interior oculto. Lo que un bloque ofrece a otro a través de una unión es su interfaz: operaciones con tipos de parámetros y retorno, errores, los tipos de datos que la cruzan con sus campos, y un ejemplo de qué cruza exactamente y cómo se ve. El transporte (REST, OPC UA, inicio de un proceso) es un atributo de una interfaz y nunca la sustituye.
Lee EXAMPLE.md antes de dibujar: un cambio completo, en ambas formas.
Pasos
1. Las palabras del lector
Un término nuevo no encaja en nada. Antes que nada, recoge las palabras que el lector ya tiene: de sus mensajes en esta conversación, de los documentos que escribió (instrucciones del proyecto, páginas de arquitectura, glosarios, tablas de nomenclatura), y de cada modelo con el que se compara el diagrama. Escribe la lista de palabras: la cosa, la palabra del lector para ella, la palabra de cada otra parte que leerá el diagrama, el nombre en el código, y la palabra que usa el diagrama.
- Etiqueta cada bloque e interfaz con la palabra del lector; el nombre del código se coloca al lado.
- Donde dos palabras choquen, o una palabra se use para la cosa equivocada, elige una, di por qué en la lista de palabras, y nombra la otra a su lado una vez.
- No acuñes nada. Una interfaz sin nombre en el código se llama por sus dos extremos,
Frontend -> Backend. - Empieza desde la imagen que el lector ya tiene, su propio diagrama con sus niveles y nombres, y coloca lo nuevo dentro de ella.
Hecho cuando cada etiqueta en un diagrama proviene de la lista de palabras, y cada término nuevo para el lector está en el glosario junto a la palabra conocida a la que pertenece.
2. Preguntas
Escribe las preguntas del lector, una línea cada una. Ellos eligen las vistas.
| Pregunta | Vista |
|---|---|
| ¿Cuáles son las partes, de qué es responsable cada una, quién la posee, quién llama a quién? | vista de bloques constructivos |
| ¿Qué interfaz une dos partes, y qué cruza exactamente por ella? | la interfaz, sus tipos de datos y un ejemplo en cada unión |
| ¿Qué sucede, en qué orden, en el escenario que importa? | vista de tiempo de ejecución: una secuencia |
| ¿Dónde se ejecuta cada parte? | host: en cada bloque; una vista de despliegue cuando las redes o los límites de confianza son la pregunta |
| ¿Qué hace un cambio, o cómo difieren dos diseños? | cada estado en la misma forma, luego las diferencias |
Hecho cuando cada vista tiene su pregunta y la pregunta está sobre ella como su título.
3. Catálogo
Llena cuatro listas a partir de las fuentes antes de dibujar.
- Bloques: la palabra del lector y el nombre en el código, estereotipo, una frase de responsabilidad, propietario, host.
- Interfaces, una por unión: proveedor, consumidores, cada operación como una firma
nombre(param: Tipo) -> Tipo, errores, transporte. - Tipos de datos: cada tipo que nombra una firma, con sus campos, unidades y valores por defecto.
- Ejemplos, uno por interfaz: un mensaje tal como cruza, llamada y respuesta en su formato real: una línea de comandos con su salida, un cuerpo JSON, una fila de tabla. Tómalo de una ejecución, una grabación, un fixture o los datos. Un ejemplo armado a partir del código lo dice en su primera línea.
Cada entrada lleva su origen: una referencia de código ruta:línea, o una etiqueta (abajo). Un estado dibujado por otro, un archivo de modelo o un boceto, se reproduce tal como está y en sus propias palabras; lo que omite se etiqueta como [indefinido], y lo que añades va a un estado propio.
Hecho cuando cada bloque tiene su frase, cada unión una interfaz cuyas firmas están copiadas del código o etiquetadas, cada tipo en una firma sus campos, cada interfaz su ejemplo, y cada entrada una referencia o una etiqueta.
4. Nivel
Los bloques de un estado son pares: unidades que se despliegan, poseen o reemplazan por sí solas, de cinco a nueve de ellas. Archivos, funciones y los pasos dentro de un bloque son su interior. Un zoom es un diagrama adicional un nivel más abajo, dibujado para el bloque del que trata la pregunta.
Hecho cuando ningún bloque de un estado está dentro de otro, y cada zoom nombra la pregunta que lo justifica.
5. Forma
- Forma de chat, hasta 78 columnas: la vista de bloques constructivos con el nombre de la interfaz y su firma principal en cada borde, luego el catálogo como tablas y los ejemplos como bloques de código. Para un estado o un cambio pequeño.
- Forma de lienzo, una página HTML estática de diagramas de texto tan anchos como necesiten: junto a cada borde su interfaz completa, el ejemplo, y los tipos de datos con sus campos. Para varios estados, o cuando se muestren más de tres uniones en su totalidad. La página es construida por un script generador que se encuentra al lado; la respuesta del chat nombra el archivo, dice en unas pocas frases qué muestra la comparación y enumera las decisiones abiertas.
- Forma C4, el mismo modelo dibujado con LikeC4 en una página con una pestaña por estado, cajas en las que se puede hacer clic y hacer zoom. Los diagramas de texto son su prototipo: asienta palabras, bloques, interfaces y ejemplos allí primero, luego renderiza. Para un resultado que otras personas abrirán. Lee LIKEC4.md.
6. Dibujar
Dibuja con los tres archivos en esta carpeta, para que las cajas se alineen y ninguna fila sea más ancha que su lienzo. La documentación de cada archivo es su manual, y ejecutarlo imprime una demo.
| Archivo | Proporciona |
|---|---|
grid.py | Grid (cajas con compartimentos, líneas, flechas), sequence (una vista de tiempo de ejecución), table |
canvas.py | glance (cada estado en una línea), overview (estados lado a lado, una fila por nivel), panel (un estado: bloques, interfaces con ejemplos, tipos de datos) |
page.py | html_page: la página alrededor de los diagramas, con los colores y los enlaces entre ids |
likec4/ | para la forma C4: template.c4, build.sh, la página de pestañas index.html con tabs.js, y clicktest.py |
Una página va desde la imagen de diez segundos hasta el detalle: de un vistazo, la lista de palabras, la guía de lectura, la vista general, un panel por estado, las diferencias por unión como tabla, las decisiones abiertas, glosario, fuentes.
7. Verificar
- Cada caja es un bloque del catálogo, cada borde una interfaz, cada caja de tipos un tipo de datos; una entrada omitida de un diagrama se omite a propósito.
- Cada referencia de código se resuelve: el archivo existe y la línea muestra el nombre.
- El mismo bloque está en el mismo lugar en cada estado. Un bloque que falta en un estado es una caja punteada allí.
- Capturas de pantalla de toda la página, leídas baldosa por baldosa: los bordes coinciden, nada está cortado, los colores llevan su significado.
- Las fuentes nombran lo que se leyó, en qué commit, qué ejemplos son reales, y qué no se leyó.
Estados
Un estado es el código tal como está, un objetivo dibujado por alguien, o una propuesta. Compara estados por posición: el mismo bloque en la misma columna de glance y la misma fila de overview, para que los vacíos de dos estados muestren dónde se complementan.
Una unión tiene un id de una letra para su estado y un número, (I4). Una interfaz o tipo de datos definido en una unión se referencia por ese id en cualquier otro lugar; sus campos se escriben una vez.
Las diferencias son una tabla con una fila por unión y una columna por estado. Las decisiones abiertas son una tabla: la pregunta, las opciones, quién decide.
Etiquetas y estereotipos
| Etiqueta | Significado |
|---|---|
[código] | existe en el código; la referencia está al lado |
una etiqueta de fuente, ej. [c4] | indicado por un modelo fuente; nombra la etiqueta en la guía de lectura |
[propuesto] | propuesto aquí, no existe en ningún lado aún |
[nuevo] [cambiado] [movido] | lo que hace un cambio, cuando solo hay estado actual y estado futuro |
[indefinido] | el estado lo deja abierto |
[?1] | una decisión abierta, listada con su número |
Los estereotipos nombran el patrón de diseño que juega un bloque: <<interfaz de usuario>>, <<cliente>>, <<puerta de enlace>>, <<fachada>>, <<servicio>>, <<puerto>>, <<adaptador>>, <<repositorio>>, <<externo>>. Usa uno donde el código juegue ese rol; un bloque sin estereotipo es mejor que uno con uno incorrecto. Un puerto es una interfaz que el consumidor posee y el proveedor implementa: <<puerto>> está en la interfaz, <<adaptador>> en el bloque que la implementa. Los tipos propios de un modelo fuente se citan como los escribe.
Dispositivos de explicación
Cada uno de estos merece su lugar al responder algo que el lector de otro modo tendría que preguntar. Úsalos con moderación.
- Guía de lectura: un pequeño diagrama que muestra cómo se lee un panel, y las etiquetas.
- Referencias de código: en cada interfaz y tipo de datos, para que el lector pueda buscarlas.
- Textos cortos: un párrafo sobre un estado que dice lo único que hay que ver en él; una nota dentro de una caja de interfaz donde el lector preguntaría por qué.
- Glosario: los términos que la lista de palabras no cubre, una línea cada uno.
- Color: solo para las etiquetas, los ids, y uno o dos nombres
claveque se mantienen iguales en todos los estados. El color marca lo que los estados comparten y dónde difieren; nada más se colorea.
La prosa está en el idioma de la conversación. Los nombres del código y de los modelos fuente se mantienen textuales.