Ingeniería de Sistemas · Semestre IV · 2026-2 · Clase 5 de 16

El trabajo que
nadie ve

Un arquitecto casi no escribe código. Decide, dibuja, explica y responde por lo que decidió. Hoy vemos ese oficio. — Elkin Rodríguez E.

Ruta de hoy · 3 horas

Cómo va a fluir la clase

01
Quiz + conceptos elementales Lo que sostiene cualquier arquitectura: IP, DNS, API, latencia, escalar.
02
El oficio del arquitecto Qué hace de verdad, y cómo se llega ahí.
03
Por qué se documenta Y sobre todo: qué NO se documenta.
04
El modelo C4 en draw.io Cuatro niveles de zoom, con tres casos completos.
05
Dinámica: la prueba del recién llegado Su documentación se califica por si otro la entiende.
Reconexión

Dónde quedamos

Clases 2 y 3

Los drivers y el estilo: qué exige el negocio y qué forma toma el sistema.

→

Clase 4

Los patrones: con qué piezas se construye por dentro.

→

Hoy

Comunicarlo. Una decisión que nadie entiende, no existe.

La frase que sostiene toda la sesión

Si nadie más lo
entiende, no sirve.

Han aprendido a decidir. Pero una decisión que vive solo en la cabeza de quien la tomó se pierde en seis meses, y el que llega después la deshace sin saberlo.

Arrancamos con esto · proyectar el quiz

Antes de explicar nada, veamos qué sabemos

Un quiz corto y en vivo, todos a la vez, sobre los conceptos que sostienen cualquier arquitectura: IP, DNS, API, latencia, caché, escalar, bases de datos.

No cuenta para notaNo es una evaluación: es un termómetro. Sirve para dos cosas: que ustedes vean qué tan sólido tienen el piso, y que yo sepa en cuáles conceptos hay que detenerse más.
Por qué empezamos por aquí

Esto es lo que separa a un junior de un senior

Un junior sabe hacer que la aplicación funcione. Un senior sabe qué pasa por debajo cuando funciona — y por qué deja de funcionar cuando llegan diez mil usuarios.

Y hay una razón prácticaCada concepto que veremos ahora es una caja o una flecha en el diagrama que van a dibujar hoy. Sin este vocabulario, dibujar arquitectura sería poner rectángulos sin saber qué va adentro.
Cómo se comunican

Arquitectura Cliente-Servidor

Casi todo lo que usan a diario funciona así: alguien pide (cliente) y alguien responde (servidor). El cliente no guarda los datos; solo sabe pedirlos y mostrarlos.

Usted
→
Su dispositivo
→
La aplicación
→
El servidor
Lo que separa a un juniorUn junior dice «la app trae los datos». Un senior pregunta de dónde, cuántas veces y qué pasa si esa respuesta se demora. Todo lo que sigue hoy son respuestas a esas tres preguntas.
Cómo se encuentran

Dirección IP

Es el número que identifica a un equipo en la red. Como un número telefónico: si dos tuvieran el mismo, nadie sabría a quién llamar.

VersiónTamañoCómo se veCuántas caben
IPv432 bits142.250.190.46≈ 4.300 millones
IPv6128 bits2001:0db8::7334340 sextillones
La cuenta, para que la expliquen bienIPv4 son 4 octetos de 8 bits. Cada octeto va de 0 a 255 (256 valores). Entonces 256⁴ = 4.294.967.296 direcciones. Suena a muchísimo… hasta que hay más celulares que personas.
Dirección IP · la pregunta que siempre hacen

¿Y por qué no existe IPv5?

El campo versión existe desde el inicio del protocolo, y varios números quedaron gastados en experimentos.

VersiónQué pasó con ella
IPv4La que funcionó. Sostiene internet desde 1983.
IPv0 – IPv3Experimentales de los años 70. Nunca se desplegaron.
IPv5Asignada a un protocolo de video y voz que no prosperó.
IPv6La sucesora real. Se saltó el 5 porque ya estaba ocupado.
El dato que enganchaLas IPv4 se agotaron en 2011. Por eso su casa comparte una sola IP pública entre todos sus dispositivos.
Cómo se traduce

DNS · la agenda de contactos de internet

Nadie escribe 142.250.190.46 para entrar a Google. Escribe el nombre, y el DNS lo traduce a la IP. Es la agenda de contactos de internet.

usted escribe google.com
→
DNS traduce
→
142.250.190.46
→
conecta
Pruébelo en clase, en vivoAbran la consola y escriban ping youtube.com. Van a ver la IP real que hay detrás del nombre — y el tiempo de respuesta en milisegundos, que es justo el siguiente concepto.
Anatomía de una dirección

Qué partes tiene una URL

Cada pedazo de lo que escriben en el navegador cumple una función distinta.

ParteEjemploQué hace
Protocolohttps://Cómo se va a hablar, y si va cifrado
Subdominiowww.Una sección dentro del dominio
Dominioutadeo.edu.coEl nombre que el DNS traduce a IP
Ruta/programas/Qué recurso específico se pide
Fíjense en el .edu.coEs un dominio restringido: solo lo tiene una institución educativa reconocida en Colombia. Por eso su correo sirve como prueba de identidad.
Cuando hay alguien en el medio

Proxy y Reverse Proxy

La información no siempre viaja directo. Un intermediario puede pararse en el camino — y según de qué lado esté, cambia por completo para qué sirve.

Proxy · protege al cliente
usted
PROXY
servidor

El servidor ve la IP del proxy, no la suya.

Reverse proxy · protege al servidor
internet
R-PROXY
sus servidores

El de afuera ve una sola puerta, no sus diez servidores.

La confusión clásica de entrevistaSon el mismo aparato mirando en direcciones opuestas. Proxy = a favor del que pide. Reverse proxy = a favor del que responde. Un reverse proxy además reparte carga y termina el cifrado.
El costo de la distancia

Latencia

El tiempo que tarda un mensaje en ir y volver. No se puede eliminar: la luz tiene velocidad límite.

De dónde a dóndeIda y vuelta aproximada
Bogotá → servidor en Bogotá1 a 5 ms
Bogotá → Virginia (EE. UU.)80 a 120 ms
Bogotá → Fráncfort150 a 200 ms
Bogotá → Singapur250 a 350 ms
Por qué esto decide arquitecturas10 llamadas seguidas a Singapur son 3 segundos solo de viaje. Por eso existen los centros de datos regionales y el CDN.
El idioma de la web

HTTP y HTTPS

HTTP es el protocolo con el que el navegador pide páginas y datos. Su problema: viaja en texto plano, así que cualquiera en el camino puede leerlo.

HTTP · texto plano
usuario: elkin
clave: 1234
legible para cualquiera

En un wifi público, esto es regalar la contraseña.

HTTPS · cifrado con TLS
a8f3d9e2b7c1…
↓
solo el destino lo descifra

El candado del navegador significa exactamente esto.

Precisión que suma en una entrevistaAl certificado se le sigue diciendo SSL por costumbre, pero SSL está obsoleto desde 2015. Lo que se usa hoy se llama TLS. Decirlo bien lo distingue de inmediato.
El contrato entre sistemas

API

Cliente y servidor no se pasan datos de cualquier forma: lo hacen por una API — Application Programming Interface. Es el menú de lo que se puede pedir y en qué formato.

cliente pide
→
API recibe
→
busca los datos
→
responde JSON
La analogía que funcionaLa API es el mesero de un restaurante. Usted no entra a la cocina: le dice al mesero qué quiere, del menú que existe, y él le trae el plato. El menú es el contrato. Si cambia sin avisar, todo el que pedía se rompe.
El estilo de API más usado

REST

Organiza la API alrededor de recursos y usa los verbos que HTTP ya traía. Es el estándar de la industria.

VerboQué haceEjemplo
GETConsultarGET /estudiantes/1032
POSTCrearPOST /matriculas
PUT / PATCHActualizarPATCH /estudiantes/1032
DELETEEliminarDELETE /matriculas/77
«Stateless», la palabra que hay que entenderEl servidor no recuerda nada entre peticiones. Por eso se pueden tener diez servidores idénticos: da igual cuál responda.
La alternativa

GraphQL

Creado por Meta. En REST, el servidor decide qué le manda. En GraphQL, el cliente pide exactamente los campos que necesita, ni uno más.

REST · el servidor decide
pide el estudiante
y recibe 40 campos
aunque necesite 3

Se llama sobre-carga de datos (over-fetching).

GraphQL · el cliente pide
{ nombre, semestre }
↓
llegan solo esos dos

Ideal cuando el que pide es un celular con datos limitados.

Y qué se pagaEl servidor se vuelve más complejo, cachear se dificulta, y un cliente puede pedir una consulta tan grande que tumbe la base. Como todo en este curso: no es mejor, es otro trade-off.
Dónde viven los datos

Bases de datos

La memoria es temporal: si se apaga, se pierde. La base de datos es donde los datos sobreviven al apagón.

FamiliaCómo guardaCuándo brilla
SQL (relacional)Tablas con esquema fijo definido de antemanoCuando los datos tienen forma estable y hay dinero de por medio
NoSQLDocumentos, clave-valor o grafos, sin esquema rígidoCuando la forma cambia seguido o hay volumen enorme
El error de junior más comúnCreer que NoSQL «es más moderno» y por eso mejor. La pregunta no es cuál es mejor, sino qué garantiza cada una.
La garantía que dan las relacionales

ACID · lo que hace confiable a SQL

Cuatro propiedades que garantizan que una operación no deje el sistema a medias.

LetraQué garantizaEn una transferencia
AtomicidadTodo o nadaO se debita y se acredita, o no pasa nada
ConsistenciaLas reglas se respetan siempreNunca queda un saldo negativo prohibido
IslamientoLas operaciones no se pisanDos retiros simultáneos no se estorban
DurabilidadLo confirmado no se pierdeSi se va la luz, la transferencia quedó
Dónde aterriza esto en el cursoCuando alguien diga «lo separo en microservicios», pregunte: ¿y la atomicidad?
Cuando llega más gente

Escalar: vertical u horizontal

Las peticiones crecen y el servidor no da abasto. Hay exactamente dos caminos, y la diferencia entre ellos define arquitecturas enteras.

Vertical · un servidor más grande
más RAM
más CPU
hay un techo físico

Rápido de hacer. Un solo punto de falla.

Horizontal · más servidores iguales
srv 1
srv 2
srv 3

Sin techo. Y si uno cae, los otros siguen.

La condición que casi nadie mencionaEscalar horizontal solo funciona si el servidor es stateless — ¿se acuerdan de REST? Si el servidor guarda la sesión en su memoria, el usuario se desloguea cada vez que le toca otro servidor.
Quién reparte el trabajo

Balanceador de carga

Si hay cinco servidores iguales, alguien tiene que decidir a cuál mandar cada petición. Ese portero es el balanceador.

EstrategiaCómo decideCuándo conviene
Round RobinPor turnos: uno a cada quien, en ordenServidores iguales y peticiones parecidas
Least ConnectionsAl que tenga menos conexiones activasPeticiones de duración muy distinta
IP HashEl mismo usuario siempre al mismo servidorCuando hay que conservar la sesión
Corrección importanteLeast Connections no es PEPS ni una cola FIFO. No atiende en orden de llegada: mira cuál servidor está más desocupado en este instante y le manda ahí. Es un criterio de carga, no de turno.
Optimizar sin comprar hardware

Índices

Un índice es el índice de un libro: en vez de leer las 800 páginas buscando un tema, va a la lista del final y salta directo a la página.

Sin índice
la base revisa
fila por fila
2 millones de filas

Una consulta puede tardar segundos.

Con índice
busca en el índice
↓
salta a la fila exacta

La misma consulta, milisegundos.

Y aquí está la facturaCada índice hace más lenta la escritura: al insertar una fila hay que actualizar también todos los índices. Y ocupa espacio en disco. Por eso no se indexa todo: se indexa lo que se consulta mucho.
Copiar la base

Replicación

Se mantiene una copia sincronizada de la base. Normalmente una escribe (primaria) y varias solo leen (réplicas).

PRIMARIA · aquí se escribe
↓ se copia a ↓
réplica 1
réplica 2
réplica 3
Para qué sirve, en dos frasesRendimiento: los reportes pesados se leen de una réplica y no estorban a la venta. Disponibilidad: si la primaria muere, una réplica toma su lugar. El costo: la copia va con segundos de retraso.
Partir la base

Sharding · fragmentación

Replicar copia toda la base. Sharding la parte: cada fragmento guarda un pedazo distinto de los datos, y ninguno tiene el total.

Replicación · copias completas
todo
todo
todo

Sirve para leer más. No para guardar más.

Sharding · pedazos distintos
A–H
I–P
Q–Z

Sirve para guardar más de lo que cabe en una máquina.

El precio es altoUna consulta que cruce varios fragmentos se vuelve lenta y difícil. Y elegir mal la clave de partición deja un fragmento saturado y los demás vacíos. Es de las decisiones más caras de revertir.
Cuando el problema son las columnas

Particionamiento vertical y bases columnares

Sharding parte por filas. Pero a veces el problema es que la tabla tiene 200 columnas y los reportes solo leen tres.

EnfoqueQué haceEjemplo típico
Partición verticalSepara las columnas en tablas distintas según cómo se usanDatos básicos aparte de datos de perfil
Base columnarGuarda por columna en vez de por fila, así leer 3 de 200 es baratoAmazon Redshift, BigQuery
Su terreno, profeAquí es donde se conecta con analítica: una base transaccional guarda por fila porque atiende operaciones completas; una analítica guarda por columna porque suma millones de valores de un mismo campo.
No preguntar dos veces lo mismo

Memoria caché

Si mil personas piden la misma cartelera en un minuto, no tiene sentido ir mil veces a la base. Se guarda la respuesta a la mano y se sirve desde ahí.

piden el dato
→
¿está en caché?
→
sí → responde ya
→
no → va a la base
La única pregunta que importa¿Cuánto puede estar desactualizado este dato sin que a alguien le importe? Una cartelera: minutos. Un saldo bancario: nada. Esa respuesta —y no la tecnología— decide si se cachea.
La ley del sistema distribuido

Teorema CAP

Cuando los datos viven en varias máquinas, la red se va a partir. Ese día hay que elegir.

SiglaQué significaSi la red se parte…
ConsistenciaTodos ven el mismo dato al mismo tiempo…prefiero no responder antes que dar un dato viejo
Availability (disponibilidad)El sistema siempre responde algo…prefiero responder aunque el dato esté un poco viejo
Partition toleranceAguanta que la red se corteNo es opcional: la red se va a partir
Cómo se explica bienNo es «elija 2 de 3»: la P no se negocia. Es ¿C o A cuando la red se parta? Cajero: C. Instagram: A.
Archivos, no filas

Blob storage

Una base de datos guarda datos estructurados. Pero un video de 2 GB, un PDF o una foto no van en una celda de una tabla.

suben el archivo
→
se guarda como objeto
→
queda con su URL
→
se replica solo
Por qué importa en arquitecturaMeter archivos pesados en la base la vuelve lenta y cara. Se guardan en un almacén de objetos (S3, Azure Blob) y en la base queda solo la URL. Es de los cambios más simples con más impacto.
Acercar el contenido

CDN · Content Delivery Network

Si el archivo está en Virginia y el usuario en Bogotá, cada descarga paga ese viaje. Un CDN guarda copias del contenido cerca del usuario.

Sin CDN
Bogotá → Virginia
cada vez
~100 ms por archivo

Y si son 50 archivos, la página se arrastra.

Con CDN
Bogotá
Lima
Miami

El archivo se sirve desde el nodo más cercano.

Es latencia, otra vezTodo lo que hemos visto de latencia se resuelve aquí de la forma más bruta posible: no se puede ir más rápido, entonces se acorta la distancia. Cloudflare y Akamai viven de esto.
Cuando HTTP no alcanza

WebSocket

HTTP funciona por turnos: el cliente pregunta, el servidor responde, y se acabó. Para un chat o un precio en vivo eso no sirve — el cliente tendría que preguntar cada segundo.

HTTP · por turnos
¿hay algo nuevo?
¿hay algo nuevo?
¿hay algo nuevo?

Se llama polling. Gasta red y llega tarde.

WebSocket · canal abierto
cliente ⟷ servidor
⟷
ambos hablan cuando quieran

El servidor empuja el dato apenas ocurre.

Corrección importanteWebSocket es bidireccional, no unidireccional. Esa es exactamente su razón de existir: una conexión que queda abierta y por la que los dos lados pueden hablar cuando quieran.
Entre servidores

Webhook

No todo es cliente-servidor. A veces un servidor tiene que avisarle a otro que pasó algo — y no puede quedarse preguntando cada minuto.

su tienda cobra
→
la pasarela procesa
→
pasarela llama a su URL
→
usted despacha
La diferencia con una API normalEn una API usted llama. En un webhook a usted lo llaman: le da al proveedor una URL suya y él la invoca cuando ocurre el evento. Por eso se le dice «API al revés» o reverse API.
Cierre del bloque de conceptos

Todo esto era una sola pregunta

Alguien pide un dato y alguien responde. Los veinticinco conceptos de hoy son respuestas a tres problemas de esa frase:

Encontrarse

IP · DNS · URL · proxy

Hablarse

HTTP/S · API · REST · GraphQL · WebSocket · webhook

Aguantar

escalar · balanceador · índices · réplica · shard · caché · CDN · CAP

Y ahora el puente al resto de la claseCada uno de estos es una caja o una flecha en un diagrama de arquitectura. Por eso los vimos primero: sin este vocabulario, el C4 que sigue sería dibujar rectángulos sin saber qué va adentro.
Capa 1 · objetivo del curso

Un martes cualquiera de un arquitecto

Esto es una agenda real. Cuenten cuántas horas hay de escribir código.

8a
Reunión con producto Quieren una función nueva para el trimestre. Hay que estimar si el sistema aguanta.
10a
Revisión de un diseño Un equipo propone separar un módulo. Toca preguntar qué se paga.
2p
Escribir un documento Dejar por escrito por qué se eligió una base de datos y no otra.
4p
Explicarle al gerente Por qué la migración cuesta tres meses y no tres semanas.
El mito que hay que romper

No es "el que más sabe de código"

Lo que muchos creen

El arquitecto es el programador más veterano, el que resuelve lo que nadie puede.

Lo que es

La persona que mejor decide con información incompleta — y que sabe explicar esa decisión a gente que no programa.

Por qué importa saberlo hoySi creen que el camino es solo programar mejor, van a llegar a senior y ahí se van a estancar. El salto siguiente lo dan otras habilidades.
Capa 1 · el rol en la organización

Los cuatro sombreros

1 · Decide

Elige entre opciones que todas tienen algo malo. Nunca hay una obviamente mejor.

2 · Comunica

Traduce la decisión a tres idiomas: negocio, desarrollo y operación.

3 · Negocia

Dice que no, o dice "sí, pero cuesta esto". Casi siempre a alguien con más rango.

Y el cuarto, el que más pesaResponde. Cuando la decisión sale mal —y a veces sale mal— el arquitecto no dice "el equipo decidió". Dice "yo decidí, y esto aprendí".
La pregunta que se hacen todos

¿Cómo se llega a arquitecto?

1
Nadie llega recién graduado Se necesitan años viendo sistemas envejecer. No se puede acelerar leyendo.
2
El camino empieza opinando En revisiones de código, en reuniones de diseño. Quien argumenta bien se hace notar.
3
Se nota quién piensa en el después El que pregunta "¿y cuando esto crezca?" ya está haciendo el trabajo.
4
Y quien sabe escribir La mitad del oficio es documentos y correos que otros entiendan.
Tres cargos que se confunden

Quién hace qué

RolSu pregunta diariaAlcance
Desarrollador senior¿Cómo hago que esto funcione bien?Un módulo
Líder técnico¿Cómo hago que el equipo entregue?Un equipo
Arquitecto¿Qué vamos a lamentar en dos años?El sistema completo
La diferencia realNo es de jerarquía sino de horizonte de tiempo. El senior piensa en el sprint; el arquitecto, en la próxima migración.
El día a día, en concreto

Las cuatro preguntas que le hacen a un arquitecto

1
«¿Esto aguanta?» Lo pregunta producto antes de prometerle algo a un cliente. Se responde con latencia, escalamiento y caché.
2
«¿Por qué está hecho así?» Lo pregunta quien llega nuevo. Se responde con un ADR y un diagrama, no con una charla.
3
«¿Dónde toco para cambiar esto?» Lo pregunta el equipo. Se responde con el nivel 2 del C4.
4
«¿Qué se cae si falla eso?» Lo pregunta operación a las 2 de la mañana. Se responde con el mismo diagrama.
El puente al resto de la clase

Tres de las cuatro se responden con un dibujo

Fíjense en algo: de esas cuatro preguntas, tres se contestan mostrando un diagrama. Ninguna se contesta abriendo el código.

Por eso lo que sigueEl resto de la clase es aprender a hacer ese dibujo. Se llama modelo C4, y con dos de sus cuatro niveles se responden esas tres preguntas.
Capa 1 · documentación

El costo de no documentar

No es que quede feo. Es que cuesta plata, y de tres formas concretas:

El caso que lo explica todo

La cerca en mitad del campo

Llega alguien nuevo, ve una cerca atravesada en un potrero sin ninguna razón aparente y dice: "esto estorba, quitémosla".

La respuesta correcta es: "no la quite hasta que sepa por qué la pusieron". Quizá había un toro del otro lado.
En software pasa igual, todos los díasUn desarrollador ve un código raro, lo "arregla", y tumba producción. Estaba raro por una razón — pero nadie la escribió.
La regla que evita documentar de más

Qué se documenta y qué no

Sí se documenta

Lo que es caro de descubrir preguntando: por qué se decidió así, qué se descartó, qué se rompe si se toca, cómo se conectan las piezas grandes.

No se documenta

Lo que el código ya dice: qué hace cada función, los nombres de las variables, listas que quedan viejas en una semana.

La prueba de una línea¿Esto lo puede averiguar alguien leyendo el código en cinco minutos? Entonces no lo documente.
El error más común

Documentación muerta

Un documento de 80 páginas que nadie abre, escrito una vez y nunca actualizado. Es peor que no tener nada: dice mentiras con cara de verdad.

Muerta

Larga · en un archivo aparte · escrita para cumplir · desactualizada a los tres meses.

Viva

Corta · al lado del código · escrita para que alguien decida · se actualiza porque duele no hacerlo.

Lo que ya saben hacer

El ADR era documentación

En la Clase 3 escribieron un ADR sin que le pusiéramos ese nombre. Ese documento de una página es el corazón de la documentación de arquitectura: no describe el sistema, describe por qué es así.

Por eso funcionaEs corto, vive junto al código y responde justo la pregunta cara: por qué. Es la cerca con su razón escrita al lado.
La herramienta del día

El modelo C4

Una forma de dibujar arquitectura que entiende todo el mundo. Creada por Simon Brown. No necesita herramienta especial: se hace en una servilleta.

La idea, en una analogía

Como Google Maps

Nadie navega la ciudad con un solo nivel de zoom. Se empieza viendo el país y se acerca hasta la cuadra. Un sistema se dibuja igual: cuatro niveles, y cada uno para una conversación distinta.

El error que evitaMeter todo en un solo diagrama: cajas, flechas, bases de datos y nombres de clases mezclados. Ese dibujo no lo entiende nadie, ni siquiera quien lo hizo.
Los cuatro niveles

De la ciudad al ladrillo

1 · Contexto

El sistema y quién lo usa. Una caja en el centro, alrededor las personas y los sistemas externos. Lo entiende un gerente.

2 · Contenedores

Las piezas que se despliegan. La app móvil, el servidor, la base de datos. Lo entiende operación.

3 · Componentes

Qué hay dentro de una de esas piezas. Solo para el equipo que la mantiene.

4 · Código

Clases y métodos. Casi nadie lo dibuja, y está bien: envejece en días.

La parte que importa

Con los dos primeros basta el 90%

Los niveles 1 y 2 resuelven casi todas las conversaciones reales de trabajo. Son los únicos que entiende alguien que no programa — y son los que van a dibujar hoy.

Guárdenlo para su primer empleoSi en su primera semana les piden entender un sistema, pidan el diagrama de contexto. Si no existe, dibújenlo ustedes y pregunten si está bien. Van a quedar muy bien parados.
Nivel 1 · Contexto

El sistema y su mundo

Qué va en el dibujo
EL SISTEMA
↑ ↓
Personas
Sistemas externos
Nada más

Una sola caja para todo su sistema. Sin abrirla.

Qué NO va
bases de datos · servidores
lenguajes · frameworks
nombres de clases

Si aparece una tecnología, ya no es nivel 1.

Nivel 1 · ejemplo

Plataforma de matrícula de la Tadeo

Las personas
Estudiante
Docente
Registro

Cada una usa el sistema para algo distinto.

Los sistemas externos
Pasarela de pago
Correo
Contabilidad

No son nuestros, pero sin ellos no funciona.

En el centro, una sola caja: Plataforma de Matrícula. Seis flechas. Eso es todo el nivel 1.
Nivel 2 · Contenedores

Abrimos la caja

Un "contenedor" en C4 no es Docker: es algo que se ejecuta o guarda datos por separado. Una app móvil, un sitio web, un servidor, una base de datos.

Dentro de la plataforma
Web del estudiante
Servidor
Base de datos

Cada caja se despliega y puede caerse por separado.

La pregunta que lo define
¿esto se puede
apagar solo?

Si sí, es un contenedor. Si no, es un componente.

Las reglas del dibujo

Cuatro reglas y ya funciona

  1. Cada caja con nombre y una línea de qué hace. Sin la línea, la caja no dice nada.
  2. Cada flecha con verbo y dirección. "Consulta notas", no una raya suelta.
  3. Un solo nivel por dibujo. No mezclar personas con bases de datos.
  4. Que se entienda sin usted al lado. Esa es la prueba real.
La regla de oroUn diagrama que necesita que usted lo explique no es documentación: es un apoyo para su charla. Y usted no va a estar ahí cuando alguien lo lea.
Los cuatro errores que voy a ver hoy

Lo que hace inútil un diagrama

El errorPor qué mata el diagrama
Flechas sin verboSé que se hablan, pero no sé para qué.
Mezclar nivelesUna persona al lado de una tabla de base de datos. No se entiende la escala.
Cajas con nombre técnico solosvc-auth-v2 no le dice nada a nadie nuevo.
Veinte cajasSi no cabe en una hoja, no es nivel 1: está mezclando niveles.
Ejercicio en conjunto · 15 min

Lo dibujamos juntos

Yo comparto pantalla con draw.io abierto y ustedes me dictan. Vamos a hacer el nivel 1 y el nivel 2 de un sistema que usan todos los días: la app de un banco.

  1. ¿Quiénes lo usan? Nómbrenlos. Ojo: no todos son clientes.
  2. ¿Con qué sistemas de afuera habla? Piensen en el dinero, no en el código.
  3. Ahora abrimos la caja: ¿qué piezas se pueden caer por separado?
Lo vemos en la herramienta · en vivo

Tres casos completos

No voy a mostrarles teoría de C4: vamos a abrir tres archivos reales en draw.io y recorrerlos página por página, del problema al diagrama.

Caso 1 · Boletería

Venta de boletas para conciertos. El problema: 40.000 personas en 8 minutos y cero doble venta.

Caso 2 · BiciCiudad

Bicicletas públicas. El problema: estaciones sin señal que igual tienen que prestar.

Caso 3 · Mercado campesino

Del campo a la mesa. El problema: un pago que se reparte entre cinco vendedores.

Cómo está armado cada archivo

Cinco pestañas, una historia

0 · Ficha y drivers

La ficha del sistema en prosa y los drivers como escenarios medibles. Aquí no hay dibujo: hay decisiones pendientes.

1 · Contexto

El sistema como una caja, quién lo usa y con qué habla afuera. Sin tecnología.

2 · Contenedores

Se abre la caja. Aquí llegamos hoy: es el nivel que resuelve el trabajo real.

3 y 4

Componentes de una pieza, y la guía de notación. Quedan para que los recorran ustedes.

Lo que quiero que noten al recorrerlos

El diagrama responde a los drivers

En los tres casos hay una pieza que existe solo por culpa de un driver. No está ahí porque sí:

CasoEl driver que mandaLa pieza que aparece por eso
BoleteríaCero doble venta de una sillaServicio de Reserva de Sillas
BiciCiudadEstaciones sin señal siguen prestandoControlador de Estación con bitácora local
Mercado campesinoUn pago repartido que debe cuadrarServicio de Liquidaciones
La conexión con lo que vimos hace un rato

Los conceptos aparecen en los diagramas

Todo lo que vimos al inicio está dibujado en esos archivos. Búsquenlo mientras los recorremos:

En Boletería

Una cola (sala de espera) para el pico · un servicio con Redis como caché de bloqueo

En BiciCiudad

WebSocket para el estado en vivo · operación sin conexión con base local

En los tres

API entre las piezas · base de datos al fondo · sistemas externos en gris

Ese es el punto de la claseUn diagrama de arquitectura es vocabulario técnico puesto en cajas. Por eso hoy empezamos por el vocabulario.
Capa 1 · vistas

La misma arquitectura, tres lectores

Quién leeQué le preocupaQué nivel necesita
GerenteCuánto cuesta y qué riesgo tieneNivel 1 · nada más
Desarrollador nuevoDónde toco para hacer un cambioNiveles 2 y 3
OperaciónQué se cae y a quién llamoNivel 2 · con despliegue
El error de principianteMandarle el mismo documento a los tres. Al gerente le sobra el 80% y al desarrollador le falta lo que necesita.
Cómo se llama esto en los libros

Vistas

Una vista es el sistema mirado desde el interés de alguien. La misma arquitectura, distinto recorte. No es que haya varios sistemas: hay varias formas de mirarlo.

De dónde vieneEs la idea del modelo 4+1 de Kruchten (1995) y del catálogo de Bass, Clements y Kazman. El C4 es la versión moderna y más simple de la misma idea.
Capa 2 · lo que cambió este año

La documentación tiene un lector nuevo

Hasta hace poco la documentación la leían personas. Hoy también la lee la IA — y de eso depende la calidad del código que les entrega.

Capa 2 · la conclusión incómoda

Lo que la IA no puede documentar

Sí puede

Describir qué hace el código, generar el diagrama a partir del repositorio, redactar y resumir.

No puede

Saber por qué se decidió así, qué se descartó, qué presión de negocio había ese día. Eso no está en el código.

Su ventaja profesionalLa IA documenta el qué. El porqué solo lo sabe quien estuvo en la reunión. Por eso el ADR no lo puede escribir una máquina.
Break de 20 min

Ahora les toca
a ustedes.

Al volver: abran su computador y entren a app.diagrams.net. Su documentación va a ser puesta a prueba por otro grupo.

Dinámica central · 60 min

La prueba del
recién llegado

Van a documentar un sistema en draw.io. Y otro grupo, sin hablar con ustedes, va a tener que entenderlo solo con ese archivo.

Por qué esta dinámica y no otra

Es su primer día de trabajo

Cuando entren a una empresa, nadie les va a explicar el sistema con calma. Les van a decir: "ahí está el repositorio, ahí está la wiki, cualquier cosa me preguntas". Y hay que producir.

La regla que lo hace realEl grupo que documenta no puede decir una sola palabra cuando comparte el enlace. Igual que en la vida real: quien escribió la documentación ya no está en la empresa.
Cómo funciona · cuatro fases

Las reglas

  1. Documentan. Reciben la ficha y la vuelven diagrama en draw.io. 22 min
  2. Entregan en silencio. Pasan el enlace al grupo siguiente. Sin explicar nada. 3 min
  3. Responden. Con el diagrama que recibieron, contestan cuatro preguntas del primer día. 17 min
  4. Se destapa. Los autores califican cuántas acertaron. Ese número es la nota. 20 min
Lo que hace distinta esta dinámica

Su nota depende de que otro entienda

No califico si el dibujo es bonito, ni si usaron los colores correctos. Califico cuántas de las cuatro preguntas pudo responder el grupo que recibió su diagrama.

Ese es el oficioUn arquitecto no se evalúa por lo que sabe, sino por lo que logró que otros entendieran. Hoy lo van a medir en carne propia.
Fase 1 · lo que dibujan

Qué va en el archivo

  1. Nivel 1 · contexto. El sistema, quién lo usa, con qué habla por fuera.
  2. Nivel 2 · contenedores. Las piezas que se despliegan por separado.
  3. Máximo cinco líneas de texto. Una caja de texto con lo que el dibujo no alcanza a decir.
Una pestaña por nivelUsen el + de abajo en draw.io: pestaña 1 para contexto, pestaña 2 para contenedores. Prohibido escribir párrafos: nadie lee ensayos el primer día.
Fase 3 · las cuatro preguntas

Lo que le preguntan a un recién llegado

1
¿Qué hace este sistema y para quién? En una frase, como se lo diría a alguien de otra área.
2
¿De qué depende que no controlamos? Sistemas de afuera que si fallan, nos afectan.
3
¿Dónde tocarían para un cambio? Les daré un cambio concreto por sistema.
4
¿Qué se cae si falla una pieza? Y sobre todo: qué sigue funcionando.
Cómo se evalúa · cuenta en el 50% de dinámicas

Qué estoy calificando

CriterioPesoQué observo
Cuántas acertó el otro grupo40%De las cuatro preguntas. Es la prueba objetiva.
Niveles bien separados20%No mezclaron personas con bases de datos.
Flechas con verbo20%Se entiende para qué se hablan las cajas.
Su desempeño como lectores20%Qué tan bien interpretaron la hoja que recibieron.
Antes de empezar

Tres reglas que no se negocian

EntregaEl enlace de su archivo de draw.io con permiso de lectura, más las respuestas que dieron sobre el diagrama ajeno.
Cierre de la dinámica · 10 min

Las tres preguntas del cierre

  1. A los que recibieron: ¿qué les habría servido que estuviera en la hoja y no estaba?
  2. A los que dibujaron: ¿qué dieron por obvio que no lo era?
  3. A todos: ¿cuál de las cuatro preguntas fue la más difícil de responder? ¿Por qué?
Cierre

Se llevan tres ideas

La próxima clase: si ya sabemos decidir y documentar, toca evaluar — cómo se revisa una arquitectura antes de construirla.
Tarea · próxima clase

Dibujen un sistema que usen

Elijan una app que usen todos los días y dibujen su nivel 1 de contexto en draw.io. Una sola pestaña.

← Portal
← → o el apuntador para avanzar · F pantalla completa · clic en los términos azules
1 / 74