inq-roi-simulador-web/ARCHITECTURE.md

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.1.0
Fecha	Mayo 2026
Estado	Draft — Fase 0 (MVP "Noche Cero") en construcción
Autor	Equipo fundador + Claude (arquitectura)
Alcance	MVP de esta noche + Norte V1.0 (12–18 meses)

---

Tabla de Contenidos

1. Contexto y Propuesta de Valor
2. Glosario y Convenciones
3. Norte Estratégico — Visión V1.0
4. Fase 0 — MVP "Noche Cero"
5. Roadmap de Evolución
6. Arquitectura Técnica
7. Modelo de Dominio
8. Decisiones Arquitectónicas (ADRs)
9. Atributos de Calidad
10. Riesgos y Mitigaciones
11. 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): el propio fundador como consultor de automatización de procesos.

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.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"

4.1 Hipótesis a validar

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. Roadmap de Evolución

┌────────────┬──────────────────────────────────────────────────────┐
│   FASE     │ CAPACIDADES                                          │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 0     │ MVP client-side: importar, configurar, simular,      │
│ (1 noche)  │ reportear, exportar PDF/CSV                          │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 1     │ + Backend mínimo + Auth + Persistencia en la nube    │
│ (1-2 sem)  │ + i18n (es/en/pt-BR) + PWA installable               │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 2     │ + Editor BPMN (no solo lectura) + Validador          │
│ (1 mes)    │ + Glosario integrado + Recursos avanzados            │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 3     │ + Estructura organizacional + Multi-tenant           │
│ (1 mes)    │ + RBAC + Versionado lineal                           │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 4     │ + Colaboración en tiempo real (Yjs/CRDT)             │
│ (1-2 mes)  │ + Presencia + Comentarios                            │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 5     │ + Distribuciones probabilísticas + Riesgos           │
│ (1 mes)    │ + Costeo ABC completo + Gobernanza RACI              │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 6     │ + IA: detección de cuellos de botella                │
│ (1-2 mes)  │ + Elementos RPA/Agente IA en paleta                  │
├────────────┼──────────────────────────────────────────────────────┤
│ Fase 7     │ + Marketplace comunitario de plantillas              │
│ (continuo) │ + Tutoriales interactivos + Modo educativo           │
└────────────┴──────────────────────────────────────────────────────┘

---

6. Arquitectura Técnica

6.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)

6.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

6.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

6.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

6.5 Modelo conceptual del motor de simulación (MVP)

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

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.

6.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.

6.7 Deployment del MVP

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.

---

7. Modelo de Dominio

7.1 Entidades núcleo (MVP)

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.

┌─────────────────────────────────────────────────────────────┐
│                         Process                             │
├─────────────────────────────────────────────────────────────┤
│ + id: UUID                                                  │
│ + name: string                                              │
│ + clientName: string                                        │
│ + bpmnXml: string (raw XML)                                 │
│ + currency: string (ISO 4217)                               │
│ + overheadPercentage: number (0..1)                         │
│ + 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,      │
└─────────────────────────┘    │    exclusivo: suma = 1.0)    │
              │ 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)                   │
└─────────────────────────────────────────────────────────────┘

7.2 Modelo extendido (V1.0)

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

---

8. 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.

---

9. Atributos de Calidad

9.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

9.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.

9.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).

9.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.

---

10. 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.

---

11. Anexos

11.1 Comandos de arranque para Claude Code (MVP)

# 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

11.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

11.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/

11.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.