Semana 1 — Qué es la arquitectura y qué la determina
Objetivos
- Definir la arquitectura de un sistema como el conjunto de estructuras necesarias para razonar sobre él, y reconocer en un sistema concreto qué decisiones son de arquitectura y cuáles no.
- Distinguir los tres tipos de estructuras (de módulos, de componentes y conectores, y de asignación) y decir qué pregunta responde cada una.
- Identificar los requisitos significativos para la arquitectura de un sistema, separándolos de los requisitos funcionales que no la afectan, y reconocer restricciones y stakeholders.
- Levantar el entorno del curso, correr Tinkuy y describir su arquitectura actual con un diagrama de contexto y uno de contenedores.
Sesión A — Presentación del curso · Qué es la arquitectura: estructuras y decisiones que cuesta cambiar
Lecturas:
- Bass, Clements y Kazman, Software Architecture in Practice (4.ª ed.), cap. 1 What Is Software Architecture? y cap. 2 Why Is Software Architecture Important?
- Lectura libre: Martin Fowler, Who Needs an Architect? (2003): arquitectura como “lo que cuesta cambiar”.
Lecturas complementarias:
- Martin Fowler, Software Architecture Guide.
- Simon Brown, The C4 model: abstractions: sistema, contenedor y componente.
Temas:
- Cómo funciona el curso: cuatro partes, un sistema (Tinkuy) que se rediseña seis veces, y la regla de trabajo de todo el semestre: una decisión se justifica con un escenario, se compara con una alternativa, se escribe y se mide.
- Definición (Bass, Clements y Kazman): la arquitectura de un sistema es el conjunto de estructuras necesarias para razonar sobre él; cada estructura tiene elementos, relaciones entre ellos y propiedades de ambos. Tres consecuencias: todo sistema tiene arquitectura, aunque nadie la haya escrito; la arquitectura es una abstracción (omite lo que no sirve para razonar); y no toda estructura es arquitectura, solo la que ayuda a razonar sobre un atributo que importa.
- La definición de Fowler y Johnson, complementaria: arquitectura son las decisiones que uno quisiera acertar temprano porque cuesta cambiarlas. En Tinkuy, “todo corre en un proceso con una base de datos PostgreSQL” es de arquitectura; el nombre de una función no lo es. La prueba práctica: ¿cuántos archivos, equipos y despliegues toca deshacerla?
- Tres tipos de estructuras. De módulos: cómo se divide el código (qué depende de qué, quién es owner de qué); responde “¿qué toca un cambio?”. De componentes y conectores: qué existe mientras el sistema corre (procesos, bases de datos) y cómo se comunican; responde “¿qué pasa con la latencia y con las fallas?”. De asignación: en qué máquinas, repositorios y equipos cae cada cosa; responde “¿quién lo construye y dónde corre?”. Un mismo sistema se ve distinto en cada una: Tinkuy tiene cinco módulos y un solo proceso propio, que habla con la base de datos y con la pasarela.
- Arquitectura y diseño: no hay una frontera nítida; es la misma actividad a distinta escala, y la diferencia es el costo de equivocarse. Arquitectura y funcionalidad: la misma funcionalidad se puede construir con muchas arquitecturas; lo que cambia es qué tan bien se cumple cada atributo de calidad.
- Por qué importa (cap. 2): habilita o impide los atributos de calidad; permite razonar sobre el costo de un cambio; es lo primero que se decide y lo más difícil de corregir; define cómo se reparte el trabajo entre equipos; se puede evaluar antes de construir.
- Error común: confundir arquitectura con un diagrama, o con la tecnología (“nuestra arquitectura es React y PostgreSQL”). El diagrama es una vista y la tecnología es una decisión entre muchas.
- Error común: creer que un sistema pequeño “no tiene arquitectura”. La tiene; lo que le falta es alguien que la haya decidido.
Sesión B — Qué determina una arquitectura: requisitos significativos, restricciones y stakeholders
Lecturas:
- Software Architecture in Practice, cap. 19 Architecturally Significant Requirements, secciones sobre cómo se obtienen de los documentos de requisitos, de los stakeholders y de los objetivos del negocio (el utility tree del mismo capítulo se ve en la semana 2).
- Lectura libre: Simon Brown, C4: diagramas, los de contexto y de contenedores.
Lecturas complementarias:
- Software Architecture in Practice, cap. 24 The Role of Architects in Projects.
- Kleppmann y Riccomini, Designing Data-Intensive Applications (2.ª ed.), cap. 1 Trade-Offs in Data Systems Architecture, la introducción.
Temas:
- Un requisito significativo para la arquitectura (ASR) es uno que, si cambiara, cambiaría la arquitectura. “El comprador puede elegir su asiento” casi no la afecta; “cuando se abre la venta de un concierto, 20 000 personas intentan comprar en el primer minuto” la determina. Regla práctica: los ASR casi nunca dicen qué hace el sistema; dicen cuánto, qué tan rápido, con qué frecuencia cambia o qué pasa si falla.
- De dónde salen: de los requisitos escritos (pocas veces: suelen decir “debe ser rápido”), de entrevistar a los stakeholders, de los objetivos del negocio (“vender entradas de partidos de la selección”) y de lo que ya se sabe del dominio. Parte del trabajo es hacerlos explícitos.
- Stakeholders: toda persona con interés en el sistema, no solo quien lo usa. En Tinkuy: compradores, organizadores de eventos, soporte, quien opera el sistema de madrugada, el equipo que lo mantiene, la pasarela de pagos, el área legal. Cada uno pide atributos distintos, y a veces opuestos.
- Restricciones: decisiones que ya vienen tomadas (el lenguaje que conoce el equipo, el presupuesto, una ley de protección de datos, la pasarela con la que el negocio ya firmó). No se negocian; se diseña dentro de ellas.
- Lo que también influye: el tamaño y la experiencia del equipo, el plazo, y lo que el equipo ya construyó antes. La arquitectura, a su vez, influye sobre la organización (se retoma con la ley de Conway en la semana 15).
- Tinkuy, primera lectura: qué vende, quiénes son sus stakeholders, cuáles de sus requisitos son ASR. La lista que salga de la clase se convierte en escenarios medibles la semana 2.
- Cómo se dibuja lo que hay: los dos primeros niveles de C4. Contexto: el sistema como una caja, las personas que lo usan y los sistemas externos (la pasarela de pagos y, cuando lo haya, el servidor de correo: en el Tinkuy inicial el envío está simulado dentro del proceso). Contenedores: lo que tiene que estar corriendo o existir para que funcione (el proceso de Node.js, la base de datos). Toda flecha dice qué viaja y por qué protocolo. Se profundiza en la semana 7.
- Error común: confundir el contenedor de C4 con un contenedor de Docker. En C4 es cualquier cosa que se ejecuta o guarda datos por separado.
- Error común: listar como ASR cosas que no se pueden comprobar (“debe ser escalable”, “debe ser seguro”). Si no se puede decir cuándo se incumple, todavía no es un requisito.
Laboratorio — Entorno; recorrer Tinkuy y dibujar lo que hay
Referencias: labs/README.md (entorno), el README de Tinkuy, C4: diagramas. Material: code/week-01/. En parejas.
- Instalar Docker, abrir el contenedor con
env/run.shy comprobar los servicios consvc status: PostgreSQL, Redis y NATS deben estar arriba. - En
tinkuy/:make db(crea la base de datos y carga los datos),make gatewayen una terminal (la pasarela de pagos simulada) ymake starten otra. Probar concurllos endpoints del README: listar eventos, ver un evento, ver sus asientos, comprar una entrada y consultar la orden. - Correr
make testymake typecheck. Leer una prueba y decir qué comportamiento fija. - Estructura de módulos: listar las carpetas de
src/y, para cada una, anotar en una frase de qué es responsable. Conmake importsencode/week-01/(o congrep -roE "from '\.\./[a-z]+" src | sort | uniq -c, que dice qué archivo importa de qué carpeta) contar los imports entre carpetas y dibujar el grafo: una caja por módulo y una flecha por dependencia. - Estructura de componentes y conectores: con el sistema corriendo, listar qué procesos existen (
ps aux), en qué puerto escucha cada uno (lo dicen sus mensajes de arranque y el README) y quién llama a quién. Seguir una compra de punta a punta leyendo el código dePOST /ordersy anotar, en orden, cada llamada que sale del proceso (a la base de datos, a la pasarela) y cuáles ocurren dentro de la transacción. - Escribir en
docs/c4/context.mdydocs/c4/containers.mdlos diagramas de contexto y de contenedores de Tinkuy, como texto, con el formato decode/week-01/. El laboratorio es en parejas, pero los diagramas son parte de P0, que es individual: cada quien termina con los suyos. Cada caja con su nombre, qué es y su tecnología; cada flecha con qué viaja y por qué protocolo. - Con lo que vieron, escribir tres candidatos a ASR de Tinkuy y, para cada uno, qué parte del diseño actual creen que no lo aguantaría. No hace falta medir todavía: eso es la semana 2.
Entregas
Se publica P0 · Reconocimiento (projects/p0-reconocimiento/README.md), individual, que se entrega en la semana 3. Los diagramas de este laboratorio son su primera parte.
Preguntas de repaso
- Den dos decisiones de Tinkuy que sean de arquitectura y dos que no. ¿Qué criterio usaron?
- ¿Qué pregunta responde una estructura de módulos que no responde una de componentes y conectores? Den un ejemplo con Tinkuy.
- “Nuestro sistema no tiene arquitectura porque nunca la diseñamos.” ¿Por qué es falso según la definición del libro?
- De estos requisitos, ¿cuáles son significativos para la arquitectura y por qué?: (a) el comprador recibe su entrada por correo; (b) una compra confirmada no se pierde aunque se caiga el servidor; (c) el organizador puede cambiar el precio de una sección; (d) el sistema debe poder agregar un medio de pago nuevo en menos de una semana.
- Nombren tres stakeholders de Tinkuy que no sean compradores y un atributo de calidad que le importe a cada uno.
- ¿Por qué la pasarela de pagos aparece en el diagrama de contexto y la tabla
ordersno?
Código de la semana
Compilar y probar dentro del contenedor del curso con make y make test.
Ejemplos (7)Errores (1)Pruebas (3)Laboratorio (2)Compilación (3)
Ejemplos
Los programas que usan los apuntes y la clase.
# 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`).// Diagramas C4 como texto: lee un archivo con el formato de c4-format.md y
// comprueba sus reglas. No dibuja nada: revisa que el diagrama diga lo que un
// diagrama de arquitectura tiene que decir (qué es cada caja, con qué está
// hecha, qué viaja por cada flecha y por qué protocolo).
export const LEVELS = ['contexto', 'contenedores', 'componentes'] as const;
export type Level = (typeof LEVELS)[number];
export const KINDS = [
'persona',
'sistema',
'sistema externo',
'contenedor',
'almacén de datos',
'componente',
] as const;
export type Kind = (typeof KINDS)[number];
// Qué tipos de caja puede tener cada nivel. En el de contexto el sistema es
// una sola caja; en los otros ya está abierto y se ven sus partes.
const KINDS_BY_LEVEL: Record<Level, readonly Kind[]> = {
contexto: ['persona', 'sistema', 'sistema externo'],
contenedores: ['persona', 'sistema externo', 'contenedor', 'almacén de datos'],
componentes: ['persona', 'sistema externo', 'contenedor', 'almacén de datos', 'componente'],
};
export const ELEMENT_COLUMNS = ['Nombre', 'Tipo', 'Descripción', 'Tecnología'] as const;
export const RELATIONSHIP_COLUMNS = ['De', 'Hacia', 'Qué viaja', 'Protocolo'] as const;
// Lo que se escribe en una celda para decir "no aplica".
const NOT_APPLICABLE = new Set(['—', '-', '–']);
// Etiquetas que no dicen qué viaja. La lista no es completa: atrapa las más
// frecuentes, y el resto lo juzga quien lee el diagrama.
const VAGUE_LABELS = new Set([
'usa',
'usa a',
'utiliza',
'llama',
'llama a',
'accede',
'accede a',
'consulta',
'consulta a',
'se conecta',
'se conecta a',
'se conecta con',
'se comunica con',
'envía datos',
'envía información',
'lee datos',
'lee y escribe',
'lee y escribe datos',
'datos',
'información',
]);
// "Base de datos" o "El backend" no describen nada: se pide una frase.
const MIN_DESCRIPTION_WORDS = 4;
export type Element = {
line: number;
name: string;
kind: string;
description: string;
technology: string;
};
export type Relationship = {
line: number;
from: string;
to: string;
label: string;
protocol: string;
};
export type Diagram = {
title: string;
level: string;
system: string;
// Solo en el nivel de componentes: el contenedor que se abrió.
container: string;
elements: Element[];
relationships: Relationship[];
};
export type Issue = {
line: number;
rule: string;
message: string;
};
type Table = { headerLine: number; header: string[]; rows: { line: number; cells: string[] }[] };
/** Para comparar nombres: sin espacios de más y sin distinguir mayúsculas. */
export function normalize(text: string): string {
return text.trim().replace(/\s+/g, ' ').toLocaleLowerCase('es');
}
function words(text: string): string[] {
return text.trim().split(/\s+/).filter((word) => /\p{L}/u.test(word));
}
function isBlank(text: string): boolean {
return text.trim() === '';
}
function isNotApplicable(text: string): boolean {
return NOT_APPLICABLE.has(text.trim());
}
/** Parte una fila de tabla en celdas. Una barra dentro de una celda se escribe `\|`. */
function splitRow(line: string): string[] {
const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
return inner.split(/(?<!\\)\|/).map((cell) => cell.replace(/\\\|/g, '|').trim());
}
function isTableRow(line: string): boolean {
return line.trim().startsWith('|');
}
function isSeparatorRow(line: string): boolean {
return /^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?$/.test(line.trim());
}
/** La primera tabla que aparece debajo del título `## <heading>`, si existe. */
function findTable(lines: string[], heading: string): { headingLine: number; table: Table | undefined } | undefined {
const start = lines.findIndex((line) => /^##\s+/.test(line) && normalize(line.replace(/^##\s+/, '')) === normalize(heading));
if (start === -1) return undefined;
let i = start + 1;
while (i < lines.length && !isTableRow(lines[i]!) && !/^#{1,2}\s/.test(lines[i]!)) i += 1;
if (i >= lines.length || !isTableRow(lines[i]!)) return { headingLine: start + 1, table: undefined };
const table: Table = { headerLine: i + 1, header: splitRow(lines[i]!), rows: [] };
i += 1;
if (i < lines.length && isSeparatorRow(lines[i]!)) i += 1;
while (i < lines.length && isTableRow(lines[i]!)) {
table.rows.push({ line: i + 1, cells: splitRow(lines[i]!) });
i += 1;
}
return { headingLine: start + 1, table };
}
/** El valor de una línea `Clave: valor` (con o sin guion de lista delante). */
function findField(lines: string[], key: string): { line: number; value: string } | undefined {
const pattern = new RegExp(`^\\s*(?:[-*]\\s+)?${key}\\s*:\\s*(.*)$`, 'i');
for (let i = 0; i < lines.length; i += 1) {
const match = pattern.exec(lines[i]!);
if (match) return { line: i + 1, value: match[1]!.trim() };
}
return undefined;
}
function sameColumns(header: string[], expected: readonly string[]): boolean {
return header.length === expected.length && header.every((cell, i) => normalize(cell) === normalize(expected[i]!));
}
/**
* Lee un diagrama. Devuelve lo que pudo leer y los problemas de forma (falta
* el título, falta una tabla, una fila tiene celdas de más o de menos). Las
* reglas sobre el contenido las revisa `checkDiagram`.
*/
export function parseDiagram(text: string): { diagram: Diagram; issues: Issue[] } {
const lines = text.split(/\r?\n/);
const issues: Issue[] = [];
const diagram: Diagram = { title: '', level: '', system: '', container: '', elements: [], relationships: [] };
const firstHeading = lines.findIndex((line) => /^#{1,6}\s/.test(line));
if (firstHeading === -1 || !/^#\s+\S/.test(lines[firstHeading]!)) {
issues.push({ line: 1, rule: 'titulo', message: 'el archivo empieza con un título de nivel 1 (`# ...`) que dice qué diagrama es' });
} else {
diagram.title = lines[firstHeading]!.replace(/^#\s+/, '').trim();
}
const level = findField(lines, 'Nivel');
if (!level) {
issues.push({ line: 1, rule: 'nivel', message: `falta la línea "Nivel: ..." (${LEVELS.join(', ')})` });
} else {
diagram.level = normalize(level.value);
if (!(LEVELS as readonly string[]).includes(diagram.level)) {
issues.push({ line: level.line, rule: 'nivel', message: `el nivel "${level.value}" no existe: es ${LEVELS.join(', ')}` });
}
}
const system = findField(lines, 'Sistema');
if (!system || isBlank(system.value)) {
issues.push({ line: system?.line ?? 1, rule: 'sistema', message: 'falta la línea "Sistema: ..." con el nombre del sistema que se describe' });
} else {
diagram.system = system.value;
}
diagram.container = findField(lines, 'Contenedor')?.value ?? '';
const elements = findTable(lines, 'Elementos');
if (!elements || !elements.table) {
issues.push({ line: elements?.headingLine ?? 1, rule: 'tabla-elementos', message: 'falta la sección "## Elementos" con su tabla' });
} else if (!sameColumns(elements.table.header, ELEMENT_COLUMNS)) {
issues.push({
line: elements.table.headerLine,
rule: 'tabla-elementos',
message: `las columnas de Elementos son: ${ELEMENT_COLUMNS.join(' | ')}`,
});
} else {
for (const row of elements.table.rows) {
if (row.cells.length !== ELEMENT_COLUMNS.length) {
issues.push({ line: row.line, rule: 'tabla-elementos', message: `la fila tiene ${row.cells.length} celdas y debe tener ${ELEMENT_COLUMNS.length}` });
continue;
}
const [name, kind, description, technology] = row.cells as [string, string, string, string];
diagram.elements.push({ line: row.line, name, kind, description, technology });
}
}
const relationships = findTable(lines, 'Relaciones');
if (!relationships || !relationships.table) {
issues.push({ line: relationships?.headingLine ?? 1, rule: 'tabla-relaciones', message: 'falta la sección "## Relaciones" con su tabla' });
} else if (!sameColumns(relationships.table.header, RELATIONSHIP_COLUMNS)) {
issues.push({
line: relationships.table.headerLine,
rule: 'tabla-relaciones',
message: `las columnas de Relaciones son: ${RELATIONSHIP_COLUMNS.join(' | ')}`,
});
} else {
for (const row of relationships.table.rows) {
if (row.cells.length !== RELATIONSHIP_COLUMNS.length) {
issues.push({ line: row.line, rule: 'tabla-relaciones', message: `la fila tiene ${row.cells.length} celdas y debe tener ${RELATIONSHIP_COLUMNS.length}` });
continue;
}
const [from, to, label, protocol] = row.cells as [string, string, string, string];
diagram.relationships.push({ line: row.line, from, to, label, protocol });
}
}
return { diagram, issues };
}
function checkElements(diagram: Diagram, issues: Issue[]): void {
const level = diagram.level as Level;
const allowed = KINDS_BY_LEVEL[level];
const seen = new Map<string, number>();
if (diagram.elements.length === 0) {
issues.push({ line: 1, rule: 'tabla-elementos', message: 'la tabla de Elementos está vacía' });
}
for (const element of diagram.elements) {
const shown = isBlank(element.name) ? '(sin nombre)' : `"${element.name}"`;
if (isBlank(element.name)) {
issues.push({ line: element.line, rule: 'nombre', message: 'hay un elemento sin nombre' });
} else {
const key = normalize(element.name);
const previous = seen.get(key);
if (previous !== undefined) {
issues.push({ line: element.line, rule: 'nombre', message: `${shown} ya está en la línea ${previous}: cada elemento aparece una sola vez` });
} else {
seen.set(key, element.line);
}
}
const kind = normalize(element.kind);
if (!(KINDS as readonly string[]).includes(kind)) {
issues.push({ line: element.line, rule: 'tipo', message: `${shown}: el tipo "${element.kind}" no existe; es ${KINDS.join(', ')}` });
} else if (!allowed.includes(kind as Kind)) {
issues.push({ line: element.line, rule: 'tipo', message: `${shown}: un diagrama de ${level} no lleva elementos de tipo "${kind}" (lleva ${allowed.join(', ')})` });
}
if (isBlank(element.description) || isNotApplicable(element.description)) {
issues.push({ line: element.line, rule: 'descripcion', message: `${shown} no tiene descripción: falta decir qué es o qué hace` });
} else if (normalize(element.description) === normalize(element.name) || words(element.description).length < MIN_DESCRIPTION_WORDS) {
issues.push({ line: element.line, rule: 'descripcion', message: `${shown}: "${element.description}" no alcanza como descripción; digan de qué es responsable` });
}
if (kind === 'persona') {
if (!isNotApplicable(element.technology)) {
issues.push({ line: element.line, rule: 'tecnologia', message: `${shown} es una persona: en Tecnología va "—" (cómo llega al sistema se dice en la relación)` });
}
} else if (isBlank(element.technology) || isNotApplicable(element.technology)) {
issues.push({ line: element.line, rule: 'tecnologia', message: `${shown} no dice con qué tecnología está hecho` });
}
}
}
function checkScope(diagram: Diagram, issues: Issue[]): void {
const level = diagram.level as Level;
const ofKind = (kind: Kind): Element[] => diagram.elements.filter((element) => normalize(element.kind) === kind);
const named = (name: string): Element | undefined => diagram.elements.find((element) => normalize(element.name) === normalize(name));
if (level === 'contexto') {
const systems = ofKind('sistema');
if (systems.length !== 1) {
issues.push({
line: systems[1]?.line ?? 1,
rule: 'alcance',
message: `un diagrama de contexto tiene exactamente un elemento de tipo "sistema" (el que se describe), y este tiene ${systems.length}`,
});
} else if (diagram.system !== '' && normalize(systems[0]!.name) !== normalize(diagram.system)) {
issues.push({ line: systems[0]!.line, rule: 'alcance', message: `el elemento de tipo "sistema" se llama "${systems[0]!.name}" y la línea Sistema dice "${diagram.system}"` });
}
return;
}
// En los otros niveles el sistema ya está abierto: no es una caja más.
const system = diagram.system === '' ? undefined : named(diagram.system);
if (system) {
issues.push({ line: system.line, rule: 'alcance', message: `"${system.name}" es el sistema que este diagrama abre: aquí van sus partes, no el sistema como una caja` });
}
if (level === 'contenedores') {
if (ofKind('contenedor').length === 0) {
issues.push({ line: 1, rule: 'alcance', message: 'un diagrama de contenedores tiene al menos un elemento de tipo "contenedor"' });
}
return;
}
if (ofKind('componente').length === 0) {
issues.push({ line: 1, rule: 'alcance', message: 'un diagrama de componentes tiene al menos un elemento de tipo "componente"' });
}
if (isBlank(diagram.container)) {
issues.push({ line: 1, rule: 'alcance', message: 'un diagrama de componentes dice qué contenedor abre, con la línea "Contenedor: ..."' });
} else {
const container = named(diagram.container);
if (container) {
issues.push({ line: container.line, rule: 'alcance', message: `"${container.name}" es el contenedor que este diagrama abre: aquí van sus componentes, no el contenedor como una caja` });
}
}
}
function checkRelationships(diagram: Diagram, issues: Issue[]): void {
const names = new Set(diagram.elements.map((element) => normalize(element.name)));
const connected = new Set<string>();
const seen = new Map<string, number>();
if (diagram.relationships.length === 0) {
issues.push({ line: 1, rule: 'tabla-relaciones', message: 'la tabla de Relaciones está vacía' });
}
for (const relationship of diagram.relationships) {
const arrow = `${relationship.from} → ${relationship.to}`;
for (const [column, end] of [['De', relationship.from], ['Hacia', relationship.to]] as const) {
if (isBlank(end)) {
issues.push({ line: relationship.line, rule: 'extremos', message: `la relación no dice su extremo "${column}"` });
} else if (!names.has(normalize(end))) {
issues.push({ line: relationship.line, rule: 'extremos', message: `"${end}" no está en la tabla de Elementos` });
} else {
connected.add(normalize(end));
}
}
if (!isBlank(relationship.from) && normalize(relationship.from) === normalize(relationship.to)) {
issues.push({ line: relationship.line, rule: 'extremos', message: `${arrow}: una relación une dos elementos distintos` });
}
const label = normalize(relationship.label).replace(/[.:;,]+$/, '');
if (label === '' || isNotApplicable(relationship.label)) {
issues.push({ line: relationship.line, rule: 'que-viaja', message: `${arrow} no dice qué viaja` });
} else if (VAGUE_LABELS.has(label) || words(label).length < 2) {
issues.push({ line: relationship.line, rule: 'que-viaja', message: `${arrow}: "${relationship.label}" no dice qué viaja; usen un verbo y lo que lleva ("Pide las reservas de un lector")` });
}
if (isBlank(relationship.protocol) || isNotApplicable(relationship.protocol)) {
issues.push({ line: relationship.line, rule: 'protocolo', message: `${arrow} no dice por qué protocolo` });
}
const key = [normalize(relationship.from), normalize(relationship.to), label].join(' > ');
const previous = seen.get(key);
if (previous !== undefined) {
issues.push({ line: relationship.line, rule: 'repetida', message: `${arrow} con la misma etiqueta ya está en la línea ${previous}` });
} else {
seen.set(key, relationship.line);
}
}
for (const element of diagram.elements) {
if (!isBlank(element.name) && !connected.has(normalize(element.name))) {
issues.push({ line: element.line, rule: 'suelto', message: `"${element.name}" no participa en ninguna relación: o falta una flecha o sobra la caja` });
}
}
}
/** Lee un diagrama y devuelve todos sus problemas, ordenados por línea. */
export function checkDiagram(text: string): { diagram: Diagram; issues: Issue[] } {
const { diagram, issues } = parseDiagram(text);
// Sin nivel válido no se sabe qué reglas aplicar a los tipos ni al alcance.
if ((LEVELS as readonly string[]).includes(diagram.level)) {
checkElements(diagram, issues);
checkScope(diagram, issues);
checkRelationships(diagram, issues);
}
issues.sort((a, b) => a.line - b.line);
return { diagram, issues };
}
export type NamedDiagram = { file: string; diagram: Diagram };
export type SetIssue = { file: string; message: string };
/**
* Coherencia entre el diagrama de contexto y el de contenedores del mismo
* sistema: abrir la caja del sistema no cambia quién lo usa ni con qué
* sistemas externos habla, así que las personas y los sistemas externos deben
* ser los mismos en los dos.
*/
export function checkSet(diagrams: NamedDiagram[]): SetIssue[] {
const issues: SetIssue[] = [];
const outside = (diagram: Diagram): Map<string, string> =>
new Map(
diagram.elements
.filter((element) => ['persona', 'sistema externo'].includes(normalize(element.kind)))
.map((element) => [normalize(element.name), element.name]),
);
for (const context of diagrams.filter((entry) => entry.diagram.level === 'contexto')) {
for (const containers of diagrams.filter((entry) => entry.diagram.level === 'contenedores')) {
if (normalize(context.diagram.system) !== normalize(containers.diagram.system)) continue;
const inContext = outside(context.diagram);
const inContainers = outside(containers.diagram);
for (const [key, name] of inContext) {
if (!inContainers.has(key)) {
issues.push({ file: containers.file, message: `"${name}" está en ${context.file} y no aparece aquí: ¿con qué contenedor se relaciona?` });
}
}
for (const [key, name] of inContainers) {
if (!inContext.has(key)) {
issues.push({ file: context.file, message: `"${name}" está en ${containers.file} y no aparece aquí: el contexto muestra a todas las personas y sistemas externos` });
}
}
}
}
return issues;
}#!/usr/bin/env bash
# ¿Cuántos archivos toca deshacer una decisión? Para cada decisión busca el
# rastro que deja en el código y cuenta en cuántos archivos de src/ aparece.
# Es una medida gruesa (un archivo puede necesitar un cambio de una línea o
# reescribirse entero), pero alcanza para ordenar las decisiones por costo.
#
# bash change-cost.sh build/tinkuy
set -euo pipefail
app="${1:?Uso: bash change-cost.sh <carpeta-de-tinkuy>}"
total=$(find "$app/src" -name '*.ts' | wc -l | tr -d ' ')
count() {
# $1: la decisión; $2: expresión regular de su rastro en el código
local files
files=$(grep -rlE "$2" "$app/src" | wc -l | tr -d ' ')
printf '%-44s %2s de %s archivos\n' "$1" "$files" "$total"
}
count 'El puerto por omisión es 3000' '3000'
count 'La comisión la calcula paymentFeeCents' 'paymentFeeCents'
count 'Los montos son céntimos enteros' 'Cents'
count 'Las consultas son SQL para PostgreSQL' 'client\.query|query<|query\('// Revisa uno o más diagramas C4 escritos con el formato de c4-format.md.
//
// node check-c4.ts docs/c4/context.md docs/c4/containers.md
//
// Termina con código 0 si no encontró errores, 1 si encontró alguno y 2 si no
// pudo leer un archivo o no recibió ninguno.
import { readFileSync } from 'node:fs';
import { checkDiagram, checkSet, type NamedDiagram } from './c4.ts';
function plural(count: number, one: string, many: string): string {
return `${count} ${count === 1 ? one : many}`;
}
function main(files: string[]): number {
if (files.length === 0) {
console.error('Uso: node check-c4.ts <diagrama.md> [<otro-diagrama.md> ...]');
return 2;
}
let errors = 0;
const read: NamedDiagram[] = [];
for (const file of files) {
let text: string;
try {
text = readFileSync(file, 'utf8');
} catch {
console.error(`${file}: no se pudo leer el archivo`);
return 2;
}
const { diagram, issues } = checkDiagram(text);
read.push({ file, diagram });
for (const issue of issues) {
console.log(`${file}:${issue.line}: [${issue.rule}] ${issue.message}`);
}
const summary = `${diagram.level || 'nivel desconocido'} de ${diagram.system || '(sin sistema)'}, ${plural(diagram.elements.length, 'elemento', 'elementos')}, ${plural(diagram.relationships.length, 'relación', 'relaciones')}`;
console.log(`${file}: ${summary}: ${issues.length === 0 ? 'sin errores' : plural(issues.length, 'error', 'errores')}`);
errors += issues.length;
}
for (const issue of checkSet(read)) {
console.log(`${issue.file}: [coherencia] ${issue.message}`);
errors += 1;
}
return errors === 0 ? 0 : 1;
}
process.exitCode = main(process.argv.slice(2));// Cuenta los imports entre las carpetas de un directorio de código fuente.
//
// node module-graph.ts ../../tinkuy/src
//
// Es la estructura de módulos vista desde los imports: una línea por cada par
// (carpeta que importa, carpeta o archivo importado) con cuántos imports hay.
// Hace lo mismo que el grep del laboratorio, pero dice además quién importa.
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { dirname, join, relative, resolve, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
export type Edge = { from: string; to: string; imports: number };
// `from './x.ts'` al final de un import o de un export, aunque ocupe varias líneas.
const IMPORT_PATTERN = /\bfrom\s+['"](\.{1,2}\/[^'"]+)['"]/g;
function sourceFiles(dir: string): string[] {
const found: string[] = [];
for (const name of readdirSync(dir).sort()) {
const path = join(dir, name);
if (statSync(path).isDirectory()) found.push(...sourceFiles(path));
else if (name.endsWith('.ts')) found.push(path);
}
return found;
}
/** El módulo de un archivo: su carpeta de primer nivel, o su nombre si está suelto en la raíz. */
function moduleOf(srcDir: string, file: string): string {
const parts = relative(srcDir, file).split(sep);
return parts.length === 1 ? parts[0]! : `${parts[0]!}/`;
}
/** Los imports que cruzan de un módulo a otro, agrupados y contados. */
export function moduleGraph(srcDir: string): Edge[] {
const root = resolve(srcDir);
const counts = new Map<string, number>();
for (const file of sourceFiles(root)) {
const from = moduleOf(root, file);
const text = readFileSync(file, 'utf8');
for (const match of text.matchAll(IMPORT_PATTERN)) {
const target = resolve(dirname(file), match[1]!);
const to = moduleOf(root, target);
if (to === from || to.startsWith('..')) continue;
const key = `${from} ${to}`;
counts.set(key, (counts.get(key) ?? 0) + 1);
}
}
return [...counts.entries()]
.map(([key, imports]) => {
const [from, to] = key.split(' ') as [string, string];
return { from, to, imports };
})
.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
}
/** Los pares de carpetas que se importan en los dos sentidos. */
export function mutualPairs(edges: Edge[]): [string, string][] {
const has = new Set(edges.map((edge) => `${edge.from} ${edge.to}`));
return edges
.filter((edge) => edge.from < edge.to && has.has(`${edge.to} ${edge.from}`))
.map((edge) => [edge.from, edge.to]);
}
function main(args: string[]): number {
const srcDir = args[0];
if (srcDir === undefined) {
console.error('Uso: node module-graph.ts <carpeta-src>');
return 2;
}
const edges = moduleGraph(srcDir);
const width = Math.max(...edges.map((edge) => edge.from.length));
for (const edge of edges) {
console.log(`${edge.from.padEnd(width)} -> ${edge.to.padEnd(18)} ${String(edge.imports).padStart(2)}`);
}
// Solo entre carpetas: los archivos sueltos de la raíz no importan módulos.
for (const [a, b] of mutualPairs(edges)) {
console.log(`En los dos sentidos: ${a} <-> ${b}`);
}
return 0;
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
process.exitCode = main(process.argv.slice(2));
}# Qillqa: diagrama de contenedores
- Nivel: contenedores
- Sistema: Qillqa
La caja "Qillqa" del diagrama de contexto, abierta: lo que tiene que estar
corriendo o existir para que el sistema funcione. Las personas y los sistemas
externos son los mismos del diagrama de contexto.
## Elementos
| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Lector | persona | Estudiante o docente que busca libros, los reserva y renueva sus préstamos | — |
| Bibliotecario | persona | Atiende el mostrador: registra préstamos y devoluciones y entrega las reservas | — |
| Aplicación web | contenedor | Las páginas del catálogo, de "mis préstamos" y del mostrador; corre en el navegador de cada persona | TypeScript y HTML, sin framework |
| API | contenedor | Aplica las reglas de préstamo (quién puede llevarse qué, por cuántos días, cuántas renovaciones) y entrega los archivos de la aplicación web | Node.js 26, node:http |
| Avisos nocturnos | contenedor | Programa que corre una vez cada noche: busca los préstamos que vencen al día siguiente y manda un aviso por cada uno | Script de Node.js que lanza cron |
| Base de datos | almacén de datos | Libros, ejemplares, lectores, préstamos, reservas y avisos enviados | PostgreSQL 18 |
| Sistema de matrícula | sistema externo | Sistema de la universidad que dice quién está matriculado este semestre | API REST de la oficina de registro |
| Servidor de correo | sistema externo | Entrega los avisos en el correo institucional de cada lector | Servicio SMTP de la universidad |
## Relaciones
| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Lector | Aplicación web | Busca libros, reserva y renueva sus préstamos | Navegador web |
| Bibliotecario | Aplicación web | Registra préstamos y devoluciones | Navegador web |
| Aplicación web | API | Pide búsquedas, reservas, préstamos y devoluciones | HTTPS, JSON |
| API | Base de datos | Lee el catálogo y escribe préstamos y reservas | Protocolo de PostgreSQL sobre TCP (SQL) |
| API | Sistema de matrícula | Pregunta si un código de estudiante está matriculado | HTTPS, JSON |
| Avisos nocturnos | Base de datos | Lee los préstamos que vencen mañana y anota cada aviso enviado | Protocolo de PostgreSQL sobre TCP (SQL) |
| Avisos nocturnos | Servidor de correo | Envía avisos de vencimiento y de reserva lista | SMTP |
| Servidor de correo | Lector | Entrega los avisos | Correo electrónico |# Qillqa: diagrama de contexto
- Nivel: contexto
- Sistema: Qillqa
Qillqa es el sistema de préstamos de la biblioteca de una universidad. Este
diagrama lo muestra como una sola caja: quién lo usa y de qué otros sistemas
depende. Lo puede leer alguien que no programa.
## Elementos
| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Lector | persona | Estudiante o docente que busca libros, los reserva y renueva sus préstamos | — |
| Bibliotecario | persona | Atiende el mostrador: registra préstamos y devoluciones y entrega las reservas | — |
| Qillqa | sistema | Catálogo, reservas y préstamos de la biblioteca, con avisos antes de cada vencimiento | Aplicación web con una API en Node.js y PostgreSQL |
| Sistema de matrícula | sistema externo | Sistema de la universidad que dice quién está matriculado este semestre | API REST de la oficina de registro |
| Servidor de correo | sistema externo | Entrega los avisos en el correo institucional de cada lector | Servicio SMTP de la universidad |
## Relaciones
| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Lector | Qillqa | Busca libros, reserva y renueva sus préstamos | HTTPS, desde el navegador |
| Bibliotecario | Qillqa | Registra préstamos y devoluciones | HTTPS, desde el navegador |
| Qillqa | Sistema de matrícula | Pregunta si un código de estudiante está matriculado | HTTPS, JSON |
| Qillqa | Servidor de correo | Envía avisos de vencimiento y de reserva lista | SMTP |
| Servidor de correo | Lector | Entrega los avisos | Correo electrónico |Errores
Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.
# Qillqa: contenedores (con errores)
- Nivel: contenedores
- Sistema: Qillqa
El mismo sistema de example/containers.md, dibujado con los errores más
comunes de un primer diagrama. `node check-c4.ts errors/containers.md` los
lista; los apuntes de la semana 1 explican cada uno.
## Elementos
| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Lector | persona | Estudiante o docente que busca libros, los reserva y renueva sus préstamos | Chrome |
| Frontend | contenedor | Frontend | React |
| Backend | contenedor | Aplica las reglas de préstamo y atiende a la aplicación web | |
| Docker | contenedor | El contenedor donde corre todo el sistema | Docker |
| PostgreSQL | almacén de datos | Base de datos | PostgreSQL 18 |
| Tabla loans | componente | Guarda un préstamo por fila, con su fecha de vencimiento | PostgreSQL 18 |
| Servidor de correo | sistema externo | Entrega los avisos en el correo institucional de cada lector | Servicio SMTP de la universidad |
## Relaciones
| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Lector | Frontend | Usa | Navegador web |
| Frontend | Backend | Pide búsquedas, reservas, préstamos y devoluciones | |
| Backend | PostgreSQL | Lee y escribe | SQL |
| Backend | Sistema de matrícula | Pregunta si un código de estudiante está matriculado | HTTPS, JSON |Pruebas
Comprueban lo que afirman los apuntes; se ejecutan con make test.
// Pruebas del formato de diagramas C4 como texto (c4-format.md) y de su
// revisor. Comprueban lo que dicen los apuntes de la semana 1: qué acepta el
// formato, qué rechaza y con qué mensaje.
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { describe, test } from 'node:test';
import { checkDiagram, checkSet, parseDiagram } from './c4.ts';
const here = import.meta.dirname;
const read = (path: string): string => readFileSync(`${here}/${path}`, 'utf8');
/** Un diagrama de contenedores mínimo y correcto, con las filas que se le pasen. */
function containers(elements: string[], relationships: string[]): string {
return [
'# Sistema de prueba: contenedores',
'',
'- Nivel: contenedores',
'- Sistema: Prueba',
'',
'## Elementos',
'',
'| Nombre | Tipo | Descripción | Tecnología |',
'|---|---|---|---|',
...elements,
'',
'## Relaciones',
'',
'| De | Hacia | Qué viaja | Protocolo |',
'|---|---|---|---|',
...relationships,
'',
].join('\n');
}
const READER = '| Lector | persona | Busca libros y renueva sus préstamos | — |';
const API = '| API | contenedor | Aplica las reglas de préstamo de la biblioteca | Node.js 26 |';
const DB = '| Base de datos | almacén de datos | Libros, lectores, préstamos y reservas | PostgreSQL 18 |';
const READER_API = '| Lector | API | Busca libros y renueva préstamos | HTTPS, JSON |';
const API_DB = '| API | Base de datos | Lee el catálogo y escribe préstamos | Protocolo de PostgreSQL |';
function rules(text: string): string[] {
return checkDiagram(text).issues.map((issue) => issue.rule);
}
describe('los ejemplos de la carpeta', () => {
test('el contexto y los contenedores de Qillqa no tienen errores', () => {
for (const file of ['example/context.md', 'example/containers.md']) {
assert.deepEqual(checkDiagram(read(file)).issues, [], file);
}
});
test('los dos diagramas de Qillqa muestran a las mismas personas y sistemas externos', () => {
const diagrams = ['example/context.md', 'example/containers.md'].map((file) => ({
file,
diagram: checkDiagram(read(file)).diagram,
}));
assert.deepEqual(checkSet(diagrams), []);
});
test('el diagrama de errors/ tiene los doce errores que explican los apuntes', () => {
const { issues } = checkDiagram(read('errors/containers.md'));
assert.deepEqual(
issues.map((issue) => `${issue.line} ${issue.rule}`),
[
'14 tecnologia', // una persona con tecnología
'15 descripcion', // la descripción repite el nombre
'16 tecnologia', // un contenedor sin tecnología
'17 suelto', // una caja que nadie usa
'18 descripcion', // "Base de datos" no dice qué guarda
'19 tipo', // un componente en un diagrama de contenedores
'19 suelto',
'20 suelto',
'26 que-viaja', // "Usa"
'27 protocolo', // una flecha sin protocolo
'28 que-viaja', // "Lee y escribe"
'29 extremos', // una flecha hacia una caja que no existe
],
);
});
test('los archivos de partida del laboratorio todavía no pasan: están vacíos', () => {
for (const file of ['lab/context.md', 'lab/containers.md']) {
const found = rules(read(file));
assert.ok(found.includes('tabla-elementos'), file);
assert.ok(found.includes('tabla-relaciones'), file);
}
});
});
describe('forma del archivo', () => {
test('un diagrama mínimo y completo pasa', () => {
assert.deepEqual(rules(containers([READER, API, DB], [READER_API, API_DB])), []);
});
test('lee nombres, tipos y números de línea', () => {
const { diagram } = parseDiagram(containers([READER, API], [READER_API]));
assert.equal(diagram.title, 'Sistema de prueba: contenedores');
assert.equal(diagram.level, 'contenedores');
assert.equal(diagram.system, 'Prueba');
assert.deepEqual(diagram.elements.map((element) => [element.line, element.name, element.kind]), [
[10, 'Lector', 'persona'],
[11, 'API', 'contenedor'],
]);
assert.deepEqual(diagram.relationships[0], {
line: 17,
from: 'Lector',
to: 'API',
label: 'Busca libros y renueva préstamos',
protocol: 'HTTPS, JSON',
});
});
test('sin título, sin nivel o sin sistema no se puede revisar', () => {
const text = containers([READER, API], [READER_API]);
assert.deepEqual(rules(text.replace('# Sistema de prueba: contenedores', '')), ['titulo']);
assert.deepEqual(rules(text.replace('- Nivel: contenedores', '')), ['nivel']);
assert.deepEqual(rules(text.replace('- Nivel: contenedores', '- Nivel: despliegue')), ['nivel']);
assert.deepEqual(rules(text.replace('- Sistema: Prueba', '')), ['sistema']);
});
test('las columnas son las del formato, en ese orden', () => {
const text = containers([READER, API], [READER_API]);
assert.ok(rules(text.replace('| Nombre | Tipo | Descripción | Tecnología |', '| Nombre | Descripción | Tipo | Tecnología |')).includes('tabla-elementos'));
assert.ok(rules(text.replace('| De | Hacia | Qué viaja | Protocolo |', '| De | Hacia | Qué viaja |')).includes('tabla-relaciones'));
});
test('una fila con celdas de menos se reporta con su línea', () => {
const { issues } = checkDiagram(containers([READER, API, '| Cola | contenedor | Guarda los avisos pendientes |'], [READER_API]));
assert.deepEqual(issues.map((issue) => [issue.line, issue.rule]), [[12, 'tabla-elementos']]);
});
test('una barra dentro de una celda se escribe con \\|', () => {
const { diagram, issues } = checkDiagram(
containers([READER, API], ['| Lector | API | Busca con filtros (autor \\| título) | HTTPS |']),
);
assert.deepEqual(issues, []);
assert.equal(diagram.relationships[0]!.label, 'Busca con filtros (autor | título)');
});
});
describe('reglas de los elementos', () => {
test('todo elemento tiene descripción, y la descripción dice algo', () => {
assert.deepEqual(rules(containers([READER, '| API | contenedor | | Node.js 26 |'], [READER_API])), ['descripcion']);
assert.deepEqual(rules(containers([READER, '| API | contenedor | API | Node.js 26 |'], [READER_API])), ['descripcion']);
assert.deepEqual(rules(containers([READER, '| API | contenedor | El backend | Node.js 26 |'], [READER_API])), ['descripcion']);
});
test('todo elemento que no es una persona dice su tecnología', () => {
assert.deepEqual(rules(containers([READER, '| API | contenedor | Aplica las reglas de préstamo | |'], [READER_API])), ['tecnologia']);
assert.deepEqual(rules(containers([READER, '| API | contenedor | Aplica las reglas de préstamo | — |'], [READER_API])), ['tecnologia']);
});
test('una persona no tiene tecnología: lleva "—"', () => {
assert.deepEqual(rules(containers(['| Lector | persona | Busca libros y renueva sus préstamos | Chrome |', API], [READER_API])), ['tecnologia']);
assert.deepEqual(rules(containers(['| Lector | persona | Busca libros y renueva sus préstamos | |', API], [READER_API])), ['tecnologia']);
});
test('un nombre no se repite, aunque cambien las mayúsculas', () => {
assert.deepEqual(rules(containers([READER, API, '| api | contenedor | Otra copia de la misma API | Node.js 26 |'], [READER_API])), ['nombre']);
});
test('el tipo existe y corresponde al nivel', () => {
assert.deepEqual(rules(containers([READER, '| API | servicio | Aplica las reglas de préstamo | Node.js 26 |'], [READER_API])).sort(), ['alcance', 'tipo']);
assert.deepEqual(
rules(containers([READER, API, '| Reglas de préstamo | componente | Decide quién puede llevarse qué | TypeScript |'], [READER_API, '| API | Reglas de préstamo | Pregunta si procede un préstamo | Llamada a función |'])),
['tipo'],
);
});
test('toda caja participa en alguna relación', () => {
const { issues } = checkDiagram(containers([READER, API, DB], [READER_API]));
assert.deepEqual(issues.map((issue) => [issue.line, issue.rule]), [[12, 'suelto']]);
});
});
describe('alcance de cada nivel', () => {
const context = (elements: string[], relationships: string[]): string =>
containers(elements, relationships).replace('- Nivel: contenedores', '- Nivel: contexto');
const SYSTEM = '| Prueba | sistema | Préstamos de la biblioteca de la universidad | Aplicación web y PostgreSQL |';
const READER_SYSTEM = '| Lector | Prueba | Busca libros y renueva préstamos | HTTPS |';
test('el contexto tiene exactamente un sistema, el de la línea Sistema', () => {
assert.deepEqual(rules(context([READER, SYSTEM], [READER_SYSTEM])), []);
assert.deepEqual(rules(context([READER, '| Otro | sistema externo | Sistema de matrícula de la universidad | API REST |'], ['| Lector | Otro | Busca libros y renueva préstamos | HTTPS |'])), ['alcance']);
assert.deepEqual(
rules(context([READER, SYSTEM.replace('| Prueba |', '| Biblioteca |')], [READER_SYSTEM.replace('| Prueba |', '| Biblioteca |')])),
['alcance'],
);
});
test('el contexto no muestra contenedores ni almacenes de datos', () => {
assert.deepEqual(rules(context([READER, SYSTEM, DB], [READER_SYSTEM, '| Prueba | Base de datos | Lee el catálogo y escribe préstamos | SQL |'])), ['tipo']);
});
test('en contenedores el sistema ya no es una caja, y hay al menos un contenedor', () => {
assert.deepEqual(rules(containers([READER, SYSTEM.replace('sistema', 'contenedor')], [READER_SYSTEM])), ['alcance']);
assert.deepEqual(rules(containers([READER, DB], ['| Lector | Base de datos | Lee el catálogo de libros | SQL |'])), ['alcance']);
});
test('un diagrama de componentes dice qué contenedor abre', () => {
const component = '| Reglas de préstamo | componente | Decide quién puede llevarse qué | TypeScript |';
const text = containers([READER, component, DB], ['| Lector | Reglas de préstamo | Pide un préstamo nuevo | HTTPS |', '| Reglas de préstamo | Base de datos | Escribe el préstamo aprobado | SQL |']).replace(
'- Nivel: contenedores',
'- Nivel: componentes',
);
assert.deepEqual(rules(text), ['alcance']);
assert.deepEqual(rules(text.replace('- Sistema: Prueba', '- Sistema: Prueba\n- Contenedor: API')), []);
});
});
describe('reglas de las relaciones', () => {
test('los dos extremos existen en la tabla de elementos y son distintos', () => {
assert.deepEqual(rules(containers([READER, API], [READER_API, '| API | Pasarela | Pide el cobro de una multa | HTTPS |'])), ['extremos']);
assert.deepEqual(rules(containers([READER, API], [READER_API, '| API | API | Se llama a sí misma | HTTPS |'])), ['extremos']);
});
test('toda relación dice qué viaja, con algo más que "usa"', () => {
for (const label of ['', 'Usa', 'usa.', 'Llama a', 'Se conecta a', 'Datos', 'Lee y escribe', 'Consulta']) {
assert.deepEqual(rules(containers([READER, API], [`| Lector | API | ${label} | HTTPS |`])), ['que-viaja'], `etiqueta "${label}"`);
}
assert.deepEqual(rules(containers([READER, API], ['| Lector | API | Consulta sus préstamos vigentes | HTTPS |'])), []);
});
test('toda relación dice por qué protocolo', () => {
assert.deepEqual(rules(containers([READER, API], ['| Lector | API | Busca libros y renueva préstamos | |'])), ['protocolo']);
assert.deepEqual(rules(containers([READER, API], ['| Lector | API | Busca libros y renueva préstamos | — |'])), ['protocolo']);
});
test('la misma flecha no se escribe dos veces', () => {
assert.deepEqual(rules(containers([READER, API], [READER_API, READER_API])), ['repetida']);
// Dos flechas entre las mismas cajas sí, si llevan cosas distintas.
assert.deepEqual(rules(containers([READER, API], [READER_API, '| Lector | API | Reserva un libro prestado | HTTPS, JSON |'])), []);
});
});
describe('coherencia entre contexto y contenedores', () => {
const contextText = [
'# Prueba: contexto',
'- Nivel: contexto',
'- Sistema: Prueba',
'## Elementos',
'| Nombre | Tipo | Descripción | Tecnología |',
'|---|---|---|---|',
READER,
'| Prueba | sistema | Préstamos de la biblioteca de la universidad | Aplicación web y PostgreSQL |',
'| Servidor de correo | sistema externo | Entrega los avisos a los lectores | SMTP de la universidad |',
'## Relaciones',
'| De | Hacia | Qué viaja | Protocolo |',
'|---|---|---|---|',
'| Lector | Prueba | Busca libros y renueva préstamos | HTTPS |',
'| Prueba | Servidor de correo | Envía avisos de vencimiento | SMTP |',
].join('\n');
test('lo que rodea al sistema es lo mismo en los dos diagramas', () => {
const context = checkDiagram(contextText);
const inside = checkDiagram(containers([READER, API], [READER_API]));
assert.deepEqual(context.issues, []);
assert.deepEqual(inside.issues, []);
const issues = checkSet([
{ file: 'context.md', diagram: context.diagram },
{ file: 'containers.md', diagram: inside.diagram },
]);
assert.equal(issues.length, 1);
assert.equal(issues[0]!.file, 'containers.md');
assert.match(issues[0]!.message, /"Servidor de correo" está en context\.md/);
});
test('diagramas de sistemas distintos no se comparan', () => {
const context = checkDiagram(contextText);
const other = checkDiagram(containers([API, DB], [API_DB]).replace('- Sistema: Prueba', '- Sistema: Otro'));
assert.deepEqual(checkSet([{ file: 'a.md', diagram: context.diagram }, { file: 'b.md', diagram: other.diagram }]), []);
});
});
describe('el comando check-c4.ts', () => {
const run = (...files: string[]): { status: number | null; stdout: string; stderr: string } => {
const result = spawnSync(process.execPath, ['check-c4.ts', ...files], { cwd: here, encoding: 'utf8' });
return { status: result.status, stdout: result.stdout, stderr: result.stderr };
};
test('termina con 0 y un resumen por archivo cuando todo está bien', () => {
const result = run('example/context.md', 'example/containers.md');
assert.equal(result.status, 0);
assert.equal(
result.stdout,
'example/context.md: contexto de Qillqa, 5 elementos, 5 relaciones: sin errores\n' +
'example/containers.md: contenedores de Qillqa, 8 elementos, 8 relaciones: sin errores\n',
);
});
test('termina con 1 y una línea por error, con archivo y número de línea', () => {
const result = run('errors/containers.md');
assert.equal(result.status, 1);
assert.match(result.stdout, /^errors\/containers\.md:16: \[tecnologia\] "Backend" no dice con qué tecnología está hecho$/m);
assert.match(result.stdout, /12 errores\n$/);
});
test('termina con 2 si no recibe archivos o no puede leer alguno', () => {
assert.equal(run().status, 2);
assert.equal(run('no-existe.md').status, 2);
});
});// Pruebas de module-graph.ts sobre un proyecto mínimo creado para la prueba.
import assert from 'node:assert/strict';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { after, before, describe, test } from 'node:test';
import { moduleGraph, mutualPairs } from './module-graph.ts';
describe('grafo de imports entre carpetas', () => {
let src = '';
const files: Record<string, string> = {
'main.ts': "import { start } from './http/server.ts';\n",
'db.ts': 'export const db = 1;\n',
'http/server.ts': "import { loan } from '../loans/index.ts';\nimport { helper } from './helper.ts';\n",
'http/helper.ts': 'export const helper = 1;\n',
// Un import de varias líneas y uno de solo tipos también cuentan.
'loans/index.ts': "export { loan } from './loan.ts';\n",
'loans/loan.ts': "import {\n findBook,\n type Book,\n} from '../books/index.ts';\nimport { db } from '../db.ts';\nimport type { Reader } from '../readers/types.ts';\n",
'books/index.ts': "import { loan } from '../loans/index.ts';\nimport pg from 'pg';\n",
'readers/types.ts': 'export type Reader = { id: number };\n',
};
before(() => {
src = mkdtempSync(join(tmpdir(), 'w01-graph-'));
for (const [path, text] of Object.entries(files)) {
mkdirSync(dirname(join(src, path)), { recursive: true });
writeFileSync(join(src, path), text);
}
});
after(() => rmSync(src, { recursive: true, force: true }));
test('cuenta los imports que cruzan carpetas, y no los internos ni los de paquetes', () => {
assert.deepEqual(moduleGraph(src), [
{ from: 'books/', to: 'loans/', imports: 1 },
{ from: 'http/', to: 'loans/', imports: 1 },
{ from: 'loans/', to: 'books/', imports: 1 },
{ from: 'loans/', to: 'db.ts', imports: 1 },
{ from: 'loans/', to: 'readers/', imports: 1 },
{ from: 'main.ts', to: 'http/', imports: 1 },
]);
});
test('encuentra las carpetas que se importan en los dos sentidos', () => {
assert.deepEqual(mutualPairs(moduleGraph(src)), [['books/', 'loans/']]);
});
});// Lo que los apuntes de la semana 1 afirman sobre el Tinkuy inicial, como
// pruebas. Leen la copia de build/tinkuy (la crea `make`): si Tinkuy cambia y
// una de estas pruebas falla, hay que corregir el apunte, no la prueba.
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { describe, test } from 'node:test';
import { moduleGraph, mutualPairs } from './module-graph.ts';
const tinkuy = join(import.meta.dirname, 'build', 'tinkuy');
const src = join(tinkuy, 'src');
describe('el Tinkuy inicial, visto desde sus archivos', () => {
const edges = moduleGraph(src);
const imports = (from: string, to: string): number => edges.find((edge) => edge.from === from && edge.to === to)?.imports ?? 0;
test('src/ tiene cinco módulos y la carpeta http, que es la entrada', () => {
const folders = readdirSync(src).filter((name) => statSync(join(src, name)).isDirectory()).sort();
assert.deepEqual(folders, ['catalog', 'http', 'notifications', 'orders', 'payments', 'reports']);
});
test('las dependencias entre carpetas son las de la tabla del apunte', () => {
const betweenFolders = edges
.filter((edge) => edge.from.endsWith('/') && edge.to.endsWith('/'))
.map((edge) => `${edge.from} -> ${edge.to} ${edge.imports}`);
assert.deepEqual(betweenFolders, [
'catalog/ -> orders/ 1',
'http/ -> catalog/ 1',
'http/ -> orders/ 1',
'http/ -> reports/ 1',
'orders/ -> catalog/ 1',
'orders/ -> notifications/ 1',
'orders/ -> payments/ 5',
'reports/ -> catalog/ 1',
'reports/ -> orders/ 1',
]);
});
test('catalog y orders se importan en los dos sentidos', () => {
assert.deepEqual(mutualPairs(edges), [['catalog/', 'orders/']]);
});
test('cinco carpetas importan db.ts: las consultas no viven en un solo módulo', () => {
const users = edges.filter((edge) => edge.to === 'db.ts').map((edge) => edge.from);
assert.deepEqual(users, ['catalog/', 'http/', 'notifications/', 'orders/', 'reports/']);
assert.equal(imports('payments/', 'db.ts'), 0);
});
test('el único paquete externo que importa el código es pg, y solo desde db.ts', () => {
const packages = new Set<string>();
const walk = (dir: string): void => {
for (const name of readdirSync(dir)) {
const path = join(dir, name);
if (statSync(path).isDirectory()) walk(path);
else {
for (const match of readFileSync(path, 'utf8').matchAll(/\bfrom\s+'([^.'][^']*)'/g)) {
if (!match[1]!.startsWith('node:')) packages.add(`${match[1]!} en ${path.slice(src.length + 1)}`);
}
}
}
};
walk(src);
assert.deepEqual([...packages], ['pg en db.ts']);
});
test('el costo de cambiar cuatro decisiones, contado en archivos', () => {
const result = spawnSync('bash', ['change-cost.sh', tinkuy], { cwd: import.meta.dirname, encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
const counts = result.stdout
.trim()
.split('\n')
.map((line) => /(\d+) de (\d+) archivos$/.exec(line)!.slice(1).map(Number));
assert.deepEqual(counts, [
[1, 31],
[2, 31],
[12, 31],
[10, 31],
]);
});
test('main.ts levanta un solo servidor HTTP: los módulos no son procesos', () => {
const main = readFileSync(join(src, 'main.ts'), 'utf8');
assert.equal(main.match(/\.listen\(/g)?.length, 1);
const listeners = spawnSync('grep', ['-rlE', '\\.listen\\(', src], { encoding: 'utf8' }).stdout.trim().split('\n');
assert.deepEqual(listeners, [join(src, 'main.ts')]);
});
});Laboratorio
Archivos de partida del laboratorio de la semana.
# Tinkuy: diagrama de contenedores
- Nivel: contenedores
- Sistema: Tinkuy
<!-- Dos o tres líneas: qué muestra este diagrama y qué deja fuera. -->
## Elementos
<!-- Una fila por caja. Tipos de este nivel: persona, sistema externo,
contenedor y almacén de datos. Las personas y los sistemas externos son
los mismos del diagrama de contexto. Tinkuy ya no es una caja: aquí van
sus partes. -->
| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
## Relaciones
<!-- Una fila por flecha. "De" y "Hacia" son nombres de la tabla de arriba.
"Qué viaja" empieza con un verbo y dice qué lleva la flecha. -->
| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|# Tinkuy: diagrama de contexto
- Nivel: contexto
- Sistema: Tinkuy
<!-- Dos o tres líneas: qué es el sistema y para quién es este diagrama. -->
## Elementos
<!-- Una fila por caja. Tipos de este nivel: persona, sistema (uno solo: Tinkuy)
y sistema externo. En Tecnología, una persona lleva "—". -->
| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
## Relaciones
<!-- Una fila por flecha. "De" y "Hacia" son nombres de la tabla de arriba.
"Qué viaja" empieza con un verbo y dice qué lleva la flecha. -->
| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|Compilación
Cómo se compilan y ejecutan los ejemplos.
# Semana 1: qué es la arquitectura y qué la determina. Se usa dentro del
# contenedor del curso.
#
# make copia Tinkuy en build/tinkuy (los ejemplos leen la copia)
# make test revisa los tipos (tsc) y corre las pruebas (*.test.ts):
# el formato de los diagramas, su revisor y lo que el
# apunte dice del Tinkuy inicial
# make example revisa los dos diagramas de ejemplo (example/)
# make errors revisa el diagrama con errores (errors/): falla a propósito
# make check-c4 revisa sus diagramas: make check-c4 DOCS=/work/tinkuy-suusuario/docs/c4
# make imports la estructura de módulos de Tinkuy: quién importa a quién
# make change-cost cuántos archivos de Tinkuy toca cambiar cuatro decisiones
# make clean borra build/
#
# Nada de esto modifica el Tinkuy del curso (../../tinkuy).
TINKUY ?= ../../tinkuy
DOCS ?= docs/c4
.PHONY: all test example errors check-c4 imports change-cost clean
all: build/tinkuy
build/tinkuy:
mkdir -p build
cp -r $(TINKUY) $@
test: build/tinkuy
tsc -p .
node --test "*.test.ts"
example:
node check-c4.ts example/context.md example/containers.md
# El revisor termina con error cuando encuentra algo: aquí eso es lo que se quiere ver.
errors:
@node check-c4.ts errors/containers.md ; echo "check-c4 terminó con código $$?"
check-c4:
node check-c4.ts $(DOCS)/context.md $(DOCS)/containers.md
imports: build/tinkuy
@node module-graph.ts build/tinkuy/src
change-cost: build/tinkuy
@bash change-cost.sh build/tinkuy
clean:
rm -rf build{
"name": "week-01",
"private": true,
"type": "module"
}{
"compilerOptions": {
"target": "es2024",
"lib": ["es2024"],
"module": "nodenext",
"moduleResolution": "nodenext",
"types": ["node"],
"strict": true,
"noEmit": true,
"allowImportingTsExtensions": true,
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": ["*.ts"],
"exclude": ["build"]
}