Documentación

Introducción

Esta sección reúne la documentación de ingeniería del proyecto dev-portfolio (codebymike.tech): requerimientos, casos de uso, diagramas UML y el tablero kanban del propio proyecto. Todo el contenido vive como datos tipados en src/data/documentacion.ts y src/data/iteraciones-portfolio.ts - un cambio de requerimiento es un commit revisable, no un documento que se desincroniza del código.

Ir a la presentación

Deck de sustentación con el resumen de esta documentación. Requiere iniciar sesión.

Propósito

El propósito de esta documentación es dejar trazabilidad formal del ciclo de vida del proyecto - desde el requerimiento hasta la historia de usuario y su estado en el kanban - usando un formato reconocido de ingeniería de software (requerimientos funcionales y no funcionales, casos de uso con flujo extendido, diagramas UML de secuencia, comunicación, actividades, componentes, despliegue, paquetes, clases y objetos, la topología de red por zonas de confianza, más los procesos de negocio en BPMN). Sirve como evidencia para sustentación académica y como referencia técnica real para el mantenimiento del sistema en producción.

Mapa de la documentación

Requerimientos funcionales

81 requerimientos en 7 módulos (80 implementados).

Requerimientos no funcionales

28 requerimientos por categoría ISO/IEC 25010.

Roles y niveles de autoridad

Los 3 niveles de decisión: qué aprueba cada uno, qué no puede hacer aunque tenga el acceso, y dónde vive esa frontera en el código.

Matriz RACI

12 actividades críticas repartidas sobre esos tres niveles, con la regla de un solo aprobador verificada en CI.

Casos de uso

6 actores, 19 casos de uso con diagrama.

Casos de uso extendidos

Flujo principal, alternos, excepciones y postcondiciones de los CU críticos.

Historias de usuario

114 historias en formato XP, agrupadas por actor, con su DoD.

Diagramas BPMN

Los 4 procesos de negocio con carriles por participante: cobro de campo, acceso al portal, respuesta de seguridad y ciclo de monitoreo.

Diagrama de secuencia

Diagrama de comunicación

Las 4 mismas interacciones de la secuencia, vistas por su estructura de enlaces y con numeración decimal.

Diagrama de actividades

3 flujos de control internos con particiones, bifurcación concurrente y bucle de reintento: middleware, pipeline con rollback y webhook de pago.

Diagrama de componentes

10 componentes con sus interfaces provistas y requeridas (bola y enchufe).

Diagrama de despliegue

Qué corre dónde, en notación UML: nodos, artefactos desplegados y caminos de comunicación con su protocolo.

Diagrama de red

Las 5 zonas de confianza y los 15 flujos entre ellas, cada cruce de frontera con su puerto y los controles que atraviesa.

Diagrama de paquetes

Cómo se agrupa el código y en qué dirección se permiten las dependencias entre capas.

Diagrama de clases

Entidades del dominio derivadas de src/db/schema.ts, agrupadas por módulo.

Diagrama de objetos

Instantáneas concretas: proyecto con sus servicios, pago con evento duplicado, IP bloqueada.

Tablero kanban

114 historias en 41 iteraciones del propio proyecto.

Testing

Guía interactiva de los 15 niveles de prueba y del pipeline completo, con simulación de una corrida.

Ejecución de pruebas

Evidencia de la última corrida: 1200 pruebas en 70 archivos con el tiempo medido de cada una, generada desde el reporte JUnit.

Reportes de pruebas

Los 7 formatos de log que emite el runner, con la salida real de cada uno, la anatomía de un fallo y la equivalencia con Surefire y JaCoCo.

Docker

8 conceptos, 7 piezas de la configuración y 7 preguntas probables: por qué se contenerizan el entorno y las pruebas, y no el despliegue.

Pipeline en vivo

Log en tiempo real del pipeline y mapa de componentes, con datos reales de GitHub Actions cuando hay una corrida activa.

Verificación y validación

Los mismos niveles de prueba, reclasificados bajo el marco IEEE 1012: ¿lo construimos bien o construimos lo correcto?

Usability testing

Metodología de validación con usuarios en 6 pasos, aplicada a un flujo real.

Stack técnico

Framework

Astro 7 (SSR, adapter Vercel)
Tailwind CSS 4

Datos

Drizzle ORM
libSQL / Turso

Auth

Auth.js (auth-astro)
Proveedor GitHub OAuth

Almacenamiento

Vercel Blob (backups, screenshots)

Observabilidad

Cron externo (cron-job.org)
ntfy.sh (push)
Web Vitals (RUM)

Testing

Vitest + coverage v8
Playwright (e2e)
Stryker (mutación)
CodeQL + axe-core

Entorno

Docker + Compose (devcontainer)
libSQL server en contenedor (pruebas)

Alcance del proyecto

Dentro de alcance: sitio público de portafolio, CRM interno (proyectos/clientes/seguimiento/briefings), finanzas y P&L por proyecto, observabilidad (monitoreo, SLO, notificaciones), un LAB de ingeniería (CI/CD con rollback, pagos idempotentes, chaos engineering) y un micro-SIEM propio (sensor, blocklist, rate limiting durable, detección de anomalías).

Fuera de alcance (por ahora): multiusuario/roles (el panel es de un único administrador), pasarela de pagos en producción real (el LAB usa un proveedor mock además de Wompi), y pruebas de carga automatizadas (k6, Fase 5 del plan del LAB; el resto de niveles de prueba, incluidos SAST y mutation testing, ya están operando, ver Testing).