🧪 Problem-Driven Systems Lab

Portafolio técnico orientado a problemas reales de software: rendimiento, observabilidad, resiliencia, arquitectura y continuidad operacional. Este repositorio forma parte del ecosistema público de Vladimir Acuña y traduce esa narrativa en escenarios ejecutables, documentados y honestos sobre su madurez real.

🎯 Executive Summary

• El laboratorio modela 12 problemas reales de ingeniería, utilizando fallos de alta fidelidad inyectados (I/O, Memoria, Excepciones) en lugar de simulaciones abstractas.
• Los casos 01 al 12 son piezas de ingeniería operativa en PHP que incluyen una Interfaz Gráfica (UI) nativa y moderna para diagnósticos visuales.
• Implementa patrones profesionales (Adapter, Strangler, Circuit Breaker) resolviendo cuellos de botella reales en el runtime de PHP.
• Docker es la vía oficial de ejecución limpia y reproducible.
• shared/catalog/cases.json es la fuente de verdad del portal, de la documentacion generada y de la narrativa operativa.
• El portal raiz ahora sirve como hub de evaluacion: rutas por audiencia, seleccion por lenguaje, proof cards y probes server-side.

💻 Interfaz Visual Integrada

El laboratorio no es solo una "API JSON ciega". Los 12 casos en PHP ahora interceptan solicitudes HTTP de navegadores (mediante cabeceras Accept) y devuelven Dashboards Interactivos. Esto permite a reclutadores, líderes y desarrolladores ver cómo se bloquea una base de datos, cómo aumentan las latencias, y probar escenarios en vivo usando estéticas modernas sin afectar el núcleo programático.

💡 Que demuestra este producto

Area	Evidencia concreta
Diagnostico tecnico	Cada caso parte desde sintomas, causas, trade-offs y solucion esperada
Ejecucion reproducible	Cada stack mantiene Dockerfile y compose.yml propios
Operacion realista	Los casos operativos no son demos vacias: usan DB, worker, metricas, logs o trazas segun corresponda
Claridad para audiencias mixtas	El portal y la documentacion separan rutas para recruiter, liderazgo tecnico, developer y beginner
Honestidad tecnica	Se distingue explicitamente entre OPERATIVO y DOCUMENTADO / SCAFFOLD

🧭 Como evaluarlo rapido

Perfil	Punto de entrada	Que deberia poder concluir
Recruiter / hiring manager	RECRUITER.md	El repo deja evidencia real y no solo una narrativa bonita
CTO / Head of Engineering	ARCHITECTURE.md	Hay criterio sistemico, foco en operacion y reduccion de riesgo
Developer / DevOps	INSTALL.md → RUNBOOK.md	El entorno levanta limpio y los casos operativos cuentan una historia tecnica verificable
Beginner	docs/BEGINNERS_GUIDE.md	La estructura y la taxonomia de madurez son comprensibles antes de entrar al codigo

Si quieres una sola puerta de entrada local con los 12 casos PHP disponibles, levanta docker compose -f compose.root.yml up -d --build y abre http://localhost:8080.

🏷️ Madurez actual

Nivel	Significado
OPERATIVO	Caso resolviendo el problema de forma real, con Docker y evidencia observable
DOCUMENTADO / SCAFFOLD	Caso bien modelado, con estructura y docs listas, pero sin la misma profundidad funcional todavia
PLANIFICADO	Futuro del roadmap, aun no presente en el arbol actual

Estado actual:

• OPERATIVO: casos 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11 y 12 en PHP.
• OPERATIVO adicional fuera de PHP: caso 03 en Node.js y Python.
• DOCUMENTADO / SCAFFOLD: stacks todavia no profundizados fuera de las variantes ya operativas y la estructura base de los otros runtimes.

🔎 Catálogo de Casos Resolutivos

Caso	Análisis Técnico (PHP)	Resumen del Problema	Que deja como prueba
01 - API lenta bajo carga	👉 Senior Analysis	OPERATIVO	Latencia legacy vs optimized, contencion real sobre DB y métricas Grafana
02 - N+1 y cuellos de botella DB	👉 Senior Analysis	OPERATIVO	N+1 reproducible, costo por request medido y lectura consolidada
03 - Observabilidad deficiente	👉 Senior Analysis	OPERATIVO	Diferencia clara entre logs pobres y telemetría útil
04 - Timeout chain y retry storms	👉 Senior Analysis	OPERATIVO	Comparación entre retries agresivos y resiliencia con circuit breaker
05 - Presion de memoria y fugas	👉 Senior Analysis	OPERATIVO	Degradación progresiva por estado retenido frente a limpieza de recursos
06 - Pipeline roto y delivery fragil	👉 Senior Analysis	OPERATIVO	Diferencia entre detectar tarde y bloquear en preflight/rollback
07 - Modernización del Monolito	👉 Senior Analysis	OPERATIVO	Refactorización incremental mediante patrón strangler fig
08 - Extracción Crítica Módulo	👉 Senior Analysis	OPERATIVO	Extracción big bang vs extract-and-proxy con cutover gradual
09 - Integración Externa Inestable	👉 Senior Analysis	OPERATIVO	Aislamiento mediante patrón adapter y validación estricta
10 - Arquitectura Sobre-Dimensionada	👉 Senior Analysis	OPERATIVO	Comparación de diseño complejo vs simplificado con costo visible
11 - Reportes Pesando la Operación	👉 Senior Analysis	OPERATIVO	Impacto de read/write locks bloqueantes mitigado por aislamiento
12 - Single Point of Knowledge	👉 Senior Analysis	OPERATIVO	Riesgo operacional y bus factor mitigado por Playbooks integrados

El catalogo completo detallado se genera desde metadatos automatizados y vive en docs/case-catalog.md. Cada caso se sirve mediante un robusto servidor en PHP listo para consumir tanto por UI Web como por API.

🖥️ Portal y experiencia de producto

La raiz del laboratorio ya no es solo una lista de archivos. El portal local ahora cumple cuatro funciones:

• explica el producto por audiencia;
• deja elegir lenguaje y ver solo casos realmente operativos;
• muestra por que importa cada caso y que evidencia deberia verse;
• ejecuta probes server-side para devolver status code, latencia y ultima verificacion real desde el propio portal.

Esto lo vuelve mucho mas claro para reclutadores, lideres y personas que quieren corroborar rapido si el producto esta vivo y por que importa.

🚀 Inicio rapido

# Laboratorio completo en PHP + portal

docker compose -f compose.root.yml up -d --build

# Portal liviano solamente

docker compose -f compose.portal.yml up -d --build

# Casos aislados si quieres revisar uno por uno

docker compose -f cases/01-api-latency-under-load/php/compose.yml up -d --build
docker compose -f cases/02-n-plus-one-and-db-bottlenecks/php/compose.yml up -d --build
docker compose -f cases/03-poor-observability-and-useless-logs/php/compose.yml up -d --build
docker compose -f cases/04-timeout-chain-and-retry-storms/php/compose.yml up -d --build
docker compose -f cases/05-memory-pressure-and-resource-leaks/php/compose.yml up -d --build
docker compose -f cases/06-broken-pipeline-and-fragile-delivery/php/compose.yml up -d --build
docker compose -f cases/07-incremental-monolith-modernization/php/compose.yml up -d --build
docker compose -f cases/08-critical-module-extraction-without-breaking-operations/php/compose.yml up -d --build
docker compose -f cases/09-unstable-external-integration/php/compose.yml up -d --build
docker compose -f cases/10-expensive-architecture-for-simple-needs/php/compose.yml up -d --build
docker compose -f cases/11-heavy-reporting-blocks-operations/php/compose.yml up -d --build
docker compose -f cases/12-single-point-of-knowledge-and-operational-risk/php/compose.yml up -d --build
docker compose -f cases/03-poor-observability-and-useless-logs/node/compose.yml up -d --build
docker compose -f cases/03-poor-observability-and-useless-logs/python/compose.yml up -d --build

Tambien existen atajos con make, pero la ruta soportada y mas portable sigue siendo docker compose directo.

📚 Documentacion del repositorio

Documento	Rol
RECRUITER.md	Ruta ejecutiva para evaluacion rapida
ARCHITECTURE.md	Vista ejecutiva de la arquitectura actual
INSTALL.md	Instalacion y puesta en marcha recomendada
RUNBOOK.md	Operacion diaria y chequeos iniciales
SECURITY.md	Politica de seguridad y reporte responsable
SUPPORT.md	Como pedir ayuda y que informacion incluir
CONTRIBUTING.md	Reglas para crecer el laboratorio sin degradarlo
CHANGELOG.md	Historial notable de cambios
docs/architecture.md	Mapa estructural del repositorio
docs/case-catalog.md	Catalogo sincronizado desde metadatos
docs/docker-strategy.md	Por que Docker es el modelo operativo oficial
docs/recruiter-guide.md	Guia extendida para lectores no tecnicos

🏗️ Arquitectura en una frase

El sistema se organiza como una capa editorial en raiz, un portal de evaluacion con entrada completa PHP o modo liviano, una biblioteca de casos problem-driven y stacks aislados por Docker. La arquitectura completa esta documentada en ARCHITECTURE.md y docs/architecture.md.

🌐 Ecosistema relacionado

• Web profesional: vladimiracunadev-create.github.io
• Perfil GitHub: github.com/vladimiracunadev-create
• Grupo GitLab: gitlab.com/vladimir.acuna.dev-group/vladimir.acuna.dev-group

✅ Lo que este repo si es

• Un laboratorio serio para demostrar criterio tecnico transferible.
• Una base reproducible para conversar de rendimiento, observabilidad y arquitectura.
• Un portfolio documentado que privilegia problemas reales sobre features aisladas.

🚫 Lo que este repo no vende

• Paridad funcional completa en todos los stacks desde la primera iteracion.
• Benchmarks absolutos entre lenguajes.
• Paridad profunda de los doce casos en todos los stacks hoy.
• Seniority inflada con claims sin evidencia.

⚖️ Licencia

El repositorio se publica bajo MIT. Revisa tambien docs/usage-and-scope.md para entender sus limites de uso y la postura honesta del proyecto.