# 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](#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"](#4-fase-0--mvp-noche-cero) 5. [Roadmap de Evolución](#5-roadmap-de-evolución) 6. [Arquitectura Técnica](#6-arquitectura-técnica) 7. [Modelo de Dominio](#7-modelo-de-dominio) 8. [Decisiones Arquitectónicas (ADRs)](#8-decisiones-arquitectónicas-adrs) 9. [Atributos de Calidad](#9-atributos-de-calidad) 10. [Riesgos y Mitigaciones](#10-riesgos-y-mitigaciones) 11. [Anexos](#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: ```typescript interface SimulationInput { processXml: string; activities: Map; 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) ```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 ``` ### 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.