# CLAUDE.md — Contexto del Proyecto

> Este archivo es leído automáticamente por Claude Code en cada sesión.
> Define el "norte" del proyecto y las reglas no negociables.

---

## Identidad del Proyecto

**Nombre de trabajo**: Process Cost Platform (nombre comercial por definir)

**Una frase**: Plataforma web para que consultores de procesos transformen un archivo BPMN 2.0 en un reporte visual deslumbrante de costos operativos en minutos.

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

---

## Estado Actual

- **Fase**: 0 — MVP "Noche Cero"
- **Documento maestro**: `ARCHITECTURE.md` (raíz del repo)
- **Fecha objetivo MVP**: una noche
- **Deploy objetivo**: Cloudflare Pages (estático, gratis)

---

## Reglas No Negociables del MVP

### ✅ Lo que SÍ hacemos esta noche

1. Importar archivo `.bpmn` por drag & drop
2. Renderizar el diagrama en read-only con bpmn-js
3. Editar atributos de actividades (costo, tiempo, recursos asignados)
4. CRUD de recursos (rol/persona/sistema/equipo/insumo + costo/hora)
5. Configuración global (moneda, overhead %, nombre proceso, cliente)
6. Motor de simulación determinístico agregado
7. Reporte visual con mapa de calor sobre el diagrama
8. Gráficos: KPIs, top actividades, costo por actividad, composición, costo por recurso
9. Export a PDF (presentable a cliente) y CSV
10. Persistencia en IndexedDB (Dexie)

### ❌ Lo que NO hacemos esta noche

Login · Multi-tenant · Backend · Colaboración · Edición del BPMN · Versionado · Distribuciones probabilísticas · Riesgos · Gobernanza/RACI · Jerarquía organizacional · IA · Elementos RPA/Agente custom · Tutoriales · Marketplace · i18n · PWA installable · Modo oscuro

**Si dudás si una feature entra: NO ENTRA.** Defendé el alcance.

---

## Stack Obligatorio (MVP)

| Capa | Tecnología |
|---|---|
| Lenguaje | TypeScript estricto |
| Framework | React 18 + Vite |
| Routing | TanStack Router |
| Estado | Zustand |
| Canvas BPMN | bpmn-js (Viewer, no Modeler) |
| UI | shadcn/ui sobre Tailwind CSS |
| Iconos | Lucide React |
| Gráficos | Apache ECharts (vía echarts-for-react) |
| Persistencia | IndexedDB vía Dexie |
| Validación | Zod |
| Export PDF | jsPDF + html2canvas |
| Export CSV | papaparse |
| Testing | Vitest |
| Deploy | Cloudflare Pages |

**No introduzcas librerías fuera de esta lista sin justificación explícita.**

---

## Arquitectura de Carpetas (obligatoria)

```
src/
├── main.tsx
├── App.tsx
├── router.tsx
├── domain/           ← lógica de negocio pura, sin React, testeable
│   ├── types.ts
│   ├── simulation.ts ← motor de simulación
│   ├── bpmn-parser.ts
│   └── schemas.ts    ← Zod schemas
├── store/            ← Zustand stores
├── persistence/      ← Dexie / IndexedDB
├── features/         ← organizado por feature, no por tipo
│   ├── import/
│   ├── workspace/
│   ├── simulation/
│   └── report/
├── components/ui/    ← shadcn copy-pastes
├── lib/              ← utilidades transversales (format, colors, pdf, csv)
└── styles/
```

**Reglas de dependencia**:
- `domain/` NO importa de React, ni de `store/`, ni de `features/`. Es puro.
- `features/` puede importar de `domain/`, `store/`, `persistence/`, `lib/`, `components/`.
- `store/` puede importar de `domain/` y `persistence/`. Nada más.

---

## Principios de Código

1. **TypeScript strict** activado. Nada de `any` salvo en bordes con librerías sin tipos.
2. **Dominio puro**: el motor de simulación es una función pura testeable sin DOM.
3. **Componentes tontos, hooks inteligentes**: lógica en custom hooks, JSX limpio.
4. **Sin lógica de negocio en componentes**.
5. **Convenciones de naming**:
   - Componentes: `PascalCase.tsx`
   - Hooks: `useCamelCase.ts`
   - Utilidades: `kebab-case.ts`
   - Tipos: `PascalCase`, interfaces con prefijo `I` PROHIBIDO
6. **Comentarios en español**, código (variables, funciones) en inglés.
7. **Errores con mensajes accionables** para el usuario, nunca traces crudos en UI.

---

## Diferencial Visual (CRÍTICO)

El 60% del valor del MVP está en **el reporte final**. Si el reporte se ve mediocre, el MVP fracasa aunque el resto funcione. Reglas:

- Tipografía: **Inter** para UI, **JetBrains Mono** para números/datos
- Paleta heatmap: verde `#10b981` → amarillo `#f59e0b` → rojo `#ef4444`
- Cifras de dinero siempre formateadas con separadores y símbolo de moneda
- El export PDF debe verse igual o mejor que la pantalla
- Cada gráfico tiene título, leyenda clara y formato de moneda apropiado
- Densidad de información media-alta (audiencia: consultor profesional)

---

## Definition of Done — Cada Feature

Antes de marcar una tarea como terminada:

- [ ] Funciona en el happy path
- [ ] Maneja el caso de datos vacíos sin crashear
- [ ] Persiste en IndexedDB cuando corresponde
- [ ] Tiene estilo consistente con el resto de la app
- [ ] Si toca dominio: tiene al menos un test en Vitest

---

## Comandos del Proyecto

```bash
npm run dev        # desarrollo
npm run build      # producción
npm run test       # tests con Vitest
npm run lint       # eslint
npm run preview    # previsualizar build
```

---

## Cómo Trabajar Conmigo (el Usuario)

- Cuando termines una tarea grande, **resumí qué cambió y qué falta**.
- Si una decisión no está clara, **proponé 2-3 opciones** con pros/contras antes de codear.
- Si encontrás que algo del documento de arquitectura está mal o falta, **avisame antes de improvisar**.
- No agregues features no pedidas. Si algo se te ocurre, anotalo en `TODO.md`.
- Cuando completes algo, **mostrame los archivos creados/modificados**, no los pegues completos en el chat salvo que te lo pida.

---

## Contexto del Fundador

- Consultor de automatización de procesos basado en Paraguay
- Construye esto como herramienta consultiva propia + para vender a colegas LATAM
- Usa Claude Code Pro como único "equipo de desarrollo"
- Lo va a presentar a clientes reales en días, no meses
- Valora: claridad, robustez, pulido visual, mantenibilidad