Proyecto: Tinkuy, un sistema que se rediseña
El proyecto del curso es un solo sistema, Tinkuy, una plataforma de venta de entradas para conciertos y partidos. Empieza como un monolito pequeño que funciona. En cada entrega llega un requisito de calidad nuevo, escrito como un escenario con su medida, que el diseño de ese momento no cumple. El trabajo es siempre el mismo:
- Medir el sistema como está y comprobar que el escenario no se cumple.
- Decidir cómo cambiar la arquitectura, comparando al menos dos alternativas.
- Implementar el cambio.
- Documentar la decisión en un ADR y actualizar los diagramas C4.
- Comprobar el escenario con las pruebas públicas de la entrega, y que las pruebas de las entregas anteriores sigan pasando.
No hay una solución única. Las pruebas comprueban el escenario (que el sistema responde dentro del umbral, que no se vende un asiento dos veces, que una falla no tumba la venta), no cómo lo resolvieron. Dos equipos pueden pasar las mismas pruebas con arquitecturas distintas, y la diferencia se discute en sus ADRs.
Las semanas de cada entrega están en el calendario del SYLLABUS. Cada entrega tiene su enunciado en su carpeta:
| # | Enunciado | Carpeta |
|---|---|---|
| P0 | Reconocimiento | p0-reconocimiento/ |
| P1 | Módulos con límites | p1-modulos/ |
| P2 | La apertura de ventas | p2-apertura-de-ventas/ |
| P3 | Lecturas que escalan | p3-lecturas/ |
| P4 | Pagos como servicio | p4-pagos/ |
| P5 | Cuando algo falla | p5-fallas/ |
| # | Entrega | El requisito que llega | Lo que se entrega | Temas del curso | Publicado | Entrega |
|---|---|---|---|---|---|---|
| P0 | Reconocimiento | Ninguno todavía: entender lo que hay | Diagramas C4 de contexto y de contenedores, tres escenarios de calidad medidos con k6, y una regla de dependencia que deja de violarse (individual) | Semanas 1–3 | Sem. 1 | Sem. 3 |
| P1 | Módulos con límites | Modificabilidad: agregar un medio de pago sin tocar el núcleo | Modular monolith con límites que se comprueban en cada build, y un medio de pago nuevo como plug-in | Semanas 3–5 | Sem. 3 | Sem. 5 |
| P2 | La apertura de ventas | Rendimiento y corrección bajo carga: se abre la venta de un concierto | Latencia p95 dentro del umbral y ninguna entrada vendida dos veces, con las tácticas elegidas justificadas | Semanas 5–7 y 12 | Sem. 5 | Sem. 8 |
| P3 | Lecturas que escalan | Escalabilidad de lectura: el catálogo responde aunque el principal esté ocupado | Una réplica de lectura y una cache, con read-your-writes para quien compra, y un cambio de contrato sin romper a un cliente antiguo | Semanas 9–11 | Sem. 8 | Sem. 11 |
| P4 | Pagos como servicio | Despliegue y aislamiento: los pagos salen del monolito | Un servicio de pagos propio, saga de compra, outbox, mensajes con NATS y consumidores idempotentes | Semanas 12–13 | Sem. 11 | Sem. 14 |
| P5 | Cuando algo falla | Disponibilidad: la pasarela lenta o caída no tumba la venta | Timeouts, circuit breaker y load shedding comprobados con Toxiproxy, logs estructurados y SLOs, make fitness y el documento de arquitectura final |
Semanas 14–16 | Sem. 14 | Sem. 16 |
P2 se publica antes de la semana 12, que es donde el curso estudia las transacciones a fondo. Es a propósito: el enunciado de P2 da lo necesario para no vender un asiento dos veces, y la semana 12 vuelve sobre esa decisión con más herramientas.
Reglas de entrega
- P0 es individual. P1–P5: [confirmar] (parejas o equipos, y si se mantienen todo el semestre).
- Cada equipo trabaja en un repositorio de Git creado a partir de
tinkuy/. Cada entrega es un tag en ese repositorio (p0,p1, …,p5) y se revisa el commit de ese tag. - Cada entrega parte de la anterior. El punto de partida de P1 es su propio P0, y así hasta P5: no se publica una solución intermedia.
- Todo corre dentro del contenedor del curso (
env/run.sh), con los servicios que trae. No se agregan dependencias de npm ni servicios nuevos: lo que el curso quiere ver es la arquitectura, y las piezas del contenedor alcanzan para todas las entregas. - La interfaz HTTP de Tinkuy (rutas, cuerpos y códigos de estado del README) no cambia salvo donde un enunciado lo pide. Las pruebas públicas entran por ahí.
- Identificadores en inglés y comentarios en español, según la guía de estilo.
Qué lleva cada entrega
Además del código, en el repositorio del equipo:
| Archivo | Contenido |
|---|---|
docs/adr/NNNN-titulo.md |
Un ADR por decisión de arquitectura de la entrega, con el formato de la semana 7: contexto (con el escenario), alternativas consideradas, decisión, estado y consecuencias. Los ADR anteriores no se reescriben: si una decisión cambia, se escribe otro que lo reemplaza. |
docs/c4/context.md, docs/c4/containers.md |
Los diagramas C4 al día. Desde P1, también docs/c4/components.md. |
docs/measurements/pN.md |
Las mediciones de la entrega: antes y después, con la máquina en que se midió, el comando y el resumen de k6 tal como salió. |
docs/scenarios.md |
Los escenarios de calidad del sistema, que crecen con cada entrega. |
Cómo se comprueba
Cada enunciado trae un Makefile con el objetivo check, que se corre dentro
del contenedor, en el repositorio del equipo:
./env/run.sh # desde la carpeta del curso
cd /work/tinkuy-equipo # el repositorio del equipo, clonado dentro de la carpeta del curso
make -f /work/projects/p2-apertura-de-ventas/Makefile check
check hace tres cosas:
- Lo de siempre:
make typecheck,make testy, desde P1,make deps. - Las pruebas públicas de la entrega: levantan el sistema del equipo y lo ejercitan desde afuera, por HTTP. Según la entrega, lanzan compras concurrentes, corren k6 con umbrales, matan un servicio o le agregan latencia a la pasarela con Toxiproxy, y revisan el estado final en la base de datos.
- Los documentos: que existan los archivos pedidos y tengan las secciones pedidas. Que una decisión esté bien justificada no lo puede juzgar un programa: eso lo revisa el docente.
El check de cada entrega corre también las pruebas públicas de todas las
anteriores.
Los umbrales de latencia están calibrados para una laptop corriente dentro del
contenedor, con margen. Si su máquina es mucho más lenta, corran
make -f … calibrate, que mide una operación de referencia y ajusta los
umbrales en proporción; el factor que se usó queda escrito en la salida, y se
copia en docs/measurements/pN.md. El factor se guarda dentro del contenedor,
así que hay que volver a calibrar en un contenedor nuevo, o fijarlo con la
variable TINKUY_FACTOR.
Tres cosas prácticas sobre check: borra y vuelve a crear la base de datos
tinkuy (no guarden ahí nada que quieran conservar); levanta su sistema en
los puertos 3100 y 4100, así que no choca con un make start que tengan
abierto, y no se pueden correr dos check a la vez en el mismo contenedor.
Con SEED=n se repite con otros datos. Desde P3 hace más: crea y destruye la
réplica de PostgreSQL, mata y vuelve a levantar Redis, NATS y los procesos del
equipo, usa también los puertos 3101 y 4101 y, desde P4, borra y crea la base
de datos tinkuy_payments. Córranlo en un contenedor donde no tengan otro
trabajo a medias.
Las pruebas públicas se repiten en la revisión con otra semilla para los datos. Un sistema que pasa las públicas porque conoce los datos de ejemplo no pasa la revisión.
Mediciones honestas
Las mediciones se entregan tal como salieron. Un resultado que no alcanza el umbral, con su explicación, vale más que uno retocado. Si una decisión no mejoró lo que esperaban, se dice en el ADR: es información, y casi siempre es lo más interesante de la entrega.
Defensa oral
Puede haber una defensa oral breve durante el laboratorio: cualquier integrante debe poder explicar cualquier decisión del equipo, qué alternativas se descartaron y cómo se comprobó. La de la semana 16 recorre todo el proyecto (guía de la semana 16).