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
01Quiz + conceptos elementales Lo que sostiene cualquier arquitectura: IP, DNS, API, latencia, escalar.
02El oficio del arquitecto Qué hace de verdad, y cómo se llega ahí.
03Por qué se documenta Y sobre todo: qué NO se documenta.
04El modelo C4 en draw.io Cuatro niveles de zoom, con tres casos completos.
05Diná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ón | Tamaño | Cómo se ve | Cuántas caben |
|---|
| IPv4 | 32 bits | 142.250.190.46 | ≈ 4.300 millones |
| IPv6 | 128 bits | 2001:0db8::7334 | 340 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ón | Qué pasó con ella |
|---|
| IPv4 | La que funcionó. Sostiene internet desde 1983. |
| IPv0 – IPv3 | Experimentales de los años 70. Nunca se desplegaron. |
| IPv5 | Asignada a un protocolo de video y voz que no prosperó. |
| IPv6 | La 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.
| Parte | Ejemplo | Qué hace |
|---|
| Protocolo | https:// | Cómo se va a hablar, y si va cifrado |
| Subdominio | www. | Una sección dentro del dominio |
| Dominio | utadeo.edu.co | El 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 clienteEl servidor ve la IP del proxy, no la suya.
Reverse proxy · protege al servidorinternet
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ónde | Ida y vuelta aproximada |
|---|
| Bogotá → servidor en Bogotá | 1 a 5 ms |
| Bogotá → Virginia (EE. UU.) | 80 a 120 ms |
| Bogotá → Fráncfort | 150 a 200 ms |
| Bogotá → Singapur | 250 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 planousuario: elkin
clave: 1234
legible para cualquiera
En un wifi público, esto es regalar la contraseña.
HTTPS · cifrado con TLSa8f3d9e2b7c1…
↓
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.
| Verbo | Qué hace | Ejemplo |
|---|
| GET | Consultar | GET /estudiantes/1032 |
| POST | Crear | POST /matriculas |
| PUT / PATCH | Actualizar | PATCH /estudiantes/1032 |
| DELETE | Eliminar | DELETE /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 decidepide 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.
| Familia | Cómo guarda | Cuándo brilla |
|---|
| SQL (relacional) | Tablas con esquema fijo definido de antemano | Cuando los datos tienen forma estable y hay dinero de por medio |
| NoSQL | Documentos, clave-valor o grafos, sin esquema rígido | Cuando 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.
| Letra | Qué garantiza | En una transferencia |
|---|
| Atomicidad | Todo o nada | O se debita y se acredita, o no pasa nada |
| Consistencia | Las reglas se respetan siempre | Nunca queda un saldo negativo prohibido |
| Islamiento | Las operaciones no se pisan | Dos retiros simultáneos no se estorban |
| Durabilidad | Lo confirmado no se pierde | Si 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 grandemás RAM
más CPU
hay un techo físico
Rápido de hacer. Un solo punto de falla.
Horizontal · más servidores igualesSin 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.
| Estrategia | Cómo decide | Cuándo conviene |
|---|
| Round Robin | Por turnos: uno a cada quien, en orden | Servidores iguales y peticiones parecidas |
| Least Connections | Al que tenga menos conexiones activas | Peticiones de duración muy distinta |
| IP Hash | El mismo usuario siempre al mismo servidor | Cuando 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 índicela base revisa
fila por fila
2 millones de filas
Una consulta puede tardar segundos.
Con índicebusca 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 completasSirve para leer más. No para guardar más.
Sharding · pedazos distintosSirve 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.
| Enfoque | Qué hace | Ejemplo típico |
|---|
| Partición vertical | Separa las columnas en tablas distintas según cómo se usan | Datos básicos aparte de datos de perfil |
| Base columnar | Guarda por columna en vez de por fila, así leer 3 de 200 es barato | Amazon 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.
| Sigla | Qué significa | Si la red se parte… |
|---|
| Consistencia | Todos 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 tolerance | Aguanta que la red se corte | No 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 CDNBogotá → Virginia
cada vez
~100 ms por archivo
Y si son 50 archivos, la página se arrastra.
Con CDNEl 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 abiertocliente ⟷ 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.
8aReunión con producto Quieren una función nueva para el trimestre. Hay que estimar si el sistema aguanta.
10aRevisión de un diseño Un equipo propone separar un módulo. Toca preguntar qué se paga.
2pEscribir un documento Dejar por escrito por qué se eligió una base de datos y no otra.
4pExplicarle 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 creenEl arquitecto es el programador más veterano, el que resuelve lo que nadie puede.
Lo que esLa 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?
1Nadie llega recién graduado Se necesitan años viendo sistemas envejecer. No se puede acelerar leyendo.
2El camino empieza opinando En revisiones de código, en reuniones de diseño. Quien argumenta bien se hace notar.
3Se nota quién piensa en el después El que pregunta "¿y cuando esto crezca?" ya está haciendo el trabajo.
4Y quien sabe escribir La mitad del oficio es documentos y correos que otros entiendan.
Tres cargos que se confunden
Quién hace qué
| Rol | Su pregunta diaria | Alcance |
| 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 que llega nuevo tarda meses en poder tocar algo sin miedo.
- La decisión se olvida y alguien la deshace sin saber por qué existía.
- Todo depende de una persona. Si se va, el conocimiento se va con ella.
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 documentaLo 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 documentaLo 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.
MuertaLarga · en un archivo aparte · escrita para cumplir · desactualizada a los tres meses.
VivaCorta · 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
- Cada caja con nombre y una línea de qué hace. Sin la línea, la caja no dice nada.
- Cada flecha con verbo y dirección. "Consulta notas", no una raya suelta.
- Un solo nivel por dibujo. No mezclar personas con bases de datos.
- 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 error | Por qué mata el diagrama |
| Flechas sin verbo | Sé que se hablan, pero no sé para qué. |
| Mezclar niveles | Una persona al lado de una tabla de base de datos. No se entiende la escala. |
| Cajas con nombre técnico solo | svc-auth-v2 no le dice nada a nadie nuevo. |
| Veinte cajas | Si 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.
- ¿Quiénes lo usan? Nómbrenlos. Ojo: no todos son clientes.
- ¿Con qué sistemas de afuera habla? Piensen en el dinero, no en el código.
- 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í:
| Caso | El driver que manda | La pieza que aparece por eso |
| Boletería | Cero doble venta de una silla | Servicio de Reserva de Sillas |
| BiciCiudad | Estaciones sin señal siguen prestando | Controlador de Estación con bitácora local |
| Mercado campesino | Un pago repartido que debe cuadrar | Servicio 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 lee | Qué le preocupa | Qué nivel necesita |
| Gerente | Cuánto cuesta y qué riesgo tiene | Nivel 1 · nada más |
| Desarrollador nuevo | Dónde toco para hacer un cambio | Niveles 2 y 3 |
| Operación | Qué se cae y a quién llamo | Nivel 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.
- Un repositorio con ADRs y diagramas hace que la IA proponga cambios coherentes con el sistema.
- Sin contexto, la IA escribe código correcto que no encaja con las decisiones que ya tomaron.
Capa 2 · la conclusión incómoda
Lo que la IA no puede documentar
Sí puedeDescribir qué hace el código, generar el diagrama a partir del repositorio, redactar y resumir.
No puedeSaber 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
- Documentan. Reciben la ficha y la vuelven diagrama en draw.io. 22 min
- Entregan en silencio. Pasan el enlace al grupo siguiente. Sin explicar nada. 3 min
- Responden. Con el diagrama que recibieron, contestan cuatro preguntas del primer día. 17 min
- 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
- Nivel 1 · contexto. El sistema, quién lo usa, con qué habla por fuera.
- Nivel 2 · contenedores. Las piezas que se despliegan por separado.
- 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
| Criterio | Peso | Qué observo |
| Cuántas acertó el otro grupo | 40% | De las cuatro preguntas. Es la prueba objetiva. |
| Niveles bien separados | 20% | No mezclaron personas con bases de datos. |
| Flechas con verbo | 20% | Se entiende para qué se hablan las cajas. |
| Su desempeño como lectores | 20% | Qué tan bien interpretaron la hoja que recibieron. |
Antes de empezar
Tres reglas que no se negocian
- En draw.io. Entren a
app.diagrams.net, activen las formas C4 y guarden en Drive.
- Silencio al entregar. Ni una palabra, ni un gesto. El archivo habla solo o no habla.
- No busquen el sistema en internet. Documenten lo que dice su ficha, nada más.
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
- A los que recibieron: ¿qué les habría servido que estuviera en la hoja y no estaba?
- A los que dibujaron: ¿qué dieron por obvio que no lo era?
- A todos: ¿cuál de las cuatro preguntas fue la más difícil de responder? ¿Por qué?
Cierre
Se llevan tres ideas
- El arquitecto no es el que más sabe de código: es el que mejor decide y mejor explica.
- Se documenta lo caro de descubrir preguntando — el porqué, no el qué.
- La documentación se mide en el que lee, no en el que escribe.
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.
- Quién la usa, además del usuario obvio.
- Con qué sistemas de afuera habla.
- Una cosa que no supieron cómo dibujar.
← → o el apuntador para avanzar · F pantalla completa · clic en los términos azules