# Documento de Arquitectura
## Plataforma de Diseño, Mapeo y Cuantificación de Procesos de Negocio

> **Mantra**: *Los procesos de negocio son activos estratégicos de las empresas y un diferencial competitivo.*

| Atributo | Valor |
|---|---|
| Versión del documento | 0.2.0 |
| Fecha | Mayo 2026 |
| Estado | Fase 0 completada · Sprint 1 (ROI) en construcción |
| Autor | Equipo fundador + Claude (arquitectura) |
| Alcance | MVP completado + Sprint 1 + Norte V1.0 (12–18 meses) |
| Deploy actual | https://process-cost-platform.pages.dev (v0.1.0-mvp) |

---

## Tabla de Contenidos

1. [Contexto y Propuesta de Valor](#1-contexto-y-propuesta-de-valor)
2. [Glosario y Convenciones](#2-glosario-y-convenciones)
3. [Norte Estratégico — Visión V1.0](#3-norte-estratégico--visión-v10)
4. [Fase 0 — MVP "Noche Cero" (COMPLETADO)](#4-fase-0--mvp-noche-cero)
5. [Fase 1 — Sprint 1: ROI y Escenarios de Automatización](#5-fase-1--sprint-1-roi-y-escenarios-de-automatización)
6. [Roadmap de Evolución](#6-roadmap-de-evolución)
7. [Arquitectura Técnica](#7-arquitectura-técnica)
8. [Modelo de Dominio](#8-modelo-de-dominio)
9. [Decisiones Arquitectónicas (ADRs)](#9-decisiones-arquitectónicas-adrs)
10. [Atributos de Calidad](#10-atributos-de-calidad)
11. [Riesgos y Mitigaciones](#11-riesgos-y-mitigaciones)
12. [Anexos](#12-anexos)

---

## 1. Contexto y Propuesta de Valor

### 1.1 Problema que resolvemos

Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa carecen de una herramienta accesible que les permita **cuantificar de forma objetiva, visual y comunicable el costo operativo real de un proceso de negocio**. Las alternativas actuales son:

- **Caras y corporativas** (Bizagi, Signavio, ARIS, Interact Process Manager): pensadas para grandes corporaciones, distantes de la realidad LATAM.
- **Genéricas** (Visio, draw.io, Lucidchart): dibujan procesos pero no los cuantifican.
- **Manuales** (Excel + Word + correo): no escalan, no son colaborativas, no son visuales.

### 1.2 Promesa de valor única (UVP)

> **Permitir a cualquier consultor o gerente de procesos navegar el resultado de la simulación de un proceso BPMN y entender visualmente, actividad por actividad, cómo se componen sus costos operativos y dónde están las oportunidades de mejora.**

### 1.3 Diferenciadores estratégicos

| Diferenciador | Cómo se materializa |
|---|---|
| **Cercanía LATAM** | Construido desde Paraguay, soporte en español LATAM, portugués BR e inglés, precio accesible |
| **Democratización del costeo operativo** | No solo medianas/grandes empresas: cualquier consultor independiente o pyme puede usarlo |
| **Visualización deslumbrante** | El mapa de calor sobre el BPMN y el reporte interactivo son el corazón del producto, no un anexo |
| **Educativa por diseño** | Glosario integrado, validador pedagógico, tutoriales in-app, plantillas comunitarias |
| **Forward-compatible con IA/RPA/Agentes** | El modelo de datos contempla nodos no-BPMN-estándar para representar bots RPA y agentes IA |

### 1.4 Audiencia objetivo

**MVP (Fase 0 - COMPLETADO)**: el propio fundador como consultor de automatización de procesos.

**Sprint 1 (en curso)**: el **equipo de InQuality** como herramienta interna de consultoría y **pre-venta de proyectos de automatización con cálculo de ROI**.

**V1.0**: consultores independientes y boutique de procesos, gerentes de operaciones de pymes LATAM, equipos de Project/Process Office.

**V2+**: estudiantes y entusiastas de eficiencia operativa (tier educativo gratuito).

### 1.4.1 Casos de uso confirmados (Sprint 1)

1. **Análisis de costos operativos**: el consultor de InQuality releva el proceso del cliente, lo modela en BPMN, configura costos/tiempos/recursos y entrega un reporte cuantitativo del costo operativo.

2. **Pre-venta de automatización con ROI**: el consultor identifica actividades automatizables, define costos automatizados estimados y el costo de inversión del proyecto. El sistema calcula payback, ahorro anual y ROI %, generando un reporte ejecutivo que sirve como propuesta comercial cuantificada.

### 1.5 Lo que NO somos

- ❌ NO somos un BPMS (motor de ejecución de procesos).
- ❌ NO generamos código fuente para automatización (eso lo hace Claude Code u otro generador).
- ❌ NO competimos contra Camunda, Bonita, ni motores de orquestación.
- ❌ NO somos un editor BPMN general — usamos uno embebido (bpmn-js) pero nuestro valor está en el costeo y la simulación.

---

## 2. Glosario y Convenciones

| Término | Definición |
|---|---|
| **BPMN 2.0** | Business Process Model and Notation, estándar OMG para modelado de procesos |
| **Actividad** | Nodo BPMN tipo `Task` o `SubProcess` con trabajo asociado |
| **Costo directo** | Costo imputable a la ejecución de la actividad (recursos humanos, sistemas, insumos) |
| **Costo indirecto** | Costo asignado por overhead (estructura, espacio, indirectos prorrateados) |
| **Simulación** | Cálculo agregado del costo esperado de un proceso dadas las configuraciones de sus actividades |
| **Mapa de calor** | Visualización donde cada nodo BPMN se colorea según métrica de costo |
| **Tenant** | Organización/cliente lógicamente aislado en el SaaS (post-MVP) |
| **CRDT** | Conflict-free Replicated Data Type — estructura de datos para colaboración sin conflictos |
| **ABC** | Activity-Based Costing — costeo basado en actividades |

**Convenciones del documento**:

- 🔴 **MVP** = aplica a Fase 0 (esta noche)
- 🟡 **V1.0** = aplica al norte estratégico
- 🔵 **V2+** = futuro lejano

---

## 3. Norte Estratégico — Visión V1.0

### 3.1 Capacidades funcionales objetivo (V1.0)

```
┌──────────────────────────────────────────────────────────────────┐
│                     PLATAFORMA V1.0                              │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  📐 DISEÑO BPMN                                                  │
│  ├─ Editor BPMN 2.0 completo (basado en bpmn-js extendido)       │
│  ├─ Paleta extendida: elementos RPA + Agentes IA                 │
│  ├─ Validador pedagógico en tiempo real                          │
│  ├─ Glosario BPMN integrado                                      │
│  └─ Importación/exportación BPMN 2.0 XML estándar                │
│                                                                  │
│  🤝 COLABORACIÓN                                                 │
│  ├─ Edición en tiempo real (hasta 5 usuarios concurrentes)       │
│  ├─ CRDT-based, sin conflictos                                   │
│  ├─ Presencia (cursores, selección, avatares)                    │
│  └─ Versionado lineal (snapshots manuales y automáticos)         │
│                                                                  │
│  🏢 ESTRUCTURA ORGANIZACIONAL                                    │
│  ├─ Jerarquía configurable hasta 10 niveles                      │
│  ├─ Nombres de niveles configurables por tenant                  │
│  ├─ Procesos cross-area con gobernanza RACI                      │
│  └─ Process owners, SLAs entre áreas                             │
│                                                                  │
│  💰 COSTEO Y SIMULACIÓN                                          │
│  ├─ Costeo dual: ABC (Activity-Based) + por hora-recurso         │
│  ├─ Tiempos como distribuciones de probabilidad                  │
│  ├─ Recursos: roles, personas, sistemas, equipamiento, insumos   │
│  ├─ Riesgos cualitativos (matriz alto/medio/bajo)                │
│  └─ Cálculo agregado de costos esperados                         │
│                                                                  │
│  📊 VISUALIZACIÓN Y REPORTES                                     │
│  ├─ Mapa de calor configurable (absoluto / relativo / desviación)│
│  ├─ Drill-down interactivo por actividad                         │
│  ├─ Reportes exportables (PDF, PNG, CSV, Excel)                  │
│  └─ Narrativa visual del costo end-to-end                        │
│                                                                  │
│  🧠 INTELIGENCIA ARTIFICIAL                                      │
│  └─ Detección automática de cuellos de botella e ineficiencias   │
│                                                                  │
│  🎓 EDUCACIÓN Y COMUNIDAD                                        │
│  ├─ Tutoriales interactivos in-app                               │
│  ├─ Plantillas de procesos publicadas por la comunidad           │
│  └─ Validador BPMN con explicaciones pedagógicas                 │
│                                                                  │
│  🌐 PLATAFORMA                                                   │
│  ├─ SaaS multi-tenant                                            │
│  ├─ PWA (instalable, offline-capable)                            │
│  ├─ i18n: es-LATAM, en, pt-BR                                    │
│  ├─ Auth RBAC                                                    │
│  └─ Freemium + suscripción por usuario                           │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

### 3.2 Atributos de calidad objetivo (V1.0)

| Atributo | Objetivo |
|---|---|
| Disponibilidad | 99% (no SLA crítico al inicio) |
| Tiempo de carga inicial | < 3s en 3G |
| Concurrencia editorial | 5 usuarios por diagrama, latencia < 200ms |
| Tamaño máximo diagrama | 200 nodos sin degradación |
| Mantenibilidad | Stack monolítico modular, contratable en LATAM |
| Soberanía de datos | Self-hostable en cualquier VPS estándar |

---

## 4. Fase 0 — MVP "Noche Cero" ✅ COMPLETADA

> **Estado**: ✅ Entregada el 13 de mayo de 2026. Tag `v0.1.0-mvp`. Deployada en https://process-cost-platform.pages.dev. **268 tests unit/integration + 5 E2E + 4/4 validación con gradiente real**. Bundle inicial 59.75 KB gzip. 0 vulnerabilidades.

### 4.1 Hipótesis validada

> Un consultor de procesos puede transformar un archivo `.bpmn` en un reporte visualmente deslumbrante de costos operativos en menos de 15 minutos, y usarlo al día siguiente en una reunión real con un cliente.

### 4.2 Alcance del MVP (estricto)

| # | Capacidad | Detalle |
|---|---|---|
| F1 | **Importar BPMN** | Drag & drop de archivo `.bpmn` 2.0 XML estándar |
| F2 | **Visualizar diagrama** | Canvas read-only con bpmn-js, navegable (zoom, pan) |
| F3 | **Editar atributos de actividad** | Panel lateral al seleccionar nodo: costo, tiempo, recursos asignados |
| F4 | **Definir recursos** | CRUD simple de recursos con costo/hora (roles, sistemas, insumos) |
| F5 | **Simular** | Cálculo agregado determinístico de costo total y por actividad |
| F6 | **Mapa de calor** | Coloreo de nodos sobre el canvas según costo relativo |
| F7 | **Reporte visual interactivo** | Dashboard con: total, ranking de actividades costosas, gráficos, drill-down |
| F8 | **Exportar reporte** | PDF + CSV |
| F9 | **Persistencia local** | IndexedDB: el trabajo del consultor se conserva entre sesiones del navegador |

### 4.3 Fuera de alcance del MVP

❌ Login/registro · ❌ Multi-tenant · ❌ Colaboración · ❌ Versionado · ❌ Edición del diagrama BPMN (solo lectura del XML importado) · ❌ Distribuciones de probabilidad (costos y tiempos fijos) · ❌ Riesgos · ❌ Gobernanza/RACI · ❌ Jerarquía organizacional · ❌ IA · ❌ Elementos RPA/Agente custom · ❌ Tutoriales · ❌ Marketplace · ❌ Backend · ❌ i18n (solo español inicialmente) · ❌ PWA installable (solo SPA web)

### 4.4 Criterios de éxito del MVP

✅ El consultor puede importar un BPMN real, configurarlo y obtener reporte en < 15 minutos
✅ El reporte tiene calidad visual presentable ante un cliente sin retoques
✅ La aplicación corre 100% en el navegador, sin backend
✅ El export PDF se ve profesional (logo, paleta, tipografía, layout)
✅ El mapa de calor es inmediatamente comprensible para alguien sin formación BPMN

### 4.5 Diseño del flujo de usuario del MVP

```
┌────────────────────────────────────────────────────────────────────┐
│                        FLUJO MVP "NOCHE CERO"                      │
└────────────────────────────────────────────────────────────────────┘

    [1. Landing]
        │
        │ "Importar mi proceso"
        ▼
    [2. Drop zone .bpmn] ─────────► IndexedDB
        │
        ▼
    [3. Workspace de configuración]
        ├─ Canvas BPMN (read-only, navegable, bpmn-js)
        ├─ Panel lateral derecho:
        │   ├─ Tab "Atributos de actividad" (al seleccionar nodo)
        │   │   ├─ Costo directo
        │   │   ├─ Tiempo de ejecución (minutos)
        │   │   ├─ Recursos asignados (multi-select)
        │   │   └─ Probabilidad de ocurrencia (para gateways)
        │   ├─ Tab "Recursos" (CRUD global)
        │   │   ├─ Nombre, tipo (rol/sistema/insumo/equipo), costo/hora
        │   └─ Tab "Configuración global"
        │       ├─ Moneda
        │       ├─ Overhead % (costos indirectos)
        │       └─ Nombre del proceso, cliente
        │
        │ Botón "Simular"
        ▼
    [4. Pantalla de Reporte]
        ├─ Header: nombre proceso, cliente, fecha, costo total
        ├─ Mapa de calor sobre el diagrama (gradiente verde→rojo)
        ├─ KPIs: costo total, costo/instancia, tiempo total, # actividades
        ├─ Tabla: top 10 actividades más costosas (interactivo)
        ├─ Gráfico de barras: costo por actividad
        ├─ Gráfico donut: composición costo directo/indirecto
        ├─ Gráfico de barras: costo por tipo de recurso
        └─ Botones: "Exportar PDF" | "Exportar CSV" | "Volver a editar"
```

### 4.6 Decisiones de diseño visual (MVP)

| Aspecto | Decisión |
|---|---|
| Tipografía | Inter (UI) + JetBrains Mono (datos numéricos) |
| Paleta principal | Neutros oscuros sobre claros (light mode primero) |
| Paleta de heatmap | Verde (#10b981) → Amarillo (#f59e0b) → Rojo (#ef4444) |
| Componentes | shadcn/ui sobre Tailwind |
| Iconografía | Lucide |
| Densidad | Media-alta (consultor profesional, no consumidor) |
| Modo oscuro | Postergado para post-MVP |

### 4.7 Recomendación sobre el mapa de calor (decisión solicitada)

**Decisión arquitectónica**: el heatmap será **configurable con 3 modos**, default **costo relativo**.

| Modo | Cuándo se usa | Cómo colorea |
|---|---|---|
| **Costo relativo (%)** ← default | Análisis interno, identificar el 20% que cuesta el 80% | Cada nodo coloreado por su % sobre el total del proceso |
| **Costo absoluto** | Comparar entre procesos del mismo cliente | Escala global definida por el rango min-max del proceso |
| **Desviación vs benchmark** | Consultoría comparativa | Requiere benchmark del usuario; pospuesto a V1.0 si no hay tiempo esta noche |

**Justificación**: el modo relativo es el más útil para "comunicar dónde duele", que es el caso de uso del consultor. El absoluto se entrega gratis con el mismo cálculo. El de benchmark es valioso pero requiere base de datos comparativa que no tendremos esta noche.

---

## 5. Fase 1 — Sprint 1: ROI y Escenarios de Automatización

> **Estado**: en construcción.
> **Audiencia primaria**: equipo de InQuality (consultora de procesos).
> **Caso de uso estrella**: pre-venta de proyectos de automatización con ROI cuantificado.

### 5.1 Hipótesis a validar

> Un consultor de InQuality puede modelar un proceso, identificar las actividades automatizables, configurar costos del escenario actual vs automatizado, y obtener en minutos un reporte ejecutivo de ROI (payback, ahorro anual, ROI %) que sirve como propuesta comercial cuantificada para vender un proyecto de automatización.

### 5.2 Alcance del Sprint 1

| # | Capacidad | Detalle |
|---|---|---|
| S1.1 | **Volumetría del proceso** | Frecuencia anual de ejecución + horizonte de análisis (años) configurables por proceso |
| S1.2 | **Marcado de actividades automatizables** | Toggle por actividad + campos de costo y tiempo automatizados |
| S1.3 | **Inversión en automatización** | Campo único agregado a nivel proceso (sin desglose) |
| S1.4 | **Motor dual de simulación** | Mismo motor recibe `scenario: 'actual' \| 'automated'` y aplica los campos correspondientes |
| S1.5 | **Sección de ROI en reporte** | Tabs en el reporte: Actual / Automatizado / Comparación + ROI |
| S1.6 | **5 KPIs de ROI** | Ahorro por ejecución · Ahorro anual · Payback (meses) · Ahorro acumulado a N años · ROI % anualizado |
| S1.7 | **Tabla comparativa** | Actividad por actividad: costos actual vs automatizado, ahorro $ y % |
| S1.8 | **Gráficos de ROI** | Ahorro acumulado en el tiempo + Top 5 actividades con mayor ahorro |
| S1.9 | **Mecanismo de transparencia** | Detecta valores cero/inversión cero y los expone en sección visible pero discreta |
| S1.10 | **Migración Dexie v1 → v2** | Preserva datos existentes, agrega los nuevos campos con defaults |
| S1.11 | **Export PDF/CSV ampliado** | El PDF incluye páginas de ROI; el CSV de ROI exporta comparación completa |
| S1.12 | **Documento metodológico** | Anexo en el repo: cómo calcular correctamente el costo automatizado por ejecución |

### 5.3 Decisiones arquitectónicas del Sprint 1

#### Modelo de escenarios — Modelo A (dos campos por actividad)

`Activity` gana 3 campos:
- `automatable: boolean` (default false)
- `automatedCostFixed: number` (default 0)
- `automatedTimeMinutes: number` (default 0)

`Process` gana 3 campos:
- `annualFrequency: number` (default 1000)
- `analysisHorizonYears: number` (default 3)
- `automationInvestment: number` (default 0)

**Justificación de Modelo A**:
- Trazabilidad actividad-por-actividad sin sincronización entre diagramas
- Un solo BPMN simplifica el flujo del consultor
- Migración a Modelo B (escenarios como entidad) queda pendiente para Sprint 3-4 si InQuality lo demanda

#### Volumetría — Multiplicador en el reporte

El motor sigue siendo determinístico ("costo de una ejecución"). La volumetría se aplica en el reporte:
```
costoAnual = costoUnitario × annualFrequency
costoHorizonte = costoAnual × analysisHorizonYears
```

No se introduce VPN, TIR ni Monte Carlo en este sprint. **Razón estratégica**: el cliente promedio de InQuality entiende payback nominal; el VPN abre discusiones sobre la tasa que distraen.

#### Fórmulas de ROI (en `domain/roi.ts`, función pura testeable)

```typescript
savingsPerExecution = costPerExecutionActual - costPerExecutionAutomated
savingsPerExecutionPercent = (savingsPerExecution / costPerExecutionActual) * 100
annualSavings = savingsPerExecution × annualFrequency
paybackMonths = (automationInvestment / annualSavings) × 12
paybackYears = paybackMonths / 12
cumulativeSavingsHorizon = (annualSavings × horizonYears) - automationInvestment
breaksEvenInHorizon = paybackYears <= horizonYears
roiAnnualPercent = (annualSavings / automationInvestment) * 100
```

**Edge cases manejados explícitamente**:
- `annualSavings <= 0`: `paybackMonths = Infinity`, `breaksEvenInHorizon = false`
- `automationInvestment === 0 && annualSavings > 0`: `paybackMonths = 0`, `roiAnnualPercent = Infinity` (display "N/A" o "∞")
- `costPerExecutionActual === 0`: `savingsPerExecutionPercent = 0` (evitar div/0)

#### Transparencia metodológica

Si el reporte detecta:
- Actividades marcadas como automatizables pero con `automatedCostFixed = 0` Y `automatedTimeMinutes = 0`
- `automationInvestment = 0` con payback < 1 mes
- Otros valores sospechosos

Muestra una sección **"Transparencia metodológica"** con:
- Lista de valores no informados
- Texto introductorio explicando el motivo del listado
- Fondo gris claro, no rojo/alarmante
- Aparece en pantalla y en PDF

**Filosofía**: convierte una posible debilidad en señal de seriedad profesional. El cliente final entiende que el consultor fue transparente sobre los supuestos.

### 5.4 Lo que NO entra en el Sprint 1

❌ Múltiples escenarios (más de 2) — viene en Sprint 3-4 si se demanda
❌ Escenarios como entidad separada (Modelo B)
❌ VPN, TIR, tasa de descuento
❌ Desglose de la inversión (licencias, dev, infra) — un único campo por ahora
❌ Análisis de sensibilidad
❌ Distribuciones probabilísticas
❌ Bots como recursos con capacidad finita
❌ Multi-tenant, login, colaboración, versionado, IA, modo oscuro, i18n, PWA

### 5.5 Definition of Done — Sprint 1

- [ ] Migración Dexie v1 → v2 con preservación de datos existentes
- [ ] Workspace permite marcar actividades como automatizables y configurar costos automatizados
- [ ] Workspace permite configurar volumetría e inversión a nivel proceso
- [ ] Motor de simulación acepta `scenario` y devuelve resultados correctos para ambos casos
- [ ] Reporte tiene 3 tabs (Actual / Automatizado / Comparación + ROI)
- [ ] Sección "Comparación + ROI" muestra 5 KPIs grandes correctamente formateados
- [ ] Tabla comparativa funcional con ordenamiento
- [ ] Gráfico de ahorro acumulado con marcador de payback
- [ ] Gráfico Top 5 actividades con mayor ahorro
- [ ] Sección "Transparencia metodológica" aparece cuando corresponde
- [ ] Cálculos de `domain/roi.ts` cubiertos por tests (≥ 10 casos incluyendo edge cases)
- [ ] Test E2E del flujo completo de ROI con Playwright
- [ ] PDF de ROI incluye las páginas adicionales con KPIs y gráficos
- [ ] CSV de ROI exporta comparación completa
- [ ] Documento `METHODOLOGY_AUTOMATED_COST.md` en raíz del repo
- [ ] Bundle no crece más de 20 KB gzip respecto al MVP
- [ ] Todos los tests previos (268 unit + 5 E2E) siguen verdes
- [ ] Deploy a producción exitoso
- [ ] Smoke test post-deploy verde

---

## 6. Roadmap de Evolución

```
┌──────────────┬──────────────────────────────────────────────────────┐
│   FASE       │ CAPACIDADES                                          │
├──────────────┼──────────────────────────────────────────────────────┤
│ Fase 0 ✅    │ MVP client-side: importar, configurar, simular,      │
│ (completa)   │ reportear, exportar PDF/CSV. v0.1.0-mvp en prod.     │
├──────────────┼──────────────────────────────────────────────────────┤
│ Sprint 1 🔄  │ ROI + escenarios de automatización:                  │
│ (en curso)   │  · Volumetría del proceso                            │
│              │  · Marcado de actividades automatizables             │
│              │  · Inversión de automatización                       │
│              │  · Motor dual: actual vs automatizado                │
│              │  · 5 KPIs de ROI + tabla comparativa + gráficos      │
│              │  · Transparencia metodológica                        │
│              │  · Migración Dexie v1 → v2                           │
├──────────────┼──────────────────────────────────────────────────────┤
│ Sprint 2     │ Productividad de carga:                              │
│              │  · Grilla de edición masiva (TanStack Table)         │
│              │  · Pegado desde Excel                                │
│              │  · Recursos con costo/hora + asignación múltiple     │
│              │  · Cálculo de costo esperado en vivo                 │
│              │  · Edición inline de nombre proceso/cliente          │
├──────────────┼──────────────────────────────────────────────────────┤
│ Sprint 3-4   │ Multi-escenario y reportes ejecutivos:               │
│              │  · Escenarios como entidad (modelo B) si demandado   │
│              │  · Reporte ejecutivo (PDF 1-2 páginas) separado      │
│              │  · Branding InQuality                                │
│              │  · Export Excel multi-hoja                           │
│              │  · Comparación de simulaciones (historial)           │
├──────────────┼──────────────────────────────────────────────────────┤
│ Fase 2       │ Backend + colaboración básica:                       │
│ (1-2 meses)  │  · Backend NestJS + Postgres + Auth                  │
│              │  · Multi-tenant + RBAC                               │
│              │  · Versionado lineal                                 │
│              │  · Editor BPMN (no solo lectura)                     │
│              │  · Validador + Glosario                              │
│              │  · i18n (es/en/pt-BR)                                │
│              │  · PWA installable                                   │
├──────────────┼──────────────────────────────────────────────────────┤
│ Fase 3       │ Colaboración avanzada y modelado fino:               │
│ (1-2 meses)  │  · Colaboración en tiempo real (Yjs/CRDT)            │
│              │  · Presencia + Comentarios                           │
│              │  · Distribuciones probabilísticas                    │
│              │  · Riesgos                                           │
│              │  · Costeo ABC completo                               │
│              │  · Gobernanza RACI                                   │
├──────────────┼──────────────────────────────────────────────────────┤
│ Fase 4       │ Inteligencia y comunidad:                            │
│ (1-2 meses)  │  · IA: detección de cuellos de botella               │
│              │  · Elementos RPA/Agente IA en paleta                 │
│              │  · Marketplace comunitario de plantillas             │
│              │  · Tutoriales interactivos                           │
│              │  · Modo educativo                                    │
└──────────────┴──────────────────────────────────────────────────────┘
```

---

## 7. Arquitectura Técnica

### 7.1 Vista de alto nivel — MVP (Fase 0)

```
┌─────────────────────────────────────────────────────────────┐
│                    NAVEGADOR DEL USUARIO                    │
│                                                             │
│  ┌────────────────────────────────────────────────────┐    │
│  │            React SPA (Vite + TypeScript)           │    │
│  │                                                    │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │    │
│  │  │  Router  │  │  State   │  │ UI Layer     │   │    │
│  │  │ (TanStack│  │ (Zustand)│  │ (shadcn +    │   │    │
│  │  │   Router)│  │          │  │   Tailwind)  │   │    │
│  │  └──────────┘  └──────────┘  └──────────────┘   │    │
│  │                                                    │    │
│  │  ┌─────────────────┐  ┌──────────────────────┐   │    │
│  │  │  bpmn-js        │  │  Simulation Engine    │   │    │
│  │  │ (canvas viewer) │  │  (TypeScript puro)    │   │    │
│  │  └─────────────────┘  └──────────────────────┘   │    │
│  │                                                    │    │
│  │  ┌─────────────────┐  ┌──────────────────────┐   │    │
│  │  │  D3 + ECharts   │  │  Export Layer         │   │    │
│  │  │ (heatmap + viz) │  │  (jsPDF + html2canvas)│   │    │
│  │  └─────────────────┘  └──────────────────────┘   │    │
│  └────────────────────────────────────────────────────┘    │
│                          │                                  │
│                          ▼                                  │
│  ┌────────────────────────────────────────────────────┐    │
│  │           IndexedDB (via Dexie.js)                 │    │
│  │  - processes (BPMN XML + metadata)                 │    │
│  │  - resources                                       │    │
│  │  - activities (costos, tiempos, recursos)          │    │
│  │  - simulations (resultados snapshots)              │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

                Deployable a: Cloudflare Pages / Vercel
                            (estático, gratis, global)
```

### 7.2 Vista de alto nivel — V1.0

```
┌──────────────────┐         ┌──────────────────────────────┐
│   Cliente PWA    │  HTTPS  │      API Gateway (Caddy)     │
│  (React + Vite)  ├────────►│                              │
└────────┬─────────┘         └──────────────┬───────────────┘
         │                                  │
         │ WSS (Yjs)                        │ REST + WebSocket
         │                                  ▼
         │                  ┌───────────────────────────────┐
         │                  │   Backend (NestJS Monolito    │
         │                  │   Modular en Node.js)         │
         │                  │                               │
         │                  │  ┌─────────┬─────────┐        │
         │                  │  │ Auth    │ Process │        │
         │                  │  │ Module  │ Module  │        │
         │                  │  ├─────────┼─────────┤        │
         │                  │  │ Org     │ Simul.  │        │
         │                  │  │ Module  │ Module  │        │
         │                  │  ├─────────┼─────────┤        │
         │                  │  │ Collab  │ AI      │        │
         │                  │  │ Module  │ Module  │        │
         │                  │  └─────────┴─────────┘        │
         │                  └────────┬──────────────────────┘
         │                           │
         └──Yjs WebSocket────────────┤
                                     │
              ┌──────────────────────┼──────────────────────┐
              ▼                      ▼                      ▼
       ┌────────────┐         ┌────────────┐         ┌────────────┐
       │ PostgreSQL │         │   Redis    │         │   MinIO    │
       │  (datos)   │         │ (cache,    │         │ (archivos, │
       │            │         │  pubsub,   │         │  exports)  │
       │            │         │  sessions) │         │            │
       └────────────┘         └────────────┘         └────────────┘

                  Todo desplegable en una VPS (Hostinger / Hetzner)
                  vía Docker Compose
```

### 7.3 Stack tecnológico

#### 6.3.1 Stack MVP (Fase 0)

| Capa | Tecnología | Versión | Justificación |
|---|---|---|---|
| Lenguaje | TypeScript | 5.x | Type safety, mantenibilidad |
| Framework UI | React | 18.x | Ecosistema, Claude Code domina |
| Build tool | Vite | 5.x | Velocidad, simplicidad |
| Routing | TanStack Router | 1.x | Type-safe, moderno |
| Estado | Zustand | 4.x | Simple, sin boilerplate, escala |
| Canvas BPMN | bpmn-js | 17.x | Estándar de facto, MIT, Camunda |
| UI components | shadcn/ui | latest | Copy-paste, no es dependencia rígida |
| Estilos | Tailwind CSS | 3.x | Productividad, mantenibilidad |
| Iconos | Lucide React | latest | Consistencia visual |
| Gráficos | Apache ECharts | 5.x | Calidad visual superior para reportes |
| Heatmap canvas | D3.js (selecciones) | 7.x | Coloreo de nodos bpmn-js |
| Persistencia | IndexedDB vía Dexie | 4.x | API ergonómica sobre IndexedDB |
| Export PDF | jsPDF + html2canvas | latest | Render WYSIWYG del reporte |
| Export CSV | papaparse | 5.x | Robusto, manejo de edge cases |
| Validación schemas | Zod | 3.x | Schemas type-safe |
| Testing | Vitest + Testing Library | latest | Suficiente para MVP |
| Deploy | Cloudflare Pages | — | Gratis, global CDN, SSL incluido |

#### 6.3.2 Stack evolutivo (V1.0)

| Capa | Tecnología | Justificación |
|---|---|---|
| Backend framework | **NestJS** | Monolito modular natural, DI, contratable |
| Runtime | Node.js LTS | Mismo lenguaje que frontend |
| ORM | Prisma | Type-safe, migraciones, excelente DX |
| Base de datos | PostgreSQL 16 | Robustez relacional + JSONB para BPMN |
| Cache/PubSub | Redis 7 | Sessions, Yjs awareness |
| Object storage | MinIO (self-hosted S3) | Exports, attachments, soberanía |
| Realtime | Yjs + y-websocket | CRDT estándar para colaboración |
| Auth | Better-Auth | Self-hosted, moderno, RBAC nativo |
| API Gateway | Caddy | TLS automático, reverse proxy simple |
| Containerización | Docker + Docker Compose | Suficiente para VPS única |
| Observabilidad | OpenTelemetry → Grafana stack | Cuando llegue el momento |
| i18n | i18next + react-i18next | Estándar de facto |
| E2E testing | Playwright | Estándar moderno |

### 7.4 Arquitectura de carpetas (MVP)

```
process-cost-platform/
├── README.md
├── ARCHITECTURE.md              ← este documento
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.ts
├── index.html
├── public/
│   └── sample-processes/        ← BPMNs de ejemplo para demos
├── src/
│   ├── main.tsx                 ← entry point
│   ├── App.tsx                  ← shell de la app
│   ├── router.tsx               ← TanStack Router
│   │
│   ├── domain/                  ← modelo puro, sin UI
│   │   ├── types.ts             ← Process, Activity, Resource, Simulation
│   │   ├── simulation.ts        ← motor de cálculo (TypeScript puro)
│   │   ├── bpmn-parser.ts       ← extracción de nodos de XML BPMN
│   │   └── schemas.ts           ← validación Zod
│   │
│   ├── store/                   ← Zustand stores
│   │   ├── process-store.ts
│   │   ├── resources-store.ts
│   │   └── simulation-store.ts
│   │
│   ├── persistence/             ← IndexedDB / Dexie
│   │   ├── db.ts                ← schema Dexie
│   │   └── repositories.ts      ← funciones CRUD
│   │
│   ├── features/                ← organización por feature
│   │   ├── import/
│   │   │   ├── ImportDropzone.tsx
│   │   │   └── useImportBpmn.ts
│   │   ├── workspace/
│   │   │   ├── WorkspacePage.tsx
│   │   │   ├── BpmnCanvas.tsx           ← integra bpmn-js
│   │   │   ├── ActivityPanel.tsx        ← edición de atributos
│   │   │   ├── ResourcesPanel.tsx
│   │   │   └── GlobalSettingsPanel.tsx
│   │   ├── simulation/
│   │   │   └── useSimulate.ts           ← hook que orquesta el cálculo
│   │   └── report/
│   │       ├── ReportPage.tsx
│   │       ├── HeatmapCanvas.tsx        ← bpmn-js + D3 overlay
│   │       ├── KpiHeader.tsx
│   │       ├── TopActivitiesTable.tsx
│   │       ├── CostByActivityChart.tsx
│   │       ├── CostCompositionChart.tsx
│   │       ├── CostByResourceChart.tsx
│   │       └── ExportControls.tsx
│   │
│   ├── components/              ← componentes compartidos (shadcn + custom)
│   │   ├── ui/                  ← shadcn copy-pastes
│   │   └── ...
│   │
│   ├── lib/                     ← utilidades transversales
│   │   ├── format.ts            ← formateo de moneda, números
│   │   ├── colors.ts            ← lógica de heatmap
│   │   ├── pdf-export.ts        ← jsPDF + html2canvas
│   │   └── csv-export.ts        ← papaparse
│   │
│   └── styles/
│       └── globals.css
└── tests/
    ├── domain/
    │   └── simulation.test.ts   ← tests del motor
    └── e2e/                     ← post-MVP
```

### 7.5 Modelo conceptual del motor de simulación (MVP + Sprint 1)

El motor de simulación del MVP es **determinístico y agregado**. NO es discrete event simulation. Su contrato:

```typescript
interface SimulationInput {
  processXml: string;
  activities: Map<ActivityId, ActivityConfig>;
  resources: Resource[];
  globalSettings: {
    currency: string;
    overheadPercentage: number;  // % sobre costos directos
  };
}

interface ActivityConfig {
  activityId: string;
  directCostFixed: number;       // costo fijo por ejecución
  executionTimeMinutes: number;  // tiempo estimado
  assignedResources: Array<{
    resourceId: string;
    utilizationPercent: number;  // % del tiempo de la actividad
  }>;
  probabilityOfExecution: number; // 0..1, default 1
  // Para gateways: probabilidad por flujo saliente
}

interface SimulationResult {
  totalCost: number;
  totalDirectCost: number;
  totalIndirectCost: number;
  totalTimeMinutes: number;
  perActivity: Array<{
    activityId: string;
    activityName: string;
    expectedDirectCost: number;
    expectedIndirectCost: number;
    expectedTotalCost: number;
    percentOfTotal: number;
    expectedExecutions: number;  // por la prob. acumulada del camino
    resourceCostBreakdown: Array<{ resourceId: string; cost: number }>;
  }>;
  perResource: Array<{
    resourceId: string;
    totalCost: number;
    totalMinutesUsed: number;
  }>;
  warnings: string[];  // ej. "el proceso tiene un loop sin probabilidad definida"
}
```

**Algoritmo (alto nivel)**:

1. Parsear el BPMN XML → grafo dirigido de nodos y flujos.
2. Calcular probabilidad acumulada de ejecución para cada actividad mediante recorrido desde Start Events, propagando probabilidades por gateways.
3. Detectar y advertir loops (en MVP los tratamos como ejecución única; manejo riguroso en V1.0).
4. Para cada actividad: `costoEsperado = (costoDirectoFijo + Σ(recursos.costo/hora × utilización × tiempo/60)) × probabilidadAcumulada`.
5. Costo indirecto = `costoDirectoTotal × overheadPercentage`.
6. Agregar totales y rankings.

### 7.6 Integración bpmn-js + heatmap

`bpmn-js` expone:
- Un `viewer` (read-only) ideal para MVP.
- API para añadir overlays/colores a elementos por ID.
- Eventos de click sobre elementos del diagrama.

El heatmap se implementa así:
1. Cargar BPMN con `Viewer.importXML(xml)`.
2. Tras la simulación, iterar resultados y para cada actividad:
   - Calcular color según modo (relativo/absoluto).
   - Aplicar fill al elemento SVG via `canvas.addMarker(id, className)` o manipulación directa del SVG hijo del nodo.
3. Registrar handler `element.click` para drill-down.
4. Mostrar tooltip con detalle al hover.

### 7.7 Deployment

**Esta noche**:
1. `npm run build` → genera `dist/` estático.
2. Subir a Cloudflare Pages (drag & drop o GitHub integration).
3. Dominio: `tu-subdominio.pages.dev` o dominio propio.

**Costo**: $0.

---

## 8. Modelo de Dominio

### 8.1 Entidades núcleo (estado al Sprint 1)

**Distinción fundamental de capas:**
- `ProcessGraph` (en memoria, reconstruido del XML cada vez): TODOS los nodos del diagrama incluidos gateways, eventos, flujos. Vive solo en el parser/motor, no se persiste.
- `Activity` (persistido en IndexedDB): solo `task` y `subprocess` — nodos con trabajo costeable.
- `GatewayConfig` (persistido en IndexedDB): probabilidades por flujo saliente de gateways divergentes (XOR/OR). Los gateways convergentes (merge) no tienen config — el motor suma probabilidades entrantes.
- El heatmap **solo colorea nodos con Activity**. Los gateways conservan estilo BPMN neutro.

**Campos añadidos en Sprint 1** marcados con 🆕.

```
┌─────────────────────────────────────────────────────────────┐
│                         Process                             │
├─────────────────────────────────────────────────────────────┤
│ + id: UUID                                                  │
│ + name: string                                              │
│ + clientName: string                                        │
│ + bpmnXml: string (raw XML)                                 │
│ + currency: string (ISO 4217)                               │
│ + overheadPercentage: number (0..1)                         │
│ + annualFrequency: number              🆕 default 1000     │
│ + analysisHorizonYears: number         🆕 default 3        │
│ + automationInvestment: number         🆕 default 0        │
│ + createdAt, updatedAt                                      │
└─────────────────────────────────────────────────────────────┘
              │ 1                              │ 1
              │                               │
              │ N                             │ N
┌─────────────────────────┐    ┌──────────────────────────────┐
│        Activity         │    │        GatewayConfig         │
├─────────────────────────┤    ├──────────────────────────────┤
│ + id: UUID              │    │ + id: UUID                   │
│ + processId: UUID (FK)  │    │ + processId: UUID (FK)       │
│ + bpmnElementId: string │    │ + bpmnElementId: string      │
│   (FK conceptual al     │    │   (id del gateway en XML)    │
│    nodo en el XML)      │    │ + gatewayType:               │
│ + name: string          │    │   'exclusive'|'inclusive'    │
│ + type:                 │    │   |'parallel'                │
│   'task'|'subprocess'   │    │ + branches: Array<{          │
│ + directCostFixed:      │    │     flowId: string,          │
│   number                │    │     probability: number      │
│ + executionTimeMinutes: │    │   }>                         │
│   number                │    │   (paralelo: todas 1.0,      │
│ + automatable: boolean  │🆕  │    exclusivo: suma = 1.0)    │
│ + automatedCostFixed:   │🆕  └──────────────────────────────┘
│   number                │
│ + automatedTimeMinutes: │🆕
│   number                │
└─────────────────────────┘
              │ N
              │
              │ M
┌─────────────────────────────────────────────────────────────┐
│                  ActivityResourceAssignment                 │
├─────────────────────────────────────────────────────────────┤
│ + activityId: UUID (FK)                                     │
│ + resourceId: UUID (FK)                                     │
│ + utilizationPercent: number (0..1)                         │
└─────────────────────────────────────────────────────────────┘
                            │ N
                            │
                            │ 1
┌─────────────────────────────────────────────────────────────┐
│                         Resource                            │
├─────────────────────────────────────────────────────────────┤
│ + id: UUID                                                  │
│ + name: string                                              │
│ + type: 'role' | 'person' | 'system' | 'equipment'         │
│        | 'supply'                                           │
│ + costPerHour: number                                       │
│ + currency: string                                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                       Simulation                            │
├─────────────────────────────────────────────────────────────┤
│ + id: UUID                                                  │
│ + processId: UUID (FK)                                      │
│ + executedAt: timestamp                                     │
│ + resultJson: SimulationResult (snapshot)                   │
└─────────────────────────────────────────────────────────────┘
```

### 8.2 Modelo extendido (V1.0)

Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `ProcessOwnership` (RACI), `Risk`, `RiskProcessLink`, `ProcessVersion`, `Comment`, `Notification`, `Template`.

---

## 9. Decisiones Arquitectónicas (ADRs)

### ADR-001 — MVP client-side sin backend
- **Contexto**: tiempo de entrega = una noche, presupuesto cero.
- **Decisión**: el MVP corre 100% en navegador con IndexedDB.
- **Consecuencias**: ✅ Cero costo, cero infraestructura. ❌ Sin colaboración, sin sync entre dispositivos.
- **Cuándo revisar**: al inicio de Fase 1.

### ADR-002 — bpmn-js como motor de canvas
- **Contexto**: existen 3 opciones — bpmn-js, librería custom, render SVG manual.
- **Decisión**: usar bpmn-js (Camunda, MIT).
- **Consecuencias**: ✅ Estándar de la industria, mantenido, soporta BPMN 2.0 XML estándar end-to-end. ❌ Atado a su modelo; extensiones de paleta requerirán plugins propios.
- **Alternativas descartadas**: librería propia (reinventar la rueda, costo prohibitivo).

### ADR-003 — Persistencia con BPMN XML estándar como fuente de verdad
- **Contexto**: hay que decidir si guardamos BPMN XML, JSON propio, o ambos.
- **Decisión**: BPMN XML 2.0 estándar como fuente de verdad. Los costos/tiempos/recursos se guardan en estructuras paralelas vinculadas por `bpmnElementId`.
- **Consecuencias**: ✅ Interoperabilidad con cualquier herramienta BPMN. ❌ Costos no viajan dentro del XML (no es estándar BPMN); requiere export combinado en el futuro.

### ADR-004 — React + Vite + TypeScript
- **Decisión**: React 18 + Vite + TS estricto.
- **Justificación**: ecosistema más grande, Claude Code óptimo en React, contratable en LATAM.
- **Alternativas descartadas**: Vue (menos ecosistema BPMN), Svelte (menor masa crítica), Next.js (SSR innecesario para MVP).

### ADR-005 — Zustand para estado global
- **Decisión**: Zustand sobre Redux/Jotai/Context.
- **Justificación**: simplicidad, sin boilerplate, suficiente para alcance MVP y V1.0.

### ADR-006 — NestJS para backend (V1.0)
- **Decisión**: NestJS como framework backend.
- **Justificación**: modularidad por design (encaja con monolito modular), DI nativo, tipado fuerte, ecosistema empresarial.
- **Alternativas descartadas**: Fastify puro (menos estructura), Express (legacy), Python/FastAPI (cambio de lenguaje innecesario).

### ADR-007 — PostgreSQL + Prisma (V1.0)
- **Decisión**: Postgres como BD principal, Prisma como ORM.
- **Justificación**: relaciones jerárquicas + JSONB para BPMN + robustez probada + tipado e2e con Prisma.

### ADR-008 — Yjs + y-websocket para colaboración (V1.0)
- **Decisión**: CRDTs vía Yjs.
- **Justificación**: estándar en editores colaborativos modernos, sin necesidad de transformación operacional, escala bien.

### ADR-009 — Monolito modular antes que microservicios
- **Decisión**: NestJS monolito con módulos por dominio.
- **Justificación**: equipo pequeño, complejidad innecesaria de microservicios, posibilidad de extraer servicios después si hace falta.

### ADR-010 — Heatmap configurable con default "costo relativo"
- **Decisión**: 3 modos, default relativo.
- **Justificación**: el modo relativo comunica mejor "dónde duele" — el caso de uso primario del consultor.

### ADR-011 — Deploy en Cloudflare Pages para MVP, VPS para V1.0
- **Decisión**: Cloudflare Pages mientras sea estático; migración a VPS al introducir backend.
- **Justificación**: $0 al inicio, latencia global, sin operación. Migrar cuando haya backend.

### ADR-012 — Escenarios como dos pares de campos por actividad (Modelo A), no entidad separada
- **Contexto Sprint 1**: necesidad de modelar costo "actual" vs "automatizado" por actividad.
- **Decisión**: Modelo A — agregar `automatable`, `automatedCostFixed`, `automatedTimeMinutes` a `Activity`. El motor recibe un parámetro `scenario` y elige qué campos usar.
- **Alternativa descartada**: Modelo B (entidad `Scenario` con N configuraciones independientes) — más complejo, no necesario hasta que haya demanda real de >2 escenarios.
- **Justificación**:
  - Trazabilidad actividad-a-actividad para la tabla comparativa (pieza más persuasiva del reporte).
  - Un solo diagrama → consultor no mantiene 2 BPMNs sincronizados.
  - Migración A→B es directa cuando llegue el momento.
- **Cuándo revisar**: Sprint 3-4 si InQuality necesita >2 escenarios o flujos distintos post-automatización.

### ADR-013 — Volumetría aplicada en el reporte, no en el motor
- **Contexto Sprint 1**: necesidad de anualizar costos para calcular ROI.
- **Decisión**: el motor sigue siendo determinístico ("costo de una ejecución"). La volumetría (frecuencia anual + horizonte) es metadata del proceso y se aplica como multiplicador en la capa de reporte.
- **Alternativa descartada**: correr Monte Carlo o múltiples instancias en el motor.
- **Justificación**:
  - El motor es determinístico → correrlo N veces da el mismo resultado × N (perder ciclos).
  - Mantiene separación de concerns: motor calcula costo unitario, reporte hace análisis temporal.
  - Cuando lleguen distribuciones probabilísticas (Fase 3), ahí tiene sentido Monte Carlo.

### ADR-014 — ROI nominal sin VPN ni tasa de descuento en Sprint 1
- **Contexto Sprint 1**: cálculo de payback y ahorro acumulado para pre-venta.
- **Decisión**: usar fórmulas nominales simples (payback = inversión / ahorro anual × 12, acumulado = ahorro × años - inversión). NO incluir VPN, TIR ni tasa de descuento.
- **Justificación**:
  - El cliente promedio de InQuality entiende payback nominal.
  - VPN abre discusiones sobre la tasa que distraen del mensaje principal.
  - Si en el futuro un cliente sofisticado lo pide, se agrega como opción.
- **Cuándo revisar**: cuando un cliente concreto pida VPN/TIR.

### ADR-015 — Transparencia metodológica como feature, no bug
- **Contexto Sprint 1**: riesgo de que consultores carguen valores incompletos (costos automatizados en 0, inversión en 0) generando ROIs irreales.
- **Decisión**: detectar estos casos y exponerlos en sección visible pero discreta del reporte ("Transparencia metodológica").
- **Justificación**:
  - Anticipar limitaciones es señal de seriedad profesional.
  - El cliente final confía más en consultores transparentes sobre supuestos que en cifras "perfectas".
  - Protege la credibilidad de InQuality y la herramienta.
- **Mecanismo**: banner amarillo informativo (no rojo de error) + lista de valores no informados.

---

## 10. Atributos de Calidad

### 10.1 Performance

| Métrica | MVP | V1.0 |
|---|---|---|
| Tiempo carga inicial | < 2s | < 3s en 3G |
| Tamaño bundle JS inicial | < 500KB gzip | < 700KB gzip |
| Cálculo de simulación (50 nodos) | < 100ms | < 500ms |
| Render mapa de calor | < 200ms | < 200ms |
| Export PDF | < 5s | < 5s |

### 10.2 Mantenibilidad

- **TypeScript strict** activado.
- **ESLint + Prettier** configurados.
- **Convención de carpetas por feature**, no por tipo de archivo.
- **Dominio puro separado** de UI (en `/src/domain`) — testeable sin React.
- **Sin lógica de negocio en componentes** — siempre en hooks o domain.

### 10.3 Seguridad (V1.0)

- TLS obligatorio (Cloudflare en MVP, Caddy en VPS).
- Auth con tokens cortos + refresh.
- RBAC: roles `owner`, `admin`, `editor`, `viewer`.
- Sanitización del BPMN XML antes de parsear (evitar XXE).
- CSP estricto en producción.
- Backups cifrados (V1.0).

### 10.4 Accesibilidad

- WCAG 2.1 AA como objetivo V1.0.
- Contraste mínimo 4.5:1 en texto.
- Navegación por teclado en el flujo principal.
- Labels en todos los inputs.

---

## 11. Riesgos y Mitigaciones

| # | Riesgo | Probabilidad | Impacto | Mitigación |
|---|---|---|---|---|
| R1 | El parser BPMN no maneja todos los XML que importe el consultor | Alta | Alto en MVP | Documentar elementos soportados; mostrar warnings claros; testear con BPMNs reales esta noche |
| R2 | El cálculo agregado es engañoso ante loops complejos | Media | Medio | Detectar loops y advertir; en V1.0 implementar Monte Carlo |
| R3 | El reporte exportado a PDF se ve mal por diferencias de render | Media | Alto en MVP | Diseñar el reporte pensando en print desde el día uno; testear export inmediatamente |
| R4 | El cliente del consultor cuestiona la metodología de costeo | Alta | Medio | Documentar fórmula visible en el reporte; permitir override de overhead |
| R5 | IndexedDB se llena o se pierde (modo incógnito, limpieza) | Media | Medio | Botón "Exportar workspace completo" como respaldo manual; en Fase 1 migrar a backend |
| R6 | Performance degrada con diagramas > 100 nodos | Baja en MVP | Bajo | MVP solo soporta hasta 50 nodos por requisito |
| R7 | Dependencia de bpmn-js a futuro (lock-in) | Baja | Bajo | bpmn-js es MIT y mantenido por Camunda; standard BPMN XML protege salida |
| R8 | El usuario espera edición y se frustra con read-only | Alta | Alto | Comunicar claramente que es importación + costeo; Fase 2 trae edición |
| R9 | Caída de motivación / scope creep | Alta | Crítico | Este documento existe para anclar el alcance. Defenderlo. |

---

## 12. Anexos

### 12.1 Comandos de arranque para Claude Code (MVP)

```bash
# Inicialización
npm create vite@latest process-cost-platform -- --template react-ts
cd process-cost-platform
npm install

# Core libs
npm install bpmn-js zustand dexie @tanstack/react-router zod
npm install d3 echarts echarts-for-react
npm install jspdf html2canvas papaparse
npm install lucide-react

# Tailwind + shadcn
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
npx shadcn@latest init

# Dev tooling
npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
npm install -D eslint prettier
```

### 12.2 BPMN XML de prueba sugerido

Para testing inicial, usar el BPMN público de ejemplo de bpmn.io: https://github.com/bpmn-io/bpmn-js-examples

### 12.3 Recursos de referencia

- **bpmn-js docs**: https://bpmn.io/toolkit/bpmn-js/
- **BPMN 2.0 spec**: https://www.omg.org/spec/BPMN/2.0/
- **shadcn/ui**: https://ui.shadcn.com/
- **TanStack Router**: https://tanstack.com/router
- **Zustand**: https://zustand-demo.pmnd.rs/
- **Dexie.js**: https://dexie.org/

### 12.4 Definition of Done — MVP "Noche Cero"

- [ ] El usuario puede importar un archivo `.bpmn` por drag & drop
- [ ] El diagrama se renderiza correctamente en el canvas
- [ ] El usuario puede seleccionar cualquier actividad y editar sus atributos
- [ ] El usuario puede crear, editar y eliminar recursos
- [ ] El usuario puede configurar moneda y overhead global
- [ ] Al hacer click en "Simular", aparece un reporte
- [ ] El reporte muestra mapa de calor sobre el diagrama
- [ ] El reporte muestra KPIs, ranking, gráficos
- [ ] El usuario puede exportar el reporte a PDF y CSV
- [ ] El estado persiste al recargar la página (IndexedDB)
- [ ] El PDF exportado es presentable a un cliente real
- [ ] Deploy público accesible (Cloudflare Pages)

---

> **Nota final del arquitecto**:
>
> Este documento es un contrato contigo mismo. El mayor riesgo del proyecto no es técnico, es la dispersión. Cada vez que sientas la tentación de agregar algo al MVP "porque sería genial", vuelve a la sección 4.3 y recuerda lo que dejaste fuera **por diseño**.
>
> El MVP no demuestra todas las capacidades de la plataforma. Demuestra **una sola cosa**: que un consultor puede transformar un BPMN en un reporte de costos visualmente deslumbrante en minutos. Si esta noche logras eso, ganaste.