Ingeniería de Sistemas · Semestre IV · 2026-2 · Clase 6 de 16
La arquitectura que se defiende sola
Hoy sus decisiones dejan de ser un documento y se vuelven una regla que el sistema hace cumplir. Y su primer despliegue queda con URL pública. — Elkin Rodríguez E.
Ruta de hoy · 3 horas
Cómo va a fluir la clase
01
Cierre del recién llegado Los resultados de la clase pasada. 10 min.
02
Git El problema que resuelve y cómo se usa de verdad.
03
Monorepo o polirepo La decisión de repositorio que sí es de arquitectura.
04
El repositorio por dentro y CI/CD Qué es src, qué es un YAML, y el pipeline que rechaza lo que viola su ADR.
05
Arranca el proyecto integrador Su repositorio, desplegado, con URL propia.
Cierre de la clase pasada · 10 min
Los resultados del recién llegado
Cada grupo documentó un sistema y otro grupo respondió cuatro preguntas usando solo ese diagrama. Estos son los números.
Lo que enseña el númeroNadie sacó cuatro de cuatro por dibujar bonito. Los que acertaron más fueron los que pusieron verbo en las flechas y una línea de qué hace cada caja. La documentación no se evalúa en quien la escribe: se evalúa en quien la lee.
El problema que arrastramos desde la Clase 3
Un ADR que nadie hace cumplir es un papel.
Escribieron decisiones excelentes. Pero nada impide que mañana alguien las viole sin darse cuenta — y nadie se entere hasta que duela.
Dónde estamos
El hilo del semestre
Clases 2 a 4
Decidir: drivers, estilos y patrones.
→
Clase 5
Comunicar: documentación y C4.
→
Hoy
Construir y hacer cumplir. Su primer sistema desplegado.
Empecemos por el problema, no por los comandos
¿Cómo trabajan diez personas sobre el mismo código?
Sin una herramienta, la respuesta histórica fue carpetas con nombres como proyecto_final_v3_ESTE_SI.zip. Y perder trabajo era normal.
Las tres preguntas que resuelve Git1. ¿Quién cambió esto y por qué? · 2. ¿Cómo vuelvo a como estaba antes? · 3. ¿Cómo junto mi trabajo con el del otro sin pisarlo?
La idea central
Git guarda fotos, no archivos
Cada commit es una foto completa del proyecto en un momento, con autor, fecha y un mensaje que dice por qué se hizo el cambio.
foto 1 versión inicial
→
foto 2 agregué canchas
→
foto 3 arreglé el precio
Por eso importa el mensajeUn commit que dice cambios no sirve de nada. Uno que dice separo catalogo de pagos segun ADR-001 es documentación que vive con el código.
Los tres lugares
Dónde vive su código
Lugar
Qué es
Cómo se pasa al siguiente
Su carpeta
Los archivos que está editando ahora
git add
Área de preparación
Lo que va a entrar en la próxima foto
git commit
Repositorio local
El historial completo, en su máquina
git push
GitHub
El repositorio compartido con el equipo
—
El error de principianteCreer que commit ya subió el código. No. Hasta que no hace push, su trabajo vive solo en su computador.
Demo en vivo · lo hago en pantalla
Los cinco comandos que resuelven el 90%
Git Bash · el ciclo completo de un cambio
git status # que cambio desde la ultima foto
git add . # preparo todo para la foto
git commit -m "separo catalogo segun ADR-001"
git push # lo subo a GitHub
git log --oneline # veo el historial
Fíjense en el mensaje del commitCita el ADR. Así, dentro de seis meses, quien lea el historial entiende no solo qué cambió sino por qué se decidió así.
La pieza que asusta
Ramas: trabajar sin pisarse
Una rama es una línea de trabajo paralela. Usted se lleva una copia, trabaja tranquilo, y cuando está listo la junta con la principal.
Sin ramas
todos escribiendo sobre lo mismo a la vez
El último que guarda borra al anterior.
Con ramas
main
↙ ↘
rama de Ana
rama de Luis
Cada uno avanza y luego se juntan (merge).
Lo que a todos les da miedo
El conflicto no es un error
Un conflicto ocurre cuando dos personas cambiaron la misma línea. Git no adivina cuál vale: se detiene y le pregunta a usted.
Cámbienle el nombre en la cabezaNo es que Git se dañó. Es que Git fue honesto: encontró una decisión que solo una persona puede tomar. Resolverlo es abrir el archivo, borrar las marcas y dejar la versión correcta.
La forma profesional de integrar
El Pull Request
En el trabajo nadie escribe directo en main. Se abre un Pull Request: una propuesta de cambio que alguien más revisa antes de que entre.
creo una rama
→
hago el cambio
→
abro el PR
→
alguien revisa
→
entra a main
¿Les suena?Ese "alguien revisa" es el code review del que hablamos en la Clase 4. El Pull Request es el lugar físico donde ocurre.
Capa 1 · esto sí es arquitectura
Un repositorio, o muchos
Aquí Git deja de ser una herramienta y se vuelve una decisión de arquitectura con factura, igual que las de la Clase 3.
Monorepo · todo junto
un solo repositorio
↓
catálogo
pagos
reservas
Polirepo · uno por pieza
repo catálogo
repo pagos
repo reservas
Cada equipo dueño de lo suyo.
La factura de cada uno
Ninguno es mejor
Factor
Monorepo
Polirepo
Cambiar algo que cruza dos piezas
Un solo commit
Coordinar varios repos
Ver el sistema completo
Está todo ahí
Hay que ir armándolo
Equipos independientes
Se estorban más
Autonomía real
Permisos por equipo
Difícil de acotar
Natural
Quién usa qué, de verdadGoogle tiene casi todo su código en un monorepo gigantesco. Netflix trabaja con muchos repositorios separados. Los dos funcionan — porque resolvieron problemas distintos.
La conexión que quiero que hagan
Es el mismo trade-off de siempre
Monorepo se parece al monolito: todo junto, fácil de ver, difícil de separar. Polirepo se parece a microservicios: autonomía real, a cambio de coordinación.
Y la trampa que ya conocenLa estructura del repositorio no obliga a la del sistema. Se puede tener un monorepo con microservicios adentro. Confundirlos es el error más común.
Break de 20 min
Al volver, su primer despliegue.
Abran el computador y entren a github.com. Si no tienen cuenta, créenla ahora — es gratis y les va a servir el resto de la carrera.
Antes de seguir · vocabulario
Qué es un repositorio
Es la carpeta del proyecto, pero con memoria: guarda todos los archivos y el historial completo de cómo llegaron a ser lo que son.
La diferencia con una carpeta normalUna carpeta en su computador tiene el estado actual. Un repositorio tiene el estado actual y todos los anteriores, con quién los hizo y por qué. Por eso se puede volver atrás.
Recorrido por el repositorio
Qué hay en cada carpeta
Carpeta o archivo
Qué guarda
src/
El código fuente (de source). Aquí vive la aplicación, partida en módulos.
arquitectura/
Los ADR y las reglas. No es código: son las decisiones.
tools/
Herramientas de apoyo. Aquí vive el verificador de arquitectura.
.github/workflows/
El pipeline. GitHub busca aquí y ejecuta lo que encuentre.
index.html
La página que se abre en el navegador.
README.md
Lo primero que ve quien llega. Explica de qué se trata.
Dos detalles que confunden
El punto y la extensión
¿Por qué .github empieza con punto?
En Linux y Mac, una carpeta que empieza con punto está oculta. Se usa para cosas de configuración que no son parte del producto. Si no la ve en su computador, active "mostrar archivos ocultos".
¿Qué significa .md?
Markdown. Es texto plano con marcas simples: # hace un título, **algo** lo pone en negrita. Se lee bien sin abrirlo con nada especial — por eso la documentación técnica vive en Markdown.
El formato del pipeline
Qué es un archivo YAML
Se escribe .yml o .yaml. Es una forma de escribir configuración que una máquina lee y un humano entiende. No es un lenguaje de programación: no tiene lógica, solo describe cosas.
La regla que lo gobierna
La sangría manda. Lo que está más a la derecha pertenece a lo que está arriba y a la izquierda. Y se usan espacios, nunca tabulaciones.
Cómo se lee
nombre: valor es un dato. Una línea que empieza con - es un elemento de una lista. Y # es un comentario.
YAML · un ejemplo mínimo
Lo mismo, en dos idiomas
Si lo dijéramos en españolUn curso llamado Arquitectura, de 3 créditos, con dos temas: patrones y estilos.
En YAMLcurso: Arquitectura creditos: 3 temas: - patrones - estilos
Eso es todoNombre, dos puntos, valor. Y guiones para las listas. El pipeline que van a usar no es más complicado que esto — solo más largo.
Las dos siglas del día
Qué significa CI/CD
Sigla
En inglés
Qué quiere decir
CI
Continuous Integration Integración continua
Cada cambio que alguien sube se revisa automáticamente apenas llega, no al final del proyecto.
CD
Continuous Delivery / Deployment Entrega o despliegue continuo
Si el cambio pasó la revisión, sale a producción solo, sin que nadie lo empuje a mano.
Por qué se nombran juntasPorque la segunda no puede existir sin la primera. Desplegar automáticamente sin revisar automáticamente es publicar errores más rápido.
El problema que vino a resolver
Cómo se hacía antes
Sin CI/CD
cada quien trabaja tres meses aparte y al final se junta todo
Se llamaba «la semana de la integración» y era un infierno: cientos de conflictos a la vez.
Con CI/CD
cada cambio se integra hoy
↓
si algo choca, se sabe en minutos
Los problemas son pequeños porque se encuentran temprano.
La idea de fondo: si algo duele, háganlo más seguido. Integrar dolía, entonces se integra cada vez.
Capa 1 · el mecanismo
Qué es un pipeline
Una lista de pasos que se ejecutan solos cada vez que alguien sube un cambio. Nadie los dispara a mano y nadie los puede saltar.
alguien sube un cambio
→
se revisa automáticamente
→
¿pasó?
→
se despliega solo
Lo que lo hace distintoNadie lo dispara y nadie lo puede saltar. Aunque tenga afán, aunque sea viernes: si el pipeline dice que no, el cambio no entra.
Por qué esto es clase de arquitectura
Sin pipeline, «despliegue independiente» es una promesa
En la Clase 3 les dije que la gran ventaja de microservicios es poder desplegar una pieza sin tocar las otras. Lo aceptaron. Pero nunca han visto un despliegue.
La verdad incómodaUn sistema separado en piezas que se despliegan todas juntas y a mano no tiene despliegue independiente. Tiene un monolito con más archivos. El pipeline es lo que hace verdad la promesa.
Y ahora la pieza clave del día
Función de aptitud
Es una prueba automática que verifica que la arquitectura no se degrade. No revisa si el código funciona: revisa si respeta las decisiones que ustedes tomaron.
De dónde saleEl concepto es de Neal Ford y Rebecca Parsons en Building Evolutionary Architectures, y Neal Ford es coautor del libro de Richards que es el eje de este curso.
El giro que cambia todo
Su ADR, convertido en regla
Antes · un documento
"cartelera va separada de pagos" nadie lo verifica
En seis meses alguien lo viola sin saber que existía.
Ahora · una regla viva
el pipeline lo revisa
↓
si se viola: rojo, no despliega
La decisión se defiende sola.
Ese es el título de hoy: la arquitectura que se defiende sola.
Cómo se ve una regla
La decisión, en un archivo
arquitectura/reglas.json · así queda escrito un ADR verificable
{
"id": "R2",
"adr": "ADR-002",
"modulo": "pagos",
"no_puede_importar": ["notificaciones"],
"porque": "Si el envio de correos falla, el cobro NO se puede caer."
}
Miren el último campoLa regla trae su propia razón de existir. Cuando el pipeline se pone rojo, no dice «error»: dice por qué esa regla está ahí. Es la cerca con el letrero al lado.
Cómo se ve el pipeline
Dos pasos, y el segundo depende del primero
.github/workflows/pipeline.yml · lo esencial
jobs:
verificar:
steps:
- run: node tools/verificar-arquitectura.js
desplegar:
needs: verificar # si el paso 1 falla, este NUNCA corre
steps:
- uses: actions/deploy-pages@v4
Toda la clase cabe en una líneaneeds: verificar. Eso es lo que hace que una arquitectura violada no llegue a producción.
Demo en vivo · lo hago en pantalla
Rojo y verde
Hago que pagos importe notificaciones — la solución "obvia".
Subo el cambio. El pipeline se pone rojo y explica qué regla se violó y por qué existe.
Lo arreglo bien: pagospublica un evento en vez de llamar.
Verde. Y la aplicación queda desplegada.
Fíjense en el paso 3: la forma correcta de arreglarlo es Observer, el patrón de la Clase 4.
Arranca hoy · es el parcial del segundo corte
Proyecto integrador
A partir de hoy cada grupo tiene un repositorio propio, desplegado y con URL pública, que va a evolucionar el resto del semestre.
Lo primero, para que nadie se asuste
No es construir un sistema grande
El sistema base ya está hecho y funciona. Lo que ustedes van a entregar no es una aplicación enorme: es el rastro de sus decisiones.
Por qué asíPorque eso es lo que produce un arquitecto. Nadie le pide a un arquitecto que escriba toda la aplicación. Le pide que decida, lo justifique y responda por ello.
El sistema base
Canchas Bogotá
Reserva de canchas sintéticas. Cuatro canchas, cuatro horarios, reserva y pago. Funciona y está desplegado.
catalogo
Solo lectura. Muestra canchas y horarios.
reservas · pagos
Bloquean el horario y cobran. Consistencia fuerte.
notificaciones
Escucha eventos y avisa. Nadie la llama.
Y trae algo que no habían vistoTres ADR ya escritos, convertidos en tres reglas verificables, con un pipeline que las hace cumplir.
Las tres reglas del repositorio
Lo que el pipeline defiende
Regla
Qué dice
Por qué existe
R1
catalogo no importa reservas, pagos ni notificaciones
Debe sobrevivir aunque el resto falle
R2
pagos no importa notificaciones
Si el correo falla, el cobro no se cae
R3
nucleo no importa a nadie
Si la base depende de alguien, se vuelve un nudo
Cómo va a crecer
Una decisión por clase
Hoy · Clase 6
Su repositorio, desplegado, con el pipeline verde. Y la primera regla propia.
Clase 7 · Microservicios
Separan un módulo con contrato explícito. La regla lo verifica.
Clase 8 · Eventos
Comunican dos piezas por eventos en vez de llamadas.
Clase 9 · CQRS
Separan el modelo de lectura del de escritura.
Ojo con estoNo es trabajo extra: es el mismo contenido de esas clases, aplicado a su repositorio en vez de quedarse en la diapositiva.
Cómo se evalúa · es el 40% del segundo corte
Qué estoy calificando
Criterio
Peso
Qué observo
El pipeline en verde
20%
Su URL responde y la verificación pasa. Objetivo, sin discusión.
Los ADR
30%
Una decisión por clase, con driver, alternativa descartada y factura.
Las reglas
25%
Cada ADR tiene su regla verificable. Y la regla dice por qué existe.
Sustentación final
25%
Defienden una decisión que yo elijo, sin notas.
La regla de oro del proyecto
Si cambia la arquitectura, cambia el ADR
No se acepta un cambio de estructura sin su ADR, ni una regla sin la decisión que la justifica.
No sirve
Un ADR que nadie hace cumplir es un papel. Una regla sin ADR es una imposición sin razón.
Sí sirve
Decisión escrita + regla que la verifica + pipeline que la aplica. Las tres cosas o ninguna.
Dinámica · 60 min
El pipeline que dice que no
Van a romper la arquitectura a propósito, ver el sistema rechazarlo, arreglarlo bien, y terminar con su aplicación desplegada.
Todo gratis y sin instalar nada
Lo único que necesitan
Una cuenta de GitHub
Gratis. Sin tarjeta. Sirve el resto de su carrera.
El navegador
Se puede hacer todo desde la web. No hay que instalar Git.
Un computador por grupo
Con eso basta para las cuatro fases.
Por qué desde el navegadorPorque algunos ya manejan Git y otros no, y nadie se puede quedar bloqueado instalando. Quien quiera usar Git Bash, adelante — es el mismo resultado.
Las cinco fases
Qué van a hacer
Copian el repositorio a su cuenta y activan Pages. 12 min
Rompen la regla R2 a propósito y ven el pipeline en rojo. 12 min
Lo arreglan bien, con un evento. Verde y desplegado. 15 min
Escriben su propio ADR y su propia regla. 15 min
Muestran su URL viva y explican su regla. 6 min
Fase 1 · el montaje
Copiar y encender
Entren al repositorio del curso y presionen Fork. Queda una copia en su cuenta.
Vayan a Settings → Pages y en Source elijan GitHub Actions.
Vayan a la pestaña Actions y activen los flujos de trabajo.
Esperen el semáforo verde. Su URL aparece en Settings → Pages.
Anoten esa URLEs su sistema, en internet, accesible desde cualquier celular. Guárdenla: es parte de la entrega.
Antes de arrancar · qué es un fork
Copiar un repositorio a su cuenta
Un fork es una copia completa de un repositorio ajeno que queda en su cuenta, con todo el historial. Desde ese momento es suyo: puede cambiar lo que quiera sin afectar el original.
repositorio del curso
→
botón Fork
→
copia en su cuenta
→
su URL desplegada
OjoNo necesitan que yo les dé permisos. El fork lo hacen ustedes y queda bajo su nombre. Es así como funciona todo el software libre del mundo.
Fase 1 · aquí es donde se van a atascar
Los dos clics escondidos
1 · Habilitar los flujos
Vayan a la pestaña Actions. GitHub muestra un aviso amarillo diciendo que los workflows están deshabilitados en los forks. Hay que darle al botón verde para habilitarlos. Si no lo hacen, nada corre.
2 · Encender Pages
Settings → Pages. En Source elijan GitHub Actions.
No elijan "Deploy from a branch": esa es la opción vieja y no usa el pipeline.
Cuando termine el pipelineSu URL aparece en Settings → Pages, arriba. Tiene la forma usuario.github.io/canchas-bogota. Anótenla.
Si el primer despliegue falla · pasa casi siempre
El error de Pages
Lo que van a ver en el job 2
Error: Get Pages site failed. Please verify that the
repository has Pages enabled ... Error: Not Found
Qué significa y cómo se arreglaPages no se enciende solo. Vayan a Settings → Pages → Source y elijan GitHub Actions. Después, en Actions, entren al flujo que falló y presionen Re-run all jobs.
Cómo leer un fallo · les va a servir siempre
¿Cuál de los dos jobs falló?
El job que falla
Qué significa
Qué hacer
1 · Verificar la arquitectura
Violaron una regla
Lean el log: dice cuál, dónde y por qué existe
2 · Desplegar a Pages
La arquitectura está bien; es configuración
Casi siempre: Pages sin encender
Es una habilidad, no un trámiteSaber en qué paso falló un pipeline es lo primero que hace alguien con experiencia. El mensaje de error casi siempre dice qué pasó — el problema es que nadie lo lee.
Cómo editar sin instalar nada
El lápiz de GitHub
Entren al archivo que quieren cambiar, dentro de su repositorio.
Arriba a la derecha hay un lápiz. Denle clic y editen ahí mismo.
Abajo, escriban el mensaje del commit y presionen Commit changes.
Vayan a Actions: el pipeline arranca solo en segundos.
Eso es un commit y un push, todo juntoEditar desde la web hace las dos cosas de una vez. Por eso hoy no necesitan instalar Git — aunque quien quiera usarlo, obtiene el mismo resultado.
Fase 2 · qué van a ver exactamente
Cómo se ve el rojo
Lo que dice el pipeline cuando falla · léanlo completo
[X] R2 VIOLADA (ADR-002)
Archivo: src/pagos/pagos.js
"pagos" esta importando a "notificaciones", y no puede.
Por que existe esta regla: Si el envio de correos falla,
el cobro NO se puede caer.
ARQUITECTURA VIOLADA: 1 problema(s). El despliegue se detiene.
Fíjense en la tercera líneaNo dice «error». Dice por qué existe esa regla. Es la cerca del campo de la clase pasada — pero esta vez con el letrero al lado.
Fase 3 · el archivo, exacto
Así queda bien
src/pagos/pagos.js · borren la línea del import y déjenlo así
import { publicar } from '../nucleo/eventos.js';
export function cobrar(reserva) {
const referencia = 'PG-' + Math.random().toString(36)
.slice(2, 8).toUpperCase();
publicar('pago.aprobado',
Object.assign({}, reserva, { referencia: referencia }));
return { ok: true, referencia: referencia, valor: reserva.valor };
}
Y aquí está el punto de toda la clase
La solución correcta ya estaba ahí
Miren la línea publicar('pago.aprobado', ...). Siempre estuvo en el archivo. El correo sí se envía — pero por evento, no por llamada directa.
Lo que intentaron
pagosllama a notificaciones. Si el correo falla, el cobro se cae con él.
Lo que ya hacía
pagosanuncia que hubo un pago. Si el correo falla, el cobro ya ocurrió.
Eso es ObserverEl patrón de la Clase 4. Y ahora saben para qué servía: no es elegancia, es que el cobro no dependa del correo.
Fase 4 · ideas para su propio ADR
Qué frontera van a proteger
Elijan una y escríbanla. Estas son ideas, no obligaciones — si se les ocurre otra mejor, mejor.
Regla posible
El driver que la justificaría
reservas no importa notificaciones
Si el aviso falla, la reserva no se puede perder
catalogo no importa nucleo/eventos
Solo lee: no debería poder disparar nada
notificaciones no importa pagos ni reservas
Solo escucha; si conoce a los demás, deja de ser desacoplada
Fase 2 · rompan la regla
El negocio pide algo razonable
«Cuando se apruebe un pago, quiero que se envíe el correo de confirmación.» Suena simple. La solución obvia es que pagos llame a notificaciones.
src/pagos/pagos.js · agreguen esta línea arriba
import { enviarCorreo } from '../notificaciones/notificaciones.js';
Ahora hagan commit y vayan a ActionsEl pipeline se va a poner rojo en menos de un minuto. En la siguiente diapositiva está exactamente lo que van a leer.
Fase 3 · arréglenlo bien
La solución correcta es un patrón
No se trata de borrar la regla. Se trata de resolver el problema sin violarla: pagos publica un evento y notificaciones se suscribe.
Quiten el import y dejen solo esto en cobrar()
publicar('pago.aprobado', { ...reserva, referencia });
Eso es ObserverEl mismo patrón de la Clase 4. Y ahora entienden para qué servía: no es elegancia, es que el cobro no dependa del correo.
Fase 4 · su primera decisión propia
Escriban su ADR
Elijan una frontera que ustedes crean que hay que proteger en este sistema, y conviértanla en regla.
El ADR en arquitectura/ADR-004-loquesea.md: driver, decisión, alternativa descartada y factura.
La regla en arquitectura/reglas.json, con su campo porque.
Prueben que sirve: viólenla a propósito, vean el rojo, y déjenla en verde.
El recurso que les va a servir todo el semestre
La guía de campo
En los recursos del curso está Guía de campo · Git y GitHub: una sola página con todo lo de hoy, y con los comandos listos para copiar.
En su máquina
El ciclo completo con VS Code y Git Bash, paso a paso.
Comandos de Git
Ramas, conflictos y las cinco formas de volver atrás.
Equipos de la sala
Cómo usar su cuenta en un computador compartido.
Cuándo abrirlaCuando algo falle y no sepan por dónde empezar. Tiene una sección de qué hacer cuando el pipeline se cae, con los dos errores que más aparecen.
Antes de entregar
Chequeo rápido
¿Su URL pública abre y la aplicación funciona?
¿El pipeline está en verde?
¿Su ADR dice qué se paga, no solo qué se gana?
¿Su regla tiene el campo porque escrito con una razón real?
¿Probaron que la regla de verdad detecta la violación?
EntregaEl enlace de su repositorio y el enlace de su URL desplegada, por el canal del curso.
Cierre
Se llevan tres ideas
Git no es guardar archivos: es dejar constancia de quién decidió qué y por qué.
Monorepo o polirepo es una decisión de arquitectura, con la misma factura de siempre.
Una decisión que no se verifica, se pierde. El pipeline la defiende cuando ustedes no están.
La próxima clase: microservicios — y ahora sí van a poder comprobar si el despliegue independiente es cierto.
Tarea · próxima clase
Dejen su repositorio listo
URL desplegada y funcionando.
Su ADR-004 escrito, con su regla verificándose.
Un commit con un mensaje que cite el ADR.
Y una pregunta para pensarSi mañana tuvieran que separar reservas en un servicio aparte, ¿qué regla nueva haría falta para que nadie lo vuelva a pegar sin darse cuenta?