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

LugarQué esCómo se pasa al siguiente
Su carpetaLos archivos que está editando ahoragit add
Área de preparaciónLo que va a entrar en la próxima fotogit commit
Repositorio localEl historial completo, en su máquinagit push
GitHubEl 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

FactorMonorepoPolirepo
Cambiar algo que cruza dos piezasUn solo commitCoordinar varios repos
Ver el sistema completoEstá todo ahíHay que ir armándolo
Equipos independientesSe estorban másAutonomía real
Permisos por equipoDifícil de acotarNatural
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 archivoQué 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.htmlLa página que se abre en el navegador.
README.mdLo 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

SiglaEn inglésQué quiere decir
CIContinuous Integration
Integración continua
Cada cambio que alguien sube se revisa automáticamente apenas llega, no al final del proyecto.
CDContinuous 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

  1. Hago que pagos importe notificaciones — la solución "obvia".
  2. Subo el cambio. El pipeline se pone rojo y explica qué regla se violó y por qué existe.
  3. Lo arreglo bien: pagos publica un evento en vez de llamar.
  4. 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

ReglaQué dicePor qué existe
R1catalogo no importa reservas, pagos ni notificacionesDebe sobrevivir aunque el resto falle
R2pagos no importa notificacionesSi el correo falla, el cobro no se cae
R3nucleo no importa a nadieSi 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

CriterioPesoQué observo
El pipeline en verde20%Su URL responde y la verificación pasa. Objetivo, sin discusión.
Los ADR30%Una decisión por clase, con driver, alternativa descartada y factura.
Las reglas25%Cada ADR tiene su regla verificable. Y la regla dice por qué existe.
Sustentación final25%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

  1. Copian el repositorio a su cuenta y activan Pages. 12 min
  2. Rompen la regla R2 a propósito y ven el pipeline en rojo. 12 min
  3. Lo arreglan bien, con un evento. Verde y desplegado. 15 min
  4. Escriben su propio ADR y su propia regla. 15 min
  5. Muestran su URL viva y explican su regla. 6 min
Fase 1 · el montaje

Copiar y encender

  1. Entren al repositorio del curso y presionen Fork. Queda una copia en su cuenta.
  2. Vayan a Settings → Pages y en Source elijan GitHub Actions.
  3. Vayan a la pestaña Actions y activen los flujos de trabajo.
  4. 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 fallaQué significaQué hacer
1 · Verificar la arquitecturaViolaron una reglaLean el log: dice cuál, dónde y por qué existe
2 · Desplegar a PagesLa arquitectura está bien; es configuraciónCasi 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

  1. Entren al archivo que quieren cambiar, dentro de su repositorio.
  2. Arriba a la derecha hay un lápiz. Denle clic y editen ahí mismo.
  3. Abajo, escriban el mensaje del commit y presionen Commit changes.
  4. 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

pagos llama a notificaciones.
Si el correo falla, el cobro se cae con él.

Lo que ya hacía

pagos anuncia 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 posibleEl driver que la justificaría
reservas no importa notificacionesSi el aviso falla, la reserva no se puede perder
catalogo no importa nucleo/eventosSolo lee: no debería poder disparar nada
notificaciones no importa pagos ni reservasSolo 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.

  1. El ADR en arquitectura/ADR-004-loquesea.md: driver, decisión, alternativa descartada y factura.
  2. La regla en arquitectura/reglas.json, con su campo porque.
  3. 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

EntregaEl enlace de su repositorio y el enlace de su URL desplegada, por el canal del curso.
Cierre

Se llevan tres ideas

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

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?
← Portal
← → o el apuntador para avanzar · F pantalla completa · clic en los términos azules
1 / 57