Apuntes · Capítulo 1Fundamentos y atributos de calidad
Qué es la arquitectura y qué la determina
Qué es la arquitectura y qué la determina
Ruta de lectura.
- Antes de clase (obligatorio, unos 20 minutos): El curso en una página; de Qué es la arquitectura, Estructuras para razonar y Las decisiones que cuesta cambiar; y de Qué determina una arquitectura, Requisitos significativos para la arquitectura.
- En clase: Sesión A: Qué es la arquitectura, Tres tipos de estructuras, Arquitectura, diseño y funcionalidad y Por qué importa la arquitectura. Sesión B: Qué determina una arquitectura y Dibujar lo que hay: los dos primeros niveles de C4. Laboratorio: Laboratorio: el entorno, un recorrido por Tinkuy y sus primeros diagramas.
- Después de clase: el Resumen y los Ejercicios. Para repasar antes del laboratorio: Diagramas como texto: el formato del curso y Un diagrama con errores. Opcionales: Un ejemplo completo: los requisitos de Qillqa, El código de la semana y
make testy las lecturas complementarias del recuadro Lectura.
Hasta ahora, en la carrera, casi todas las preguntas sobre un programa tenían una respuesta que se podía comprobar en el momento: compila o no compila, la prueba pasa o no pasa, la consulta devuelve las filas correctas o no. Este curso trata de otra clase de preguntas. ¿Qué pasa con la venta de entradas si el servicio que cobra las tarjetas tarda diez segundos en responder? ¿Cuántos archivos hay que tocar para aceptar un medio de pago nuevo? ¿Aguanta el sistema el minuto en que se abre la venta de un concierto? Ninguna se responde mirando una función. Se responden mirando cómo está dividido el sistema, qué partes existen cuando corre, cómo se hablan entre ellas y dónde viven los datos. A eso le vamos a llamar arquitectura.
Este primer capítulo hace tres cosas. Primero define la palabra con cuidado, porque se usa con mucha soltura y casi siempre para hablar de otra cosa (un diagrama, una lista de tecnologías). Después responde de dónde sale una arquitectura: qué requisitos la determinan, quién los pide y qué decisiones ya vienen tomadas. Y al final enseña a dibujar lo que hay: los dos primeros niveles del modelo C4, escritos como texto, que es la forma en que van a describir sistemas durante todo el semestre.
El sistema que nos acompaña es Tinkuy, una plataforma de venta de entradas para conciertos y partidos. Hoy lo corremos, lo recorremos y lo miramos sin cambiarle nada. Como ejemplo resuelto usamos otro sistema, más chico: Qillqa, los préstamos de la biblioteca de una universidad. La razón de usar dos es simple: dibujar Tinkuy es su trabajo de esta semana, y no tendría gracia que el capítulo lo hiciera por ustedes.
Lectura. Sesión A: Bass, Clements y Kazman, Software Architecture in Practice (4.ª ed.), cap. 1 What Is Software Architecture? y cap. 2 Why Is Software Architecture Important?; Martin Fowler, Who Needs an Architect? (2003), sobre la arquitectura como “lo que cuesta cambiar”. Complementarias: Fowler, Software Architecture Guide; Simon Brown, The C4 model: abstractions, sobre sistema, contenedor y componente.
Sesión B: Software Architecture in Practice, cap. 19 Architecturally Significant Requirements, las 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); Simon Brown, C4: diagramas, los de contexto y de contenedores. 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.
El código de este capítulo está en code/week-01/. Todas las salidas que se muestran son de ejecuciones reales en el contenedor del curso.
El curso en una página
Cuatro partes y un sistema
El curso tiene cuatro partes. En la primera, fundamentos y atributos de calidad (semanas 1 a 3), aprendemos a decir con precisión qué se le pide a un sistema además de que funcione, y a medirlo. En la segunda, estilos, tácticas y decisiones (semanas 4 a 7), vemos las formas conocidas de organizar un sistema, las técnicas para lograr cada atributo de calidad y cómo se documenta y se evalúa una decisión. La tercera, datos y sistemas distribuidos (semanas 9 a 13), trata la replicación, el sharding, la cache, las transacciones y la mensajería como decisiones con costos. La cuarta, fallas, operación y evolución (semanas 14 a 16), se ocupa de lo que pasa cuando el sistema ya está en producción: qué hace cuando algo falla, cómo se observa y cómo se cambia sin detenerlo. El calendario completo está en el sílabo.
Todo el curso gira alrededor de un solo sistema, Tinkuy, que empieza como un monolito pequeño que funciona. En el proyecto lo van a rediseñar seis veces. En cada entrega llega un requisito de calidad nuevo que el diseño de ese momento no cumple: que se pueda agregar un medio de pago sin tocar el núcleo, que la apertura de ventas de un concierto no venda un asiento dos veces, que una pasarela de pagos caída no tumbe la venta. La descripción del proyecto está en projects/README.md.
Que sea siempre el mismo sistema es a propósito. La arquitectura se entiende cuando uno ve qué le pasa a un diseño al cambiar lo que se le pide, y eso no se ve con un ejemplo distinto cada semana.
La regla de trabajo
Hay una regla que vale para todo el semestre, en clase, en los laboratorios y en el proyecto. Una decisión de arquitectura:
- se justifica con un escenario: una situación concreta, con su medida, que el sistema tiene que cumplir (“con 200 compradores a la vez, el 95 % de las compras responde en menos de un segundo”);
- se compara con una alternativa: si solo hubo una opción sobre la mesa, no hubo decisión;
- se escribe: quien llegue después tiene que poder saber por qué se decidió así y qué se descartó;
- se mide: antes y después, en la misma máquina.
La regla descarta dos formas muy comunes de discutir arquitectura. Una es el argumento de autoridad: “así lo hace tal empresa”. Esa empresa tiene otros escenarios, otro equipo y otro presupuesto. La otra es el adjetivo: “esto es más escalable”, “esto es más limpio”. Un adjetivo sin escenario y sin medida no se puede discutir, porque no se puede saber cuándo es falso.
En arquitectura casi ninguna pregunta tiene una respuesta correcta para todos los sistemas. La respuesta honesta suele empezar con “depende”, y el trabajo consiste en decir de qué depende y cómo se decide en este caso.
Qué es la arquitectura
Un sistema para pensar: Tinkuy
Antes de definir nada, conviene tener un sistema delante. Tinkuy vende entradas para conciertos y partidos de fútbol: publica los eventos de varios locales, muestra qué asientos quedan, cobra con tarjeta o con Yape y emite una entrada por asiento. Su README describe la API y las reglas del negocio.
Dentro del contenedor del curso, la base de datos se crea con un comando:
$ cd tinkuy
$ make db
Semilla 7: 6 locales, 24 eventos, 75 secciones, 13080 asientos (3225 vendidos), 1303 órdenes, 1303 pagos, 3225 entradas, 1303 notificaciones
Con make gateway en una terminal y make start en otra, ya se puede
comprar. Dos asientos de la sección Preferencial del evento 1, con Yape:
$ curl -s -X POST localhost:3000/orders -H 'content-type: application/json' -d '{
"eventId": 1,
"seatIds": [1001, 1002],
"buyer": { "email": "rosa.quispe@correo.pe", "name": "Rosa Quispe" },
"payment": { "method": "yape", "phone": "987654321", "approvalCode": "482913" }
}'
{"order":{"id":1304,"eventId":1,"status":"paid","buyer":{"email":"rosa.quispe@correo.pe","name":"Rosa Quispe"},"paymentMethod":"yape","subtotalCents":32000,"feeCents":0,"totalCents":32000,"createdAt":"2026-11-16T05:39:22.349Z"},"tickets":[{"id":3226,"code":"TKY-BE82AD314FEE","seatId":1001,"sectionName":"Preferencial","row":"P","number":1,"priceCents":16000},{"id":3227,"code":"TKY-792BD03DF3AE","seatId":1002,"sectionName":"Preferencial","row":"P","number":2,"priceCents":16000}]}
(Los códigos de las entradas se generan al azar: en su máquina saldrán otros.) Mientras tanto, la terminal del servidor fue contando lo que hacía:
Tinkuy escucha en http://localhost:3000 (base de datos "tinkuy")
...
pasarela: cobro ch_00000001 approved para orden-1304
correo: confirmación de la orden 1304 enviada a rosa.quispe@correo.pe
orden 1304: pagada, 2 entradas
POST /orders 201
Funciona. Tiene pruebas, y pasan:
$ make test
...
ℹ tests 62
ℹ suites 9
ℹ pass 62
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
Nada de lo que acabamos de ver dice si Tinkuy tiene una buena o una mala arquitectura. Las pruebas comprueban que el sistema hace lo que debe: que cobra la comisión correcta, que no vende un asiento ya vendido, que responde 404 cuando la orden no existe. No dicen qué pasa cuando llegan doscientas compras a la vez, cuánto cuesta agregar un medio de pago, ni qué ve el comprador si la pasarela se cae. Para hablar de eso necesitamos otro vocabulario.
Estructuras para razonar
La definición que usamos en el curso es la del libro de Bass, Clements y Kazman, que es además la más extendida en el área:
La arquitectura de un sistema es el conjunto de estructuras necesarias para razonar sobre él. Cada estructura está hecha de elementos, de relaciones entre esos elementos y de propiedades de ambos.
Hay tres palabras que cargan con todo el peso.
Estructuras, en plural. Un sistema no tiene una sola forma. Si uno mira las carpetas del código, ve archivos que importan a otros archivos. Si mira el sistema corriendo, ve procesos que se mandan mensajes. Si mira dónde está instalado, ve máquinas. Las tres son estructuras del mismo sistema: cada una tiene sus elementos (archivos, procesos, máquinas) y sus relaciones (importa a, le pide algo a, corre en). Ninguna es “la” arquitectura. La arquitectura es el conjunto.
Razonar. Una estructura es de arquitectura si sirve para responder una pregunta sobre el sistema sin tener que leerlo entero ni ponerlo a correr. Si sé que el proceso de Tinkuy llama a la pasarela de pagos y espera su respuesta antes de contestarle al comprador, puedo razonar así: “si la pasarela tarda diez segundos, la compra tarda al menos diez segundos”. No necesité leer ninguna función para decirlo. Me bastó un elemento (el proceso), una relación (llama y espera) y una propiedad (cuánto tarda la pasarela).
Propiedades. Las cajas y las flechas solas dicen poco. Lo que permite razonar es lo que se sabe de cada una: que la base de datos acepta hasta cierto número de conexiones, que esta llamada es síncrona, que este módulo es el único que conoce el formato de la pasarela. Un diagrama con cajas sin propiedades sirve de decoración, no de herramienta.
Idea clave. La arquitectura no es un documento ni un dibujo: es una propiedad del sistema, igual que su peso es una propiedad de un puente. Los documentos y los diagramas son descripciones de la arquitectura, y pueden estar completos, incompletos o equivocados.
Tres consecuencias de la definición
Todo sistema tiene arquitectura, aunque nadie la haya escrito. Todo sistema está hecho de partes que se relacionan. Si nadie decidió cuáles ni cómo, las partes y las relaciones existen igual: salieron de decisiones pequeñas, tomadas una por una, sin mirar el conjunto. Tinkuy no trae ningún documento de arquitectura y, sin embargo, se puede decir con exactitud qué procesos tiene, qué carpeta importa a cuál y dónde están sus datos. Lo veremos en unas páginas.
La arquitectura es una abstracción. Describir una arquitectura es elegir qué se omite. El diagrama de contenedores de un sistema no dice cómo se llama cada función, y hace bien: ese detalle no ayuda a razonar sobre latencia ni sobre fallas. La pregunta que guía qué entra y qué sale es siempre la misma: ¿sirve para razonar sobre algo que importa? Una descripción que lo incluye todo es el código fuente, y el código fuente ya lo tenemos.
No toda estructura es arquitectura. Los archivos de Tinkuy se pueden ordenar alfabéticamente: es una estructura, con sus elementos y su relación (“va antes que”), y no sirve para razonar sobre nada. Una estructura es de arquitectura solo si ayuda a razonar sobre un atributo de calidad (quality attribute) que le importa a alguien: que el sistema responda rápido, que no se caiga, que sea barato de cambiar, que no pierda una venta. La semana 2 está dedicada a esos atributos.
Error común. Creer que un sistema pequeño, o hecho con apuro, “no tiene arquitectura”. La tiene; lo que le falta es alguien que la haya decidido. Y una arquitectura que nadie decidió no es neutral: tiene consecuencias sobre la latencia, las fallas y el costo de los cambios igual que una decidida, solo que nadie las eligió.
Las decisiones que cuesta cambiar
Hay una segunda definición, complementaria, que conviene tener a la mano porque sirve para trabajar. Viene de un artículo corto de Martin Fowler, Who Needs an Architect? (2003), que es la lectura libre de esta sesión. Fowler cita allí un mensaje de Ralph Johnson a una lista de correo. Johnson discute la idea de que la arquitectura son “las decisiones de diseño que hay que tomar al comienzo de un proyecto”, y la corrige: son las decisiones que uno quisiera acertar al comienzo, sin que nada garantice que al comienzo se acierten mejor que las demás. Su conclusión es célebre: la arquitectura trata de the important stuff. Whatever that is (lo importante, sea lo que sea). Más adelante, el mismo artículo recoge otra forma de decirlo: arquitectura son las cosas que la gente percibe como difíciles de cambiar.
Las dos definiciones se complementan. La del libro dice qué es una arquitectura (estructuras) y para qué sirve (razonar). La de Fowler y Johnson dice cuáles de las miles de decisiones de un sistema merecen ese nombre: las que cuesta deshacer. Y trae una prueba práctica, que vamos a usar todo el semestre. Ante una decisión, pregunten:
¿Cuántos archivos, cuántos equipos y cuántos despliegues toca deshacerla?
Si la respuesta es “un archivo, yo, ninguno”, no es arquitectura, por importante que parezca. Si la respuesta es “la mitad del código, tres equipos, y hay que migrar los datos con el sistema apagado”, lo es, aunque se escriba en una línea.
La definición por el costo tiene una consecuencia interesante: lo que es arquitectura depende del sistema. El ejemplo de Johnson, en el mismo mensaje, es la base de datos. Quien construye aplicaciones empresariales suele considerar que la persistencia es parte central de la arquitectura. En una aplicación de imágenes médicas, en cambio, la misma base de datos puede no serlo: casi toda la dificultad está en analizar las imágenes, y guardarlas es asunto de una parte pequeña que casi nadie mira.
Una prueba con Tinkuy: contar lo que toca un cambio
Hagamos la prueba con cuatro decisiones de Tinkuy. No hace falta opinar: se
puede contar. El script change-cost.sh
busca el rastro que deja cada decisión en el código y cuenta en cuántos
archivos de src/ aparece:
$ cd code/week-01
$ make change-cost
El puerto por omisión es 3000 1 de 31 archivos
La comisión la calcula paymentFeeCents 2 de 31 archivos
Los montos son céntimos enteros 12 de 31 archivos
Las consultas son SQL para PostgreSQL 10 de 31 archivos
Leamos cada línea.
- El puerto 3000 aparece en un archivo,
config.ts, y además se puede cambiar con una variable de entorno sin tocar nada. No es arquitectura. - El nombre
paymentFeeCentsaparece en dos archivos: donde se define y donde se usa. Un editor lo renombra en un segundo. Tampoco. - Los montos en céntimos enteros aparecen en 12 de los 31 archivos, y la
cuenta se queda corta: también son columnas de la base de datos
(
price_cents,total_cents,amount_cents), campos de la API que ya usan otros (totalCents) y parte del protocolo con la pasarela. Cambiarlo a soles con decimales toca el código, el esquema, los datos guardados y a quien consume la API. Es una decisión de arquitectura, y de las buenas: se tomó bien al comienzo y por eso nadie la nota. - Las consultas SQL para PostgreSQL se lanzan desde 10 archivos:
db.tsy nueve más, repartidos en cinco carpetas. Cambiar de base de datos no es reescribir un módulo: es tocar un tercio de los archivos del sistema.
La medida es gruesa. Contar archivos no distingue entre cambiar una línea y reescribir el archivo entero, y no ve lo que está fuera del código (los datos, los otros equipos). Pero alcanza para ordenar las decisiones, que es lo que queríamos: las dos primeras son baratas, las dos últimas son caras.
En Tinkuy. “Todo corre en un proceso con una base de datos PostgreSQL” es la decisión de arquitectura más grande del sistema, y no está escrita en ningún archivo: es el resultado de cómo está armado todo lo demás. Para deshacerla habría que decidir qué partes se separan, cómo se hablan, quién se queda con qué tablas y cómo se despliega cada una. El nombre de una función, en cambio, se deshace en un segundo.
Trade-off. Que una decisión sea cara de cambiar no la hace mala. Un solo proceso y una sola base de datos dan mucho a cambio: una compra es una sola transacción, hay un solo programa que desplegar y un solo lugar donde buscar un error. Lo que se paga es que todo escala junto, todo falla junto y todo se despliega junto. Si eso conviene o no depende de lo que se le pida al sistema, y eso es justo lo que todavía no hemos dicho.
Tres tipos de estructuras
Dijimos que la arquitectura es un conjunto de estructuras. Son muchas, pero caen en tres familias, y cada familia responde una pregunta distinta. La clasificación es la del libro del curso, y vale la pena aprenderla bien porque ordena todo lo que viene.
| Tipo de estructura | Sus elementos | Sus relaciones | La pregunta que responde |
|---|---|---|---|
| De módulos | Unidades de código: carpetas, paquetes, clases | “depende de”, “es parte de”, “usa” | ¿Qué toca un cambio? ¿Quién es owner de qué? |
| De componentes y conectores | Lo que existe mientras el sistema corre: procesos, bases de datos, colas | “le pide”, “le envía”, “lee de” (los conectores) | ¿Qué pasa con la latencia y con las fallas? |
| De asignación | El software y algo que no es software: máquinas, repositorios, equipos | “corre en”, “se guarda en”, “lo mantiene” | ¿Quién lo construye y dónde corre? |
Estructuras de módulos
Una estructura de módulos describe cómo está dividido el código: qué unidades hay y qué depende de qué. Existe aunque el sistema esté apagado: se lee en los archivos.
En Tinkuy los módulos son las carpetas de src/:
$ ls tinkuy/src
catalog
config.ts
db.ts
errors.ts
http
log.ts
main.ts
notifications
orders
payments
reports
Cinco carpetas son módulos del negocio (catalog, orders, payments,
notifications, reports), una es la entrada al sistema (http) y hay
cinco archivos sueltos que usan todos. La relación entre módulos se lee en
los import. El comando de la guía de laboratorio cuenta cuántas veces se
importa cada cosa desde otra carpeta:
$ cd tinkuy
$ grep -rhoE "from '\.\./[a-z]+" src | sort | uniq -c
3 from '../catalog
2 from '../config
9 from '../db
9 from '../errors
4 from '../log
1 from '../notifications
3 from '../orders
5 from '../payments
1 from '../reports
Eso dice qué se importa, pero no quién lo importa: la opción -h de
grep esconde el nombre del archivo. Para dibujar el grafo hace falta el
otro extremo de cada flecha. Una forma es repetir el comando carpeta por
carpeta (src/http, src/orders, …). Otra es
module-graph.ts, que hace la misma
cuenta y dice las dos puntas:
$ cd code/week-01
$ make imports
catalog/ -> db.ts 3
catalog/ -> errors.ts 1
catalog/ -> orders/ 1
db.ts -> config.ts 1
http/ -> catalog/ 1
http/ -> db.ts 1
http/ -> errors.ts 4
http/ -> log.ts 1
http/ -> orders/ 1
http/ -> reports/ 1
log.ts -> config.ts 1
main.ts -> config.ts 1
main.ts -> http/ 1
main.ts -> log.ts 1
notifications/ -> config.ts 1
notifications/ -> db.ts 1
notifications/ -> log.ts 1
orders/ -> catalog/ 1
orders/ -> db.ts 3
orders/ -> errors.ts 2
orders/ -> log.ts 1
orders/ -> notifications/ 1
orders/ -> payments/ 5
payments/ -> config.ts 1
payments/ -> errors.ts 1
payments/ -> log.ts 1
reports/ -> catalog/ 1
reports/ -> db.ts 1
reports/ -> errors.ts 1
reports/ -> orders/ 1
En los dos sentidos: catalog/ <-> orders/
Con esa lista ya se puede razonar, que es para lo que sirve una estructura:
- Un cambio en
payments/puede afectar aorders/, que lo importa cinco veces, y a nadie más. Un cambio endb.tspuede afectar a cinco carpetas. payments/no importadb.ts: no toca la base de datos. Es una propiedad del módulo, y se ve sin abrir ninguno de sus archivos.catalog/yorders/se importan mutuamente. Ninguno de los dos se puede entender, probar ni mover sin el otro. De por qué eso importa y de cómo se evita nos ocupamos en la semana 3.
Lo que esta estructura no dice es qué pasa cuando el sistema corre. La
flecha orders/ -> payments/ puede ser una llamada a una función que tarda
microsegundos o una llamada por la red que tarda segundos: en los import
se ven idénticas.
Estructuras de componentes y conectores
Una estructura de componentes y conectores describe lo que existe mientras el sistema está corriendo. Los componentes son las unidades de ejecución y de datos: procesos, bases de datos, colas. Los conectores son los caminos por donde se comunican: una llamada HTTP, una conexión a la base de datos, un mensaje en una cola. Esta estructura no se lee en los archivos: se observa con el sistema encendido.
Con Tinkuy y la pasarela corriendo, dentro del contenedor del curso:
$ ps -eo pid,args | grep -E "node|postgres$|redis|nats" | grep -v grep
12 postgres
80 redis-server *:6379
104 nats-server --jetstream --store_dir /var/lib/nats --http_port 8222
193 node tools/fake-gateway.ts
194 node src/main.ts
Redis y NATS vienen encendidos con el contenedor, pero el Tinkuy inicial no
los usa: son para más adelante. Lo que queda es poco. Todo Tinkuy es un
solo proceso, node src/main.ts. Las cinco carpetas que acabamos de ver
no aparecen: catalog, orders y payments no son procesos, son código que
corre dentro del mismo. Al lado hay un proceso de PostgreSQL, que guarda los
datos, y la pasarela de pagos de prueba, que en el curso hace el papel de un
servicio que en producción sería de un banco.


Las preguntas que responde esta estructura son otras:
- Si el proceso de Tinkuy se cae, ¿qué deja de funcionar? Todo: el catálogo, las compras y los reportes viven en él.
- Si la pasarela tarda, ¿quién espera? Para saberlo hay que conocer el conector: si la llamada es síncrona, quien llamó espera.
- ¿Cuántas conexiones abre Tinkuy hacia PostgreSQL cuando atiende cien pedidos a la vez? Depende de una propiedad del conector que hoy no conocemos y que el laboratorio empieza a averiguar.
En Tinkuy. El mismo sistema, visto con dos estructuras, da dos números distintos: cinco módulos y un solo proceso. Las dos descripciones son verdaderas y ninguna reemplaza a la otra. Quien dice “Tinkuy tiene cinco partes” y quien dice “Tinkuy es una sola pieza” están mirando estructuras diferentes.
Estructuras de asignación
Una estructura de asignación relaciona el software con algo que no es software: en qué máquina corre cada proceso, en qué repositorio vive cada módulo, qué equipo mantiene cada parte. Responde quién lo construye y dónde corre.
En el curso, la asignación de Tinkuy es mínima: todos los procesos corren en un contenedor de Docker dentro de su laptop, todo el código está en un repositorio y lo mantiene una pareja. Por eso hoy casi no hablaremos de ella. Pero es la estructura que más cambia cuando un sistema crece, y la que explica por qué algunas decisiones técnicas son en realidad decisiones sobre personas: si dos equipos tienen que tocar el mismo módulo para cada cambio, el problema se ve en la asignación de módulos a equipos, no en el código. Volveremos sobre esto con la ley de Conway, en la semana 15.
En la industria. En febrero de 2016, Nick Craver publicó la lista de máquinas que servían Stack Overflow y sus sitios hermanos: 4 servidores de SQL Server, 11 servidores web con IIS, 2 de Redis, 3 para el motor de etiquetas, 3 de Elasticsearch y 4 load balancers HAProxy, además del equipo de red. Esa lista es una vista de asignación: dice qué corre dónde. Lo que no dice, y ninguna vista de asignación dice, es cómo está dividido el código por dentro.
Un mismo sistema, tres dibujos distintos
Las tres familias no son tres niveles de detalle del mismo dibujo. Son tres dibujos distintos, con elementos distintos, y no hay forma de deducir uno a partir de otro.
| Pregunta sobre Tinkuy | Estructura que la responde | Dónde se mira |
|---|---|---|
| Si cambia el formato de la respuesta de la pasarela, ¿qué archivos hay que revisar? | Módulos | Los import |
| Si PostgreSQL deja de responder, ¿qué ve el comprador? | Componentes y conectores | El sistema corriendo |
| ¿Se puede desplegar un cambio en los reportes sin reiniciar las compras? | Componentes y conectores, y asignación | Qué proceso contiene qué y dónde corre |
| ¿Quién aprueba un cambio en el módulo de pagos? | Asignación | Quién es owner de qué |
Una confusión frecuente es creer que cada módulo corresponde a un componente. A veces pasa (un microservicio suele ser un módulo, un proceso y un equipo a la vez), pero no hay ninguna obligación. Tinkuy tiene cinco módulos en un proceso. Un mismo módulo puede correr en varios procesos (una biblioteca compartida), y un proceso puede cargar módulos de varios repositorios. Por eso, cuando alguien diga “el componente de pagos”, pregunten siempre: ¿el código o lo que corre?
Idea clave. Antes de responder una pregunta de arquitectura, decidan qué estructura hay que mirar. “¿Qué toca un cambio?” se responde con los módulos. “¿Qué pasa si esto falla o tarda?” se responde con los componentes y los conectores. “¿Quién y dónde?”, con la asignación.
Arquitectura, diseño y funcionalidad
Arquitectura y diseño
¿Dónde termina la arquitectura y empieza el diseño? No hay una frontera
nítida, y no hace falta buscarla. Es la misma actividad, decidir cómo se
divide algo y cómo se comunican sus partes, a distinta escala. Elegir si
paymentFeeCents recibe el medio de pago como texto o como objeto es diseño.
Elegir si los pagos corren en el mismo proceso que las órdenes es
arquitectura. Lo que cambia entre una y otra es el costo de equivocarse.
Por eso la prueba del costo de cambio sirve mejor que cualquier lista de
temas. No existe una lista de “cosas que son arquitectura”. La elección de la
base de datos lo es en Tinkuy y, como vimos con el ejemplo de Johnson, puede
no serlo en otro sistema. Hasta el nombre de un campo puede serlo: totalCents
es un nombre, pero está en la respuesta de una API que otros ya usan, y
cambiarlo rompe a quienes dependen de él.
Una consecuencia práctica: las decisiones baratas de cambiar no merecen una discusión larga. Se toman, y si salen mal se corrigen. El cuidado, las alternativas escritas y las mediciones se reservan para las caras. Tratar todas las decisiones con la misma ceremonia es tan mal uso del tiempo como no tratar ninguna.
Arquitectura y funcionalidad
La funcionalidad es lo que el sistema hace: listar eventos, vender entradas, emitir un reporte. Es natural pensar que la arquitectura se deduce de ella, y no es así. La misma funcionalidad se puede construir con arquitecturas muy distintas.
Tinkuy podría ser un solo proceso con una base de datos, que es lo que es hoy. Podría ser tres servicios, cada uno con sus datos, que se hablan por la red. Podría ser un proceso que recibe las compras y las deja en una cola, y otro que las cobra después. En los tres casos el comprador ve lo mismo: elige asientos, paga y recibe sus entradas. Las pruebas funcionales, que entran por HTTP y miran las respuestas, pasarían igual en las tres.
Lo que cambia entre una arquitectura y otra es qué tan bien se cumple cada atributo de calidad:
| Un proceso, una base de datos | Varios servicios por la red | |
|---|---|---|
| Una compra es una sola transacción | Sí, la da la base de datos | No: hay que coordinar entre servicios |
| Se puede desplegar pagos sin tocar el resto | No | Sí |
| Una falla en reportes puede tumbar las compras | Sí, comparten proceso | No necesariamente |
| Seguir un error de punta a punta | Un log, un proceso | Varios logs, varios procesos |
| Lo que hay que operar | Un programa | Varios programas, y la red entre ellos |
Ninguna columna gana en todas las filas. Por eso la funcionalidad no alcanza para elegir: lo que decide son los atributos de calidad que le importan a este sistema, y en qué orden. Los estilos de la tabla, con sus costos completos, son el tema de las semanas 4 y 5.
Idea clave. La funcionalidad dice qué hace el sistema; la arquitectura determina qué tan bien lo hace bajo carga, ante una falla o frente a un cambio. Si dos diseños hacen lo mismo, la diferencia entre ellos se mide en atributos de calidad.
Por qué importa la arquitectura
Si la funcionalidad se puede lograr con cualquier arquitectura, ¿por qué dedicarle un curso? El segundo capítulo del libro da una lista larga de razones. Estas cinco son las que usaremos todo el semestre.
Habilita o impide los atributos de calidad. Que Tinkuy pueda atender la apertura de ventas de un concierto no depende de qué tan bien esté escrita cada función: depende de cuántos procesos hay, de cómo usan la base de datos y de qué se hace dentro de la transacción de compra. Una arquitectura no garantiza un atributo (se puede escribir código lento sobre cualquier diseño), pero sí puede hacerlo imposible.
Permite razonar sobre el costo de un cambio. Con la estructura de módulos a la vista se puede estimar qué toca un cambio antes de hacerlo. Sin ella, cada estimación es una apuesta. Y como la mayor parte del costo de un sistema se paga después de la primera versión, en cambios, poder razonar sobre ellos vale mucho.
Es lo primero que se decide y lo más difícil de corregir. Las primeras decisiones (un proceso o varios, una base de datos o varias, síncrono o por mensajes) condicionan todas las que siguen. Se toman cuando menos se sabe del problema, y por eso son las que más conviene tomar con cuidado y dejar escritas. Es la observación de Johnson otra vez: son las decisiones que uno quisiera acertar temprano.
Define cómo se reparte el trabajo. Los módulos son también unidades de trabajo: lo que un equipo puede construir, probar y entregar sin coordinarse a cada paso con los demás. Una división en módulos que obliga a tres equipos a tocar el mismo archivo es un problema de arquitectura, aunque el código funcione.
Se puede evaluar antes de construir. Con una descripción de la arquitectura y unos escenarios concretos se pueden encontrar problemas en una pizarra, cuando corregirlos cuesta una tarde, y no en producción. En la semana 7 haremos una evaluación de ese tipo sobre Tinkuy.
Error común. Confundir la arquitectura con un diagrama o con una lista de tecnologías. “Nuestra arquitectura es React y PostgreSQL” no dice qué partes tiene el sistema, cómo se comunican ni qué pasa cuando una falla. El diagrama es una vista de la arquitectura, y la tecnología es una decisión entre muchas. Dos sistemas con las mismas tecnologías pueden tener arquitecturas opuestas, y el mismo diseño se puede construir con otras.
Qué determina una arquitectura
Hasta aquí, qué es una arquitectura. Ahora, de dónde sale. Si la funcionalidad no la determina, ¿qué la determina? Tres cosas: unos pocos requisitos que pesan más que todos los demás, las personas que los piden y las decisiones que ya vienen tomadas.
Requisitos significativos para la arquitectura
Un sistema tiene cientos de requisitos. Casi ninguno afecta su arquitectura. Que el comprador pueda filtrar los eventos por ciudad, que la entrada tenga un código, que la comisión con tarjeta sea de 3,5 %: todos se resuelven en una función o en una consulta, y se pueden agregar, quitar o cambiar sin que la forma del sistema se entere.
Unos pocos son distintos.
Un requisito significativo para la arquitectura (architecturally significant requirement, ASR) es un requisito que, si cambiara, cambiaría la arquitectura.
La definición trae su propia prueba: tomen el requisito, cámbienlo y miren si el diseño tendría que ser otro. Dos requisitos de Tinkuy:
- “El comprador puede elegir su asiento.” Si mañana el negocio decide que los asientos se asignan solos, cambia una pantalla y una función. Los procesos, la base de datos y la forma de comunicarse siguen igual. No es un ASR.
- “Cuando se abre la venta de un concierto, 20 000 personas intentan comprar en el primer minuto.” Si fueran 20 personas, cualquier diseño serviría. Con 20 000, hay que decidir cuántos procesos atienden, cómo se reparten las conexiones a la base de datos, qué se hace mientras se espera a la pasarela y qué ve el comprador que no alcanzó a entrar. Este requisito determina la arquitectura.
Los dos hablan de lo mismo, comprar entradas. La diferencia está en el tipo de frase. El primero dice qué hace el sistema. El segundo dice cuánto. De ahí sale una regla práctica:
Idea clave. Los ASR casi nunca dicen qué hace el sistema. Dicen cuánto (cuántos usuarios, cuántos datos), qué tan rápido, con qué frecuencia cambia algo o qué pasa si falla.
“Casi nunca” no es “nunca”. A veces un requisito funcional sí toca la arquitectura, porque obliga a que exista una pieza nueva. “El lector recibe un aviso un día antes de que venza su préstamo” es funcional, pero nadie hace un pedido al sistema en ese momento: tiene que haber algo corriendo por su cuenta, a una hora, y eso es un elemento más en la estructura de componentes y conectores. La regla sirve para buscar, no para descartar sin pensar.
Error común. Listar como ASR cosas que no se pueden comprobar: “debe ser escalable”, “debe ser seguro”, “debe ser rápido”. ¿Escalable hasta cuánto? ¿Rápido para quién, haciendo qué? Si no se puede decir cuándo se incumple, todavía no es un requisito: es un deseo. Parte del trabajo de esta semana es encontrar esos deseos; convertirlos en escenarios con una medida es el trabajo de la siguiente.
De dónde salen
Sería cómodo que los ASR vinieran escritos en un documento. Pocas veces pasa. Hay cuatro lugares donde buscarlos.
Los requisitos escritos. Es el primer lugar donde mirar y el que menos rinde. Los documentos de requisitos describen con mucho detalle lo que el sistema hace y, cuando hablan de calidad, suelen decir “debe ser rápido” o “debe estar siempre disponible”. Aun así sirven: cada frase vaga de esas marca un lugar donde hay que preguntar.
Los stakeholders. La mayoría de los ASR está en la cabeza de alguien, y se obtiene preguntando. No “¿qué tan rápido debe ser?”, que invita a responder “muy rápido”, sino preguntas con situación: “¿qué pasó la última vez que se abrió la venta de un concierto grande?”, “¿cuánto se pierde si el sistema no vende durante una hora un sábado?”, “¿qué cambio les pidieron el año pasado que tardó más de lo que esperaban?”.
Los objetivos del negocio. Un objetivo como “vender las entradas de los partidos de la selección” no menciona el software, pero trae requisitos adentro: esos partidos se agotan en minutos, así que el objetivo implica una carga que hoy el sistema nunca recibió. Buena parte de los ASR más importantes sale de preguntarle a cada objetivo del negocio qué le exige al sistema.
Lo que ya se sabe del dominio. Nadie escribe “un asiento no se vende dos veces” ni “si se cobró, la entrada existe”, porque a todos les parece obvio. Quien conoce el dominio sabe que en venta de entradas la carga llega en picos, que los pagos dependen de un tercero y que un cobro sin entrada termina en un reclamo. Ese conocimiento también es una fuente.
De los cuatro lugares sale una lista desordenada, con repeticiones y contradicciones. Hacerla explícita, ordenarla y decidir qué pesa más es parte del trabajo de arquitectura, no un paso previo que hace otro.
En la industria. El 15 de noviembre de 2022, Ticketmaster abrió la preventa de una gira de Taylor Swift. Cuatro días después publicó una explicación de lo que pasó. Según ese comunicado, más de 3,5 millones de personas se habían inscrito para la preventa y alrededor de 1,5 millones recibieron un código para entrar; el día de la venta, entre ataques de bots y personas sin código, el sitio recibió 3 500 millones de pedidos, cuatro veces su pico anterior, y la empresa estimó que cerca del 15 % de las interacciones tuvo problemas. Lo que el comunicado cuenta es la carga y el resultado. Lo que nosotros leemos en él es un ASR: la carga para la que se había planificado (los invitados) no fue la que llegó (los invitados, más todos los demás). El requisito que determina la arquitectura no es el día promedio, es el pico, y el pico incluye a quien nadie invitó.
Stakeholders
Un stakeholder es toda persona u organización con interés en el sistema. No solo quien lo usa: también quien lo paga, quien lo opera, quien lo mantiene, quien responde ante la ley por él y quien depende de él desde otro sistema.
Importan por una razón concreta: cada uno pide atributos de calidad distintos, y varios de esos pedidos se oponen. Quien compra quiere que la compra sea inmediata. Quien cuida la seguridad quiere más verificaciones antes de cobrar, y cada verificación tarda. Quien opera quiere que se cambie poco, porque cada cambio es un riesgo; el negocio quiere una promoción nueva cada semana. Ninguno está equivocado. La arquitectura es, en buena parte, el lugar donde se resuelven esos conflictos, y por eso conviene saber quién pidió qué.
Una forma útil de encontrarlos es recorrer la vida del sistema: quién lo usa, quién le entrega datos, quién recibe datos de él, quién lo despierta de madrugada cuando falla, quién lo modifica, quién lo audita.
Error común. Pensar solo en el usuario final. En casi todos los sistemas, los requisitos que más marcan la arquitectura vienen de gente que nunca abre la pantalla principal: quien opera el sistema, quien lo mantiene, quien firma el contrato con un proveedor.
Restricciones
Una restricción (constraint) es una decisión que ya viene tomada. El equipo no la elige: diseña dentro de ella.
- Técnicas: el lenguaje que el equipo conoce, la base de datos que la organización ya opera, el sistema con el que hay que integrarse tal como es.
- Del negocio: el presupuesto, el plazo, el proveedor con el que ya se firmó. Si el negocio firmó con una pasarela de pagos, esa pasarela, con su API y sus tiempos de respuesta, es un dato del problema.
- Legales: en el Perú, la Ley de Protección de Datos Personales (Ley N.° 29733) pone condiciones sobre qué datos de los compradores se pueden guardar y cómo. No es una opción de diseño.
La diferencia con un ASR es que un requisito se negocia y una restricción no. Si cumplir “p95 de 300 ms” cuesta el doble que cumplir “p95 de 500 ms”, se puede volver donde quien lo pidió y conversar. Con una restricción no hay conversación: se cumple.
Dicho eso, conviene revisar que una restricción de verdad lo sea. “Tiene que ser con microservicios” casi nunca es una restricción: es una solución que alguien propuso antes de tiempo. Detrás suele haber un requisito legítimo (“queremos desplegar pagos sin tocar lo demás”) que admite varias soluciones. Una restricción auténtica tiene detrás un contrato, una ley, un presupuesto o algo que la organización ya opera.
Lo que también influye
Además de requisitos y restricciones, tres cosas empujan la arquitectura, aunque no figuren en ningún documento.
El equipo. Su tamaño y su experiencia. Dos personas no pueden operar doce servicios, por muy bien diseñados que estén. Un equipo que nunca usó una cola de mensajes va a pagar su aprendizaje en producción.
El plazo. Con tres meses se elige distinto que con tres años, y es correcto que así sea. Una decisión tomada por plazo es legítima si se escribe como lo que es, con lo que costará revisarla.
Lo que el equipo construyó antes. Todos repetimos lo que nos funcionó. Es razonable, porque lo conocido tiene menos sorpresas, y es un sesgo, porque el sistema anterior tenía otros requisitos.
La influencia va también en el otro sentido. Una vez elegida, la arquitectura moldea a la organización: los módulos se vuelven equipos, los límites entre servicios se vuelven límites entre personas, y lo que el equipo aprendió con este sistema será lo que proponga en el siguiente. Lo retomamos con la ley de Conway en la semana 15.
Un ejemplo completo: los requisitos de Qillqa
Veamos todo junto en un sistema pequeño. Qillqa es el sistema de préstamos de la biblioteca de una universidad. Lo va a construir un equipo de dos practicantes. De las reuniones con la biblioteca salió esta lista, tal como la dijeron:
- El lector busca libros por título, autor o materia.
- Un lector puede tener hasta tres libros a la vez, por siete días, con dos renovaciones.
- Solo los estudiantes matriculados pueden pedir prestado.
- El lector recibe un aviso un día antes de que venza su préstamo.
- El sistema debe ser rápido y seguro.
- El primer día de exámenes parciales, cuando la biblioteca abre a las 8 a. m., se forma una cola de unas doscientas personas en el mostrador.
- Las reglas de préstamo las cambia el comité de biblioteca cada semestre.
- Un préstamo registrado en el mostrador no se puede perder.
Pasemos cada una por la prueba: si cambiara, ¿cambiaría la arquitectura?
| # | ¿Es un ASR? | Por qué |
|---|---|---|
| 1 | No | Se resuelve con una consulta. Buscar también por editorial no cambia la forma del sistema. |
| 2 | No, tal como está | Son tres números en una función. Pero véase el 7. |
| 3 | Esconde uno | La regla es funcional, pero crea una dependencia de un sistema ajeno, el de matrícula. La pregunta que falta: si ese sistema no responde, ¿el mostrador deja de prestar? |
| 4 | Sí, por la estructura | Nadie pide el aviso: hace falta algo que corra solo cada noche. Es un elemento más. |
| 5 | Todavía no es un requisito | No se puede decir cuándo se incumple. Hay que volver a preguntar. |
| 6 | Sí | Dice cuánto y cuándo: la carga llega en un pico, en el mostrador, y cada préstamo tiene que registrarse en segundos. |
| 7 | Sí | Dice con qué frecuencia cambia algo. Las reglas tienen que estar en un lugar que se cambie sin tocar el resto. |
| 8 | Sí | Dice qué pasa si algo falla: el préstamo tiene que estar guardado antes de que el lector se vaya con el libro. |
Tres observaciones. El requisito 5 es el más fácil de escribir y el único que no sirve. El requisito 3 parecía inocente, y al preguntar “¿y si falla?” apareció el ASR que más discusión va a dar: la biblioteca respondió que el mostrador tiene que seguir prestando aunque el sistema de matrícula esté caído. Y los requisitos 2 y 7 muestran que una misma regla del negocio puede no ser un ASR por lo que dice y serlo por la frecuencia con que cambia.
Los stakeholders de Qillqa, y lo que le importa a cada uno:
| Stakeholder | Lo que más le importa |
|---|---|
| Lectores | Encontrar el libro y saber cuándo vence el préstamo |
| Bibliotecarios | Que el mostrador no se detenga, sobre todo en la cola de las 8 a. m. |
| Jefa de la biblioteca | Que no se pierda un préstamo y poder cambiar las reglas cada semestre |
| Oficina de TI de la universidad | Operarlo sin sorpresas: un servidor, la base de datos que ya administran |
| Oficina de registro | Que Qillqa no sobrecargue su sistema de matrícula con consultas |
| Los dos practicantes | Poder mantenerlo entre dos y entregarlo a quien venga después |
Y las restricciones: la universidad ya opera PostgreSQL y un servidor de correo, y no va a instalar otros; el sistema corre en un servidor de la biblioteca; el equipo conoce TypeScript; el historial de préstamos de una persona es un dato personal, y la ley dice qué se puede hacer con él.
Fíjense en el conflicto que ya asoma. Los bibliotecarios piden que el mostrador nunca se detenga. La oficina de registro pide que no la llamen por cada préstamo. Y la regla 3 pide verificar la matrícula. No se pueden cumplir las tres al máximo: hay que decidir qué pesa más, y esa decisión (por ejemplo, guardar una copia de la lista de matriculados y aceptar que esté desactualizada unas horas) es de arquitectura. Tiene una alternativa (consultar siempre y no prestar si no hay respuesta) y un costo (durante unas horas, alguien que se retiró de la universidad todavía puede llevarse un libro). Así se ven las decisiones del curso.
Tinkuy, primera lectura
Ahora, Tinkuy. Qué vende ya lo sabemos. ¿Quiénes son sus stakeholders?
| Stakeholder | Qué quiere del sistema |
|---|---|
| Compradores | Que la compra sea rápida y que, si pagaron, la entrada exista |
| Organizadores de eventos | Vender todo el aforo y ver sus ventas al momento |
| Soporte | Poder explicar qué pasó con una orden cuando llega un reclamo |
| Quien opera el sistema de madrugada | Enterarse de que algo falla antes que los compradores, y poder arreglarlo |
| El equipo que lo mantiene | Cambiar una parte sin romper otra |
| La pasarela de pagos | Que le lleguen pedidos bien formados y no la misma orden cobrada dos veces |
| El área legal | Que los datos de los compradores se traten como dice la ley |
Cada fila pide un atributo distinto: rendimiento, disponibilidad, modificabilidad, capacidad de observar lo que pasa, seguridad. Y hay oposiciones a la vista. Los organizadores quieren el reporte de ventas al momento, mientras los compradores están comprando: las dos cosas usan la misma base de datos. El negocio quiere medios de pago nuevos pronto, y quien opera quiere pocos cambios en la parte que cobra.
¿Cuáles de los requisitos de Tinkuy son ASR? No vamos a dar la lista: es lo que sale de la clase y del laboratorio. Lo que sí podemos dar es dónde buscar, siguiendo las cuatro preguntas de la regla práctica:
- ¿Cuánto? El README dice que el evento 1 tiene 2000 asientos y que es el que se usa para las pruebas de carga. ¿Cuánta gente llega cuando abre su venta?
- ¿Qué tan rápido? ¿Cuánto espera un comprador antes de abandonar? ¿Es lo mismo esperar al mirar el catálogo que al pagar?
- ¿Con qué frecuencia cambia? Hoy hay dos medios de pago. ¿Cada cuánto aparecerá otro?
- ¿Qué pasa si falla? Recorran las piezas que vieron con
psy la pasarela. Para cada una: si se cae o tarda, ¿qué ve el comprador? ¿Se puede haber cobrado sin emitir la entrada?
La lista que salga de la clase se convierte en escenarios medibles la semana 2.
En Tinkuy. Las restricciones del proyecto son las del curso: TypeScript sobre Node.js sin frameworks, PostgreSQL, y las piezas que trae el contenedor (Redis, NATS). No se agregan servicios ni dependencias. Son restricciones de verdad, en el sentido de esta sección: no se negocian, y todo rediseño de Tinkuy se hace dentro de ellas.
Dibujar lo que hay: los dos primeros niveles de C4
Para razonar sobre una arquitectura con otras personas hay que describirla. El curso usa el modelo C4, de Simon Brown, porque es pequeño y porque obliga a decir lo que importa. C4 propone mirar un sistema con cuatro niveles de zoom: contexto, contenedores, componentes y código. Esta semana usamos los dos primeros, que según el propio modelo bastan para la mayoría de los equipos. Los otros llegan en la semana 7.
El diagrama de contexto
El diagrama de contexto muestra el sistema como una sola caja, rodeada de las personas que lo usan y de los sistemas externos con los que se comunica. Nada más. No dice de qué está hecho por dentro.
Parece poca cosa, y es el diagrama que más discusiones ahorra, porque fija tres cosas:
- El límite. Qué es “nuestro sistema” y qué no. Un sistema externo es uno que no construimos ni operamos: no podemos cambiarlo, no podemos desplegarlo y, sobre todo, no controlamos cuándo falla.
- Quién lo usa. Las personas, nombradas por su papel. “Usuario” casi nunca sirve: en una biblioteca hay lectores y bibliotecarios, y piden cosas distintas.
- De quién depende. Cada sistema externo es una dependencia: algo que puede tardar, cambiar su interfaz o caerse sin avisarnos.
Lo que no aparece: bases de datos, tablas, procesos, carpetas. Todo eso está dentro de la caja, y en este nivel la caja está cerrada. La base de datos de un sistema no es un sistema externo: la opera el mismo equipo y solo ese sistema la usa.
El diagrama de contenedores
El diagrama de contenedores abre la caja. Muestra las piezas que tienen que estar corriendo, o existir, para que el sistema funcione, y cómo se comunican. Alrededor siguen las mismas personas y los mismos sistemas externos del contexto, ahora conectados a la pieza concreta que los atiende.
En C4, un contenedor es una aplicación o un almacén de datos: algo que se ejecuta o que guarda datos por separado. Un servidor web, una aplicación que corre en el navegador, una app de celular, una base de datos, una carpeta de archivos, un programa que corre cada noche. El sitio del modelo lo resume así: un contenedor es algo que tiene que estar corriendo para que el sistema completo funcione.
Es, en los términos de la primera sesión, una vista de componentes y conectores a grano grueso: lo que existe mientras el sistema corre. Por eso es el diagrama con el que se razona sobre latencia y fallas. Cada flecha entre dos contenedores cruza un límite entre procesos, y casi siempre la red: puede tardar, puede fallar, y lo que viaja por ella tiene un formato que las dos puntas deben respetar.
Error común. Confundir el contenedor de C4 con un contenedor de Docker. Son cosas distintas. El autor de C4 eligió la palabra como un nombre genérico para “algo donde viven componentes”, y hoy encabeza la página con un “Not Docker!”. En el curso, todo corre dentro de un solo contenedor de Docker, y sin embargo el diagrama de contenedores de un sistema tiene varias cajas: una por cada cosa que se ejecuta o guarda datos por separado. Docker es un asunto de despliegue, es decir, de la estructura de asignación.
Diagramas como texto: el formato del curso
En el curso los diagramas se escriben como texto, en Markdown, dentro del
repositorio: un archivo por diagrama en docs/c4/. El formato está descrito
en code/week-01/c4-format.md y es
deliberadamente simple. Un diagrama son dos tablas:
- Elementos, las cajas: nombre, tipo, descripción y tecnología.
- Relaciones, las flechas: de, hacia, qué viaja y protocolo.
Arriba van el título y dos líneas, Nivel: y Sistema:, que dicen qué
diagrama es. Los tipos de elemento de esta semana son cinco:
| Tipo | Qué es | En qué nivel |
|---|---|---|
persona |
Alguien que usa el sistema, por su papel | contexto y contenedores |
sistema |
El sistema que se describe, como una caja | solo contexto |
sistema externo |
Un sistema que no construimos ni operamos | contexto y contenedores |
contenedor |
Algo que se ejecuta por separado | solo contenedores |
almacén de datos |
Algo que guarda datos por separado | solo contenedores |
El formato exige cuatro cosas que un dibujo deja pasar:
- Toda caja dice qué es y de qué es responsable. “Base de datos” no es una descripción: es el tipo. La descripción dice qué guarda.
- Toda caja dice con qué tecnología está hecha (menos las personas). De un sistema externo se escribe lo que se sabe: cómo se llega a él.
- Toda flecha dice qué viaja, con un verbo: “Pide búsquedas, reservas y préstamos”. “Usa” no dice nada.
- Toda flecha dice por qué protocolo. Es lo que permite razonar: una llamada HTTP síncrona y un mensaje en una cola fallan de maneras distintas.
La dirección de la flecha es la de quien inicia: quien llama, quien pide, quien envía. Que la respuesta vuelva por el mismo camino se da por entendido.
Trade-off. Escribir los diagramas como tablas tiene un costo: no se ve el dibujo. Las alternativas son dibujar a mano en una herramienta gráfica o usar un lenguaje de diagramas como Mermaid, que GitHub dibuja solo. La herramienta gráfica da el mejor dibujo, pero el archivo no se puede comparar línea por línea en un pull request y se desactualiza sin que nadie lo note. Un lenguaje de diagramas se versiona bien y da un dibujo, pero la descripción, la tecnología y el protocolo son texto opcional que nadie obliga a llenar. Las tablas se versionan, se revisan en un pull request y dejan que un programa compruebe que no falte nada. Elegimos lo último porque lo que más se olvida en un diagrama es justo lo que más sirve para razonar. Quien quiera el dibujo puede hacerlo a partir de las tablas; la fuente es el texto.
Hay una diferencia con C4 que conviene declarar. C4 recomienda que el diagrama de contexto se concentre en personas y sistemas y deje fuera los detalles técnicos, como los protocolos, para que pueda leerlo cualquiera. En el curso pedimos el protocolo también ahí. La columna de descripción sigue siendo legible para quien no programa, y saber desde el contexto que una dependencia externa es una llamada síncrona es lo primero que hace falta para preguntar “¿y si no responde?”.
Qillqa, dibujado
El diagrama de contexto de Qillqa, completo, está en
example/context.md. Sus dos tablas:
| 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 |
| 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 |
Cinco cajas y cinco flechas, y ya se puede razonar. Qillqa depende de dos sistemas que no son suyos. Con el servidor de correo la relación es de envío: si está caído, los avisos se atrasan, pero el mostrador sigue prestando. Con el sistema de matrícula la relación es una pregunta, por HTTPS, en medio de un préstamo: si no responde, alguien está esperando en el mostrador. El ASR que encontramos antes (“el mostrador sigue prestando aunque matrícula no responda”) se ve en el diagrama como una flecha, y ya se sabe sobre cuál hay que decidir.
El diagrama de contenedores,
example/containers.md, abre la caja
de Qillqa:
| 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 |
| 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 |


Varias cosas que el contexto escondía ahora se ven.
Hay cuatro piezas, y solo dos son servidores. La aplicación web corre en el navegador de cada persona, no en la biblioteca. Los avisos nocturnos no están siempre corriendo: se ejecutan una vez por noche y terminan. Los dos son contenedores de C4, porque se ejecutan por separado. Ninguno es un contenedor de Docker.
El requisito 4 se volvió una caja. “El lector recibe un aviso un día antes” era un requisito funcional, y dijimos que tocaba la estructura. Aquí está: Avisos nocturnos existe solo por él.
Hay una decisión a la vista, con su alternativa. Avisos nocturnos lee la base de datos directamente, sin pasar por la API. Se gana sencillez: el programa no depende de que la API esté arriba, y no hay que agregarle un endpoint. Se paga con acoplamiento: ahora dos programas conocen las tablas, y un cambio en el esquema obliga a revisar los dos. La alternativa, que los avisos le pidan los préstamos a la API, invierte el trade-off. Ninguna es correcta en general: con dos practicantes y un esquema estable, la primera es defendible. Lo importante es que el diagrama muestra la decisión, porque las dos flechas hacia la base de datos están ahí para que alguien las cuestione.
Lo que rodea al sistema no cambió. Las dos personas y los dos sistemas externos son los mismos del contexto. Si al abrir la caja aparece un sistema externo nuevo, uno de los dos diagramas está mal.
Un diagrama con errores
El formato viene con un revisor,
check-c4.ts, que comprueba las reglas. Con
los dos diagramas de Qillqa no encuentra nada:
$ cd code/week-01
$ node check-c4.ts example/context.md example/containers.md
example/context.md: contexto de Qillqa, 5 elementos, 5 relaciones: sin errores
example/containers.md: contenedores de Qillqa, 8 elementos, 8 relaciones: sin errores
Más instructivo es
errors/containers.md: el mismo
sistema, dibujado como suele salir un primer diagrama. Estas son sus tablas:
| 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 |
| 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 |
Y esto dice el revisor:
$ make errors
errors/containers.md:14: [tecnologia] "Lector" es una persona: en Tecnología va "—" (cómo llega al sistema se dice en la relación)
errors/containers.md:15: [descripcion] "Frontend": "Frontend" no alcanza como descripción; digan de qué es responsable
errors/containers.md:16: [tecnologia] "Backend" no dice con qué tecnología está hecho
errors/containers.md:17: [suelto] "Docker" no participa en ninguna relación: o falta una flecha o sobra la caja
errors/containers.md:18: [descripcion] "PostgreSQL": "Base de datos" no alcanza como descripción; digan de qué es responsable
errors/containers.md:19: [tipo] "Tabla loans": un diagrama de contenedores no lleva elementos de tipo "componente" (lleva persona, sistema externo, contenedor, almacén de datos)
errors/containers.md:19: [suelto] "Tabla loans" no participa en ninguna relación: o falta una flecha o sobra la caja
errors/containers.md:20: [suelto] "Servidor de correo" no participa en ninguna relación: o falta una flecha o sobra la caja
errors/containers.md:26: [que-viaja] Lector → Frontend: "Usa" no dice qué viaja; usen un verbo y lo que lleva ("Pide las reservas de un lector")
errors/containers.md:27: [protocolo] Frontend → Backend no dice por qué protocolo
errors/containers.md:28: [que-viaja] Backend → PostgreSQL: "Lee y escribe" no dice qué viaja; usen un verbo y lo que lleva ("Pide las reservas de un lector")
errors/containers.md:29: [extremos] "Sistema de matrícula" no está en la tabla de Elementos
errors/containers.md: contenedores de Qillqa, 7 elementos, 4 relaciones: 12 errores
check-c4 terminó con código 1
Doce errores en once filas. Vale la pena recorrerlos, porque son los que van a cometer.
- Línea 15, “Frontend: Frontend”. La descripción repite el nombre. Quien lee no sabe qué hace esa pieza ni dónde corre.
- Líneas 16 y 27, celdas vacías. En un dibujo, una caja sin tecnología o una flecha sin protocolo pasan inadvertidas. En una tabla, se ven.
- Línea 17, “Docker”. El error que anunciamos: alguien leyó “contenedor” y puso el de Docker. El revisor no sabe qué es Docker; lo delata que la caja no se relaciona con nadie. Es una caja que no participa en el funcionamiento del sistema: sobra.
- Línea 18, “PostgreSQL: Base de datos”. El nombre dice la tecnología y la descripción dice el tipo. Ninguno dice qué datos guarda, que es lo único que hace falta saber.
- Línea 19, “Tabla loans”. Una tabla no es un contenedor: no se ejecuta ni guarda datos por separado, vive dentro de la base de datos. Es detalle de otro nivel.
- Líneas 26 y 28, “Usa” y “Lee y escribe”. Verbos que valdrían para cualquier flecha de cualquier sistema. Si la etiqueta se puede copiar a otra flecha sin que nadie lo note, no dice nada.
- Líneas 20 y 29, cajas y flechas que no se encuentran. El servidor de correo está en la tabla y nadie le envía nada; al sistema de matrícula le llega una flecha y no está en la tabla. En un dibujo hecho a mano, las dos cosas pasan todo el tiempo.
Lo que un revisor puede comprobar y lo que no
El revisor comprueba que el diagrama esté completo. No puede comprobar que sea cierto.
Para verlo, miren otra vez errors/containers.md. Faltan los avisos
nocturnos, y el revisor no lo dijo: no tiene cómo saber que existen. Tampoco
sabe si la flecha entre la API y el sistema de matrícula va en esa dirección,
ni si la aplicación web habla de verdad con una sola API. Un diagrama puede
pasar las dieciséis reglas y describir un sistema que no existe.
La verdad de un diagrama se comprueba contra el sistema:
- Los contenedores, contra lo que corre:
psdice qué procesos hay. - Las flechas, contra quién abre una conexión hacia quién: se lee en el código que hace la llamada y se ve en los logs.
- Los sistemas externos, contra la configuración: toda URL o dirección que el sistema recibe por una variable de entorno apunta a algo que alguien tiene que dibujar.
Idea clave. Un diagrama es una afirmación sobre el sistema, y como toda afirmación puede ser falsa. El revisor garantiza que no le falten partes a la afirmación. Que sea verdadera lo garantizan ustedes, comparándola con el sistema corriendo. Un diagrama completo y falso es peor que no tener diagrama, porque se le cree.
El código de la semana y make test
La carpeta code/week-01/ tiene:
| Archivo | Qué es |
|---|---|
c4-format.md |
El formato de los diagramas como texto y sus dieciséis reglas |
c4.ts, check-c4.ts |
La biblioteca que lee y revisa un diagrama, y el comando que la usa |
example/context.md, example/containers.md |
Los dos diagramas de Qillqa |
errors/containers.md |
El diagrama con errores de este capítulo |
lab/context.md, lab/containers.md |
Los archivos de partida del laboratorio, con las tablas vacías |
module-graph.ts |
Cuenta los imports entre las carpetas de un src/ |
change-cost.sh |
Cuenta en cuántos archivos deja rastro una decisión |
c4.test.ts, module-graph.test.ts |
Las pruebas del revisor y del grafo de imports |
tinkuy-observations.test.ts |
Lo que este capítulo afirma del Tinkuy inicial, como pruebas |
Dentro del contenedor del curso:
$ cd code/week-01
$ make test
mkdir -p build
cp -r ../../tinkuy build/tinkuy
tsc -p .
node --test "*.test.ts"
...
ℹ tests 38
ℹ suites 9
ℹ pass 38
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
make copia Tinkuy en build/tinkuy, y todo lo que se ejecuta lee esa
copia: nada de esta carpeta modifica tinkuy/. make clean borra build/.
Las pruebas de tinkuy-observations.test.ts merecen un comentario. Este
capítulo dice que Tinkuy tiene cinco módulos, que catalog y orders se
importan mutuamente, que cinco carpetas usan db.ts y que los montos en
céntimos aparecen en 12 de 31 archivos. Son afirmaciones sobre un sistema
que puede cambiar. Escritas como pruebas, si Tinkuy cambia, la prueba falla y
avisa que el texto quedó desactualizado. Es una idea que volverá en la
semana 15 con otro nombre: una descripción de la arquitectura que se
comprueba sola no se desactualiza sin que alguien se entere.
Los otros objetivos del Makefile:
| Comando | Qué hace |
|---|---|
make example |
Revisa los dos diagramas de Qillqa |
make errors |
Revisa el diagrama con errores |
make check-c4 DOCS=<carpeta> |
Revisa context.md y containers.md de la carpeta que le indiquen |
make imports |
La cuenta de imports entre carpetas de Tinkuy |
make change-cost |
La tabla de decisiones y archivos |
Laboratorio: el entorno, un recorrido por Tinkuy y sus primeros diagramas
El laboratorio de esta semana no cambia una línea de Tinkuy. Lo corre, lo mira con las tres estructuras y lo describe. Se trabaja en parejas, sobre una copia de Tinkuy en su propio repositorio, como explica la guía del entorno. Los pasos están en la guía de la semana; aquí va qué muestra cada uno.
Paso 1: el entorno. Instalen Docker y abran el contenedor con
./env/run.sh desde la carpeta del curso. La primera vez construye la
imagen y tarda unos minutos. Adentro, comprueben los servicios:
$ svc status
postgres: arriba
redis: arriba
nats: arriba
toxiproxy: detenido
PostgreSQL, Redis y NATS deben estar arriba. Toxiproxy aparece detenido, y está bien: se enciende solo en las semanas que lo usan. Si algo no coincide, la tabla de solución de problemas de la guía del entorno cubre los casos frecuentes.
Paso 2: correr Tinkuy. make db, y después make gateway y make start,
cada uno en su terminal (un segundo ./env/run.sh abre otra shell en el
mismo contenedor). Prueben con curl los endpoints del README: listar
eventos, ver un evento, ver sus asientos, comprar y consultar la orden. Miren
la terminal del servidor mientras compran. Este paso muestra la
funcionalidad: lo que el sistema hace, que es lo único que ve un
comprador.
Paso 3: las pruebas. make test y make typecheck. Abran un archivo de
test/, elijan una prueba y digan qué comportamiento fija. Por ejemplo, hay
una que se llama si uno de los asientos pedidos está vendido, no se vende
ninguno: ¿qué tendría que hacer mal el sistema para que falle? Fíjense
también en qué no fija ninguna prueba: cuánto tarda una compra, o qué
pasa con cincuenta a la vez.
Paso 4: la estructura de módulos. Listen las carpetas de src/ y
escriban, para cada una, una frase con su responsabilidad. Si necesitan
una “y” para describir una carpeta, anótenlo: puede ser una señal. Después
cuenten los imports con el grep de la guía y dibujen el grafo: una caja
por módulo y una flecha por dependencia. Como vimos, el grep no dice quién
importa; repítanlo por carpeta o usen make imports desde code/week-01.
Al dibujar, decidan qué hacer con db.ts, errors.ts, log.ts y
config.ts: ¿son módulos? ¿Cambia el dibujo si los dejan fuera? Guarden el
grafo: en la semana 3 lo van a comparar con el que genera una herramienta.
Paso 5: la estructura de componentes y conectores. Con el sistema
corriendo, listen los procesos con ps aux. El contenedor no trae
herramientas para listar puertos abiertos, pero no hacen falta: cada proceso
anuncia su puerto al arrancar, y el README dice con qué variable se cambia.
Anoten qué proceso escucha en qué puerto y quién llama a quién.
Después viene la parte más importante del laboratorio: seguir una compra de
punta a punta. Abran el handler de POST /orders y sigan el código hasta el
final, anotando en orden cada llamada que sale del proceso (a la base de
datos, a la pasarela) y marcando cuáles ocurren entre el BEGIN y el
COMMIT. No hace falta entender cada línea: se trata de ver la forma de
la operación. Esa lista ordenada es lo que les va a permitir, la próxima
semana, explicar los números que midan. Una pregunta para hacerse mientras la
escriben: el correo de confirmación, ¿sale del proceso? ¿Qué dice
notifications/email.ts sobre eso?
Paso 6: los diagramas. Copien los archivos de partida a su repositorio:
mkdir -p docs/c4
cp /work/code/week-01/lab/context.md /work/code/week-01/lab/containers.md docs/c4/
Llenen las dos tablas de cada uno, con lo que observaron en los pasos 4 y 5 (no con lo que suponen), y revísenlos:
node /work/code/week-01/check-c4.ts docs/c4/context.md docs/c4/containers.md
Con las tablas vacías, el revisor reporta tres errores por archivo; cuando
termine en “sin errores”, les falta la mitad del trabajo: comparar cada caja
con ps y cada flecha con el código, como en la sección anterior. Algunas
decisiones que van a tener que tomar y justificar: ¿la pasarela de pagos de
prueba es un contenedor de Tinkuy o un sistema externo? ¿El servidor de
correo va en el diagrama, si hoy está simulado? ¿Redis y NATS, que están
corriendo, aparecen? Dibujen el sistema como es hoy, no como creen que
debería ser.
Paso 7: candidatos a ASR. Con todo lo que vieron, escriban tres candidatos a requisito significativo para la arquitectura de Tinkuy y, para cada uno, qué parte del diseño actual creen que no lo aguantaría. No hay que medir nada todavía: son hipótesis, y la semana 2 las pone a prueba. Usen las cuatro preguntas (cuánto, qué tan rápido, con qué frecuencia cambia, qué pasa si falla) y eviten los adjetivos sueltos.
Esta semana se publica la primera entrega del proyecto, P0 · Reconocimiento, que es individual. Los diagramas del paso 6 son su primera parte, así que conviene que cada integrante de la pareja termine con los suyos.
Resumen
- La arquitectura de un sistema es el conjunto de estructuras necesarias para razonar sobre él; cada estructura tiene elementos, relaciones y propiedades. Todo sistema tiene arquitectura, aunque nadie la haya escrito; describirla es elegir qué omitir; y solo es de arquitectura la estructura que ayuda a razonar sobre un atributo de calidad.
- La definición de Fowler y Johnson la complementa: arquitectura son las decisiones que uno quisiera acertar temprano, porque cuesta cambiarlas. La prueba: ¿cuántos archivos, equipos y despliegues toca deshacerla?
- Hay tres tipos de estructuras. Las de módulos (el código y sus dependencias) responden qué toca un cambio. Las de componentes y conectores (lo que existe mientras el sistema corre) responden qué pasa con la latencia y las fallas. Las de asignación (máquinas, repositorios, equipos) responden quién lo construye y dónde corre. Tinkuy tiene cinco módulos y un solo proceso.
- Arquitectura y diseño son la misma actividad a distinta escala; cambia el costo de equivocarse. La funcionalidad no determina la arquitectura: lo mismo se puede construir de muchas formas, y la diferencia se mide en atributos de calidad.
- La arquitectura importa porque 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, reparte el trabajo entre equipos y se puede evaluar antes de construir.
- Un ASR es un requisito que, si cambiara, cambiaría la arquitectura. Casi nunca dice qué hace el sistema: dice cuánto, qué tan rápido, con qué frecuencia cambia o qué pasa si falla. Si no se puede decir cuándo se incumple, todavía no es un requisito.
- Los ASR salen de los requisitos escritos (pocas veces), de los stakeholders, de los objetivos del negocio y del conocimiento del dominio. Cada stakeholder pide atributos distintos, y a veces opuestos.
- Una restricción es una decisión que ya viene tomada: no se negocia, se diseña dentro de ella. También influyen el equipo, el plazo y la experiencia previa, y la arquitectura influye de vuelta sobre la organización.
- El diagrama de contexto de C4 muestra el sistema como una caja, con sus personas y sus sistemas externos. El de contenedores la abre: lo que tiene que estar corriendo o existir para que funcione. Un contenedor de C4 no es un contenedor de Docker.
- En el curso los diagramas son texto: una tabla de elementos (nombre, tipo,
descripción, tecnología) y una de relaciones (de, hacia, qué viaja,
protocolo).
check-c4.tscomprueba que estén completos; que sean ciertos se comprueba contra el sistema corriendo.
Ejercicios
- Para cada decisión de Tinkuy, digan si es de arquitectura y qué costaría
cambiarla, en archivos, equipos y despliegues: (a) las entradas llevan un
código que empieza con
TKY-; (b) los errores de la API tienen la forma{ "error": { "code", "message" } }; (c) cada pedido abre su propia conexión a PostgreSQL; (d) las pruebas usannode:test; (e) la pasarela de pagos es un servicio de un tercero. ¿En cuál cambia la respuesta si Tinkuy ya tiene una app de celular publicada que usa la API? - Agreguen una línea a
change-cost.shpara la decisión “los errores que la API sabe explicar son instancias deAppError” y córranlo. Comparen el número con los otros cuatro. ¿Es una decisión de arquitectura? Den un argumento a favor y uno en contra. - Para cada pregunta, digan qué tipo de estructura hay que mirar y dónde la
mirarían en Tinkuy: (a) ¿se puede probar
orders/sin tener una pasarela corriendo?; (b) si se reinicia PostgreSQL, ¿cuánto tarda Tinkuy en volver a vender?; (c) ¿qué partes del código puede tocar un practicante que solo conoce los reportes?; (d) ¿cuánta memoria necesita la máquina donde corre todo? - Un compañero dice: “Tinkuy tiene cinco componentes: catálogo, órdenes, pagos, notificaciones y reportes”. Otro responde: “Tiene uno solo”. Expliquen en qué sentido tiene razón cada uno, y escriban una frase que los dos aceptarían.
- Den un ejemplo, que no esté en el capítulo, de un sistema con un módulo que corre en varios procesos, y otro de un proceso que contiene módulos mantenidos por varios equipos. Para cada uno, digan qué pregunta responderían mal si confundieran módulos con componentes.
- Clasifiquen como ASR, como requisito que no afecta la arquitectura o como “todavía no es un requisito”, y justifiquen con la prueba del cambio: (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; (e) el sistema debe ser robusto; (f) el reporte de ventas de un evento se puede pedir mientras el evento está en venta.
- Reescriban “Qillqa debe ser rápido y seguro” como dos requisitos de los que se pueda decir cuándo se incumplen. Para cada uno, digan a qué stakeholder de la tabla le preguntarían el número y qué le preguntarían exactamente.
- En el diagrama de contenedores de Qillqa, Avisos nocturnos lee la base
de datos directamente. Escriban la variante en la que le pide los
préstamos a la API: copien
example/containers.md, cambien las filas que haga falta y pasen el revisor. Después comparen las dos variantes en una tabla: qué se gana y qué se paga en cada una si (a) cambia el esquema de la tabla de préstamos, (b) la API está caída a las 3 a. m. - La biblioteca decide que el mostrador debe seguir prestando aunque el sistema de matrícula no responda. Propongan dos diseños que lo cumplan y modifiquen el diagrama de contenedores de Qillqa para cada uno (un archivo por diseño, los dos sin errores en el revisor). ¿Qué puede salir mal en cada diseño que antes no podía? ¿A qué stakeholder le tocaría aceptar ese riesgo?
- Escriban un diagrama de contenedores que pase las reglas de
check-c4.tsy que sea falso respecto deexample/containers.mdde tres maneras distintas (una caja que no existe, una flecha en la dirección contraria, una dependencia que falta). Para cada falsedad, digan qué observación sobre el sistema corriendo la delataría. - El revisor rechaza la etiqueta “Usa” pero acepta “Usa el sistema
siempre”. Agreguen a
c4.test.tsuna prueba que lo demuestre. Después discutan: ¿conviene endurecer la regla enc4.ts, o hay un punto a partir del cual una regla automática estorba más de lo que ayuda? Si la endurecen, corranmake testy verifiquen que los ejemplos sigan pasando. - Elijan un sistema que usen todos los días (el de matrícula de su universidad, una app de delivery, una billetera digital). Sin ver su código, escriban su diagrama de contexto con el formato del curso, cinco stakeholders con lo que le importa a cada uno, y tres ASR con su número estimado. Marquen cuáles de sus afirmaciones son observaciones y cuáles son suposiciones, y digan cómo comprobarían una de las suposiciones.