# Diagramas C4 como texto: el formato del curso

En el curso los diagramas de arquitectura se escriben como texto, en
Markdown, un archivo por diagrama dentro de `docs/c4/`. Un diagrama es **dos
tablas**: la de elementos (las cajas) y la de relaciones (las flechas). Se
leen en GitHub sin instalar nada, se revisan en un pull request línea por
línea, y un programa puede comprobar que no les falte nada:
[`check-c4.ts`](check-c4.ts).

El formato sirve para los tres primeros niveles de C4. La semana 1 usa el de
contexto y el de contenedores; el de componentes llega con P1 y se trabaja a fondo en la semana 7.

## Un archivo

```markdown
# Qillqa: diagrama de contexto

- Nivel: contexto
- Sistema: Qillqa

Dos o tres líneas en prosa: qué es el sistema y qué muestra este diagrama.

## Elementos

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Lector | persona | Estudiante o docente que busca libros y renueva sus préstamos | — |
| Qillqa | sistema | Catálogo, reservas y préstamos de la biblioteca | Aplicación web con una API en Node.js y PostgreSQL |

## Relaciones

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Lector | Qillqa | Busca libros, reserva y renueva sus préstamos | HTTPS, desde el navegador |
```

Los ejemplos completos están en [`example/context.md`](example/context.md) y
[`example/containers.md`](example/containers.md). Los archivos de partida
para su propio sistema, en [`lab/`](lab/).

## Las partes

| Parte | Qué lleva |
|---|---|
| Título (`# ...`) | Qué sistema y qué diagrama. Es lo primero del archivo. |
| `Nivel:` | `contexto`, `contenedores` o `componentes`. |
| `Sistema:` | El nombre del sistema que se describe. |
| `Contenedor:` | Solo en el nivel de componentes: el contenedor que el diagrama abre. |
| Prosa | Opcional, donde quieran. El revisor no la lee. |
| `## Elementos` | Una tabla con las columnas **Nombre, Tipo, Descripción, Tecnología**, en ese orden. Una fila por caja. |
| `## Relaciones` | Una tabla con las columnas **De, Hacia, Qué viaja, Protocolo**, en ese orden. Una fila por flecha. |

Las líneas `Nivel:`, `Sistema:` y `Contenedor:` pueden ir con o sin el guion
de lista. Si una celda necesita una barra vertical, se escribe `\|`.

### Tipos de elemento

| Tipo | Qué es | Niveles donde aparece |
|---|---|---|
| `persona` | Alguien que usa el sistema, nombrado por su papel (Lector, no "Usuario") | todos |
| `sistema` | El sistema que se describe, como una sola caja | contexto |
| `sistema externo` | Un sistema del que el nuestro depende o que depende del nuestro, y que no construimos ni operamos | todos |
| `contenedor` | Algo que tiene que estar corriendo para que el sistema funcione: un servidor, una aplicación en el navegador, un programa que corre cada noche. No es un contenedor de Docker | contenedores, componentes |
| `almacén de datos` | Algo que guarda datos por separado: una base de datos, una carpeta de archivos, una cola en disco | contenedores, componentes |
| `componente` | Una parte de un contenedor, con una responsabilidad y una interfaz | componentes |

## Las reglas

`check-c4.ts` revisa estas reglas. Entre corchetes, el nombre con el que
aparece cada una en su salida.

**Forma del archivo**

1. `[titulo]` El archivo empieza con un título de nivel 1.
2. `[nivel]` Tiene la línea `Nivel:` con uno de los tres niveles.
3. `[sistema]` Tiene la línea `Sistema:` con el nombre del sistema.
4. `[tabla-elementos]` Tiene la sección `## Elementos` con su tabla, con las
   cuatro columnas del formato, y al menos una fila.
5. `[tabla-relaciones]` Tiene la sección `## Relaciones` con su tabla, con las
   cuatro columnas del formato, y al menos una fila.

**Elementos**

6. `[nombre]` Todo elemento tiene nombre, y no hay dos con el mismo nombre
   (no se distinguen mayúsculas).
7. `[tipo]` El tipo es uno de la tabla de arriba y corresponde al nivel del
   diagrama: una tabla de la base de datos no va en un diagrama de
   contenedores, ni un contenedor en uno de contexto.
8. `[descripcion]` Todo elemento tiene una descripción que dice qué es o de
   qué es responsable: una frase, no el nombre repetido ni dos palabras
   ("Base de datos").
9. `[tecnologia]` Todo elemento que no es una persona dice con qué tecnología
   está hecho. De un sistema externo se escribe lo que se sabe: cómo se llega
   a él ("API REST de la oficina de registro"). Una persona lleva `—`.
10. `[suelto]` Todo elemento participa en al menos una relación. Una caja a
    la que no llega ni de la que sale ninguna flecha sobra, o le falta la
    flecha.

**Alcance del nivel**

11. `[alcance]` Un diagrama de **contexto** tiene exactamente un elemento de
    tipo `sistema`, y se llama como dice la línea `Sistema:`. En uno de
    **contenedores** el sistema ya no aparece como caja (aparecen sus partes)
    y hay al menos un `contenedor`. En uno de **componentes** hay al menos un
    `componente`, la línea `Contenedor:` dice cuál se abre, y ese contenedor
    ya no aparece como caja.

**Relaciones**

12. `[extremos]` `De` y `Hacia` son nombres de la tabla de elementos, y son
    distintos. La dirección de la flecha es la de quien inicia: quien llama,
    quien pide, quien envía.
13. `[que-viaja]` Toda relación dice qué viaja, con un verbo y lo que lleva:
    "Pide búsquedas, reservas y préstamos". "Usa", "llama a", "se conecta a",
    "lee y escribe" o "datos" no dicen nada, y el revisor los rechaza.
14. `[protocolo]` Toda relación dice por qué protocolo: "HTTPS, JSON", "SMTP",
    "Protocolo de PostgreSQL sobre TCP". Cuando un extremo es una persona, se
    escribe el medio por el que llega: "Navegador web", "Correo electrónico".
15. `[repetida]` La misma flecha (mismos extremos, misma etiqueta) no se
    escribe dos veces. Dos flechas entre las mismas cajas sí pueden existir si
    llevan cosas distintas.

**Entre diagramas**

16. `[coherencia]` Si se revisan juntos el diagrama de contexto y el de
    contenedores de un mismo sistema, las personas y los sistemas externos
    son los mismos en los dos. Abrir la caja del sistema no cambia lo que lo
    rodea.

## Cómo se revisa

Dentro del contenedor del curso:

```sh
node /work/code/week-01/check-c4.ts docs/c4/context.md docs/c4/containers.md
```

Por cada error imprime una línea con el archivo, el número de línea, la regla
y qué falta; al final, un resumen por archivo. Termina con código 0 si no
encontró errores y con 1 si encontró alguno, así que se puede usar en un
`Makefile` o en un paso de integración continua.

## Lo que el revisor no ve

El revisor comprueba que el diagrama esté **completo**, no que sea
**cierto**. No sabe si el sistema tiene de verdad esos procesos, si la flecha
va en la dirección correcta, si falta un sistema externo o si la descripción
describe bien. Eso se comprueba contra el sistema corriendo (qué procesos
hay, quién abre una conexión hacia quién) y lo juzga quien lee. Un diagrama
que pasa el revisor y no coincide con el sistema es peor que no tener
diagrama.

## Decisiones del formato

- **Tablas y no un lenguaje de diagramas** (Mermaid, PlantUML, Structurizr
  DSL). Un lenguaje de diagramas dibuja las cajas; a cambio hay que aprender
  su sintaxis, y lo que más importa (la descripción, la tecnología, la
  etiqueta y el protocolo) queda como texto opcional que nadie obliga a
  llenar. Con tablas, una celda vacía se ve, y se puede revisar. Lo que se
  pierde es el dibujo: quien lo quiera puede generarlo a partir de las tablas
  o dibujarlo aparte, pero la fuente es el texto.
- **Protocolo también en el diagrama de contexto.** C4 propone que el
  diagrama de contexto se concentre en personas y sistemas, sin detalle
  técnico, para que lo lea cualquiera. En el curso pedimos igual el protocolo
  de cada flecha: la descripción sigue siendo legible para quien no programa,
  y saber desde el contexto que una dependencia externa es una llamada HTTP
  síncrona es justo lo que hace falta para razonar sobre fallas.
- **Los tipos y los títulos en español**, como el resto de los documentos del
  repositorio. Los nombres de los archivos, en inglés (`context.md`,
  `containers.md`, `components.md`).
