---
id: VISION-ERP-CORE
title: Vision General - ERP Core
type: Vision
status: Published
priority: P0
version: 2.0.0
created_date: 2025-12-01
updated_date: 2026-01-10
---

# Vision General: ERP Core

## Resumen Ejecutivo

ERP Core es la **base generica reutilizable** que proporciona el 60-70% del codigo compartido para todas las verticales del ERP Suite. Es una adaptacion de los patrones de Odoo al stack TypeScript/Node.js/React.

**Capacidades Core:**
- Multi-tenancy con Row-Level Security (RLS)
- Autenticacion/Autorizacion avanzada (JWT, OAuth, RBAC)
- Modulos de negocio genericos (Inventario, Ventas, Compras, CRM)

**Capacidades SaaS (Plataforma):**
- Billing y suscripciones con Stripe
- Planes con feature gating y limites
- Notificaciones multicanal (Email, Push, WhatsApp)
- Webhooks outbound con firma HMAC
- Feature flags por tenant/usuario

**Capacidades IA (Inteligencia):**
- Integracion LLM multi-proveedor (OpenRouter)
- MCP Server para herramientas de negocio
- WhatsApp Business con IA conversacional
- Prediccion de inventario y demanda
- Asistente de negocio inteligente

---

## Proposito

### Problema que Resuelve

Desarrollar ERPs verticales desde cero es costoso y repetitivo. El 60-70% de la funcionalidad es comun:
- Autenticacion y usuarios
- Multi-tenancy
- Catalogos maestros
- Partners (clientes/proveedores)
- Productos e inventario
- Ventas y compras
- Contabilidad basica

**Ademas, las plataformas modernas requieren:**
- Modelo de negocio SaaS con suscripciones
- Inteligencia artificial integrada
- Comunicacion omnicanal con clientes

### Solucion

ERP Core provee esta funcionalidad comun de forma:
- **Modular:** Cada modulo es independiente
- **Extensible:** Las verticales pueden extender sin modificar
- **Multi-tenant:** Aislamiento por tenant desde el diseno
- **Documentado:** Documentacion antes de desarrollo
- **SaaS-Ready:** Billing, planes y self-service incluidos
- **AI-First:** IA integrada en flujos de negocio

---

## Objetivos

### Corto Plazo (3 meses)
1. Completar modulos core: Auth, Users, Roles, Tenants
2. Implementar Partners y Products
3. Establecer patrones de extension para verticales
4. **Integrar Billing y Plans (Stripe)**
5. **Implementar Feature Flags**

### Mediano Plazo (6 meses)
1. Completar Sales, Purchases, Inventory
2. Implementar Financial basico
3. Primera vertical (Construccion) usando el core
4. **Integrar Notificaciones multicanal**
5. **Implementar Webhooks outbound**
6. **Integrar MCP Server y LLM**

### Largo Plazo (12 meses)
1. Todas las verticales usando el core
2. **SaaS layer completo para autocontratacion**
3. Marketplace de extensiones
4. **WhatsApp Business con IA integrada**
5. **Prediccion de inventario y demanda**
6. **Asistente de negocio inteligente**

---

## Arquitectura

### Modelo de Capas

```
+------------------------------------------------------------------+
|                        CLIENTES                                   |
|  +----------+ +----------+ +----------+ +----------+             |
|  | Web App  | |Mobile App| | WhatsApp | | API Rest |             |
|  | React 18 | | Expo 51  | | Meta API | | Swagger  |             |
|  +----------+ +----------+ +----------+ +----------+             |
+------------------------------------------------------------------+
|                        CAPA IA                                    |
|  +----------------------------------------------------------+    |
|  |                    MCP SERVER                             |    |
|  |  (Model Context Protocol - Herramientas de Negocio)      |    |
|  +----------------------------------------------------------+    |
|  |                 LLM GATEWAY (OpenRouter)                  |    |
|  |  Claude | GPT-4 | Gemini | Mistral | Llama               |    |
|  +----------------------------------------------------------+    |
+------------------------------------------------------------------+
|                        API GATEWAY                                |
|  +----------------------------------------------------------+    |
|  | Express.js + TypeScript + Swagger                         |    |
|  | Middleware: Auth | Tenant | Rate Limit | Validation      |    |
|  +----------------------------------------------------------+    |
+------------------------------------------------------------------+
|                    SERVICIOS BACKEND                              |
|  +-------+ +-------+ +-------+ +-------+ +-------+ +-------+    |
|  | Auth  | | Users | |Tenants| |Billing| | Plans | |Webhooks|   |
|  +-------+ +-------+ +-------+ +-------+ +-------+ +-------+    |
|  +-------+ +-------+ +-------+ +-------+ +-------+ +-------+    |
|  |Notif  | |Storage| | Audit | |FFlags | |  AI   | |WhatsApp|   |
|  +-------+ +-------+ +-------+ +-------+ +-------+ +-------+    |
|  +-------+ +-------+ +-------+ +-------+ +-------+ +-------+    |
|  |Catalog| |Invntry| | Sales | |Purchas| | CRM   | |Projects|   |
|  +-------+ +-------+ +-------+ +-------+ +-------+ +-------+    |
+------------------------------------------------------------------+
|                     BASE DE DATOS                                 |
|  +----------------------------------------------------------+    |
|  | PostgreSQL 16+ con RLS (Row-Level Security)              |    |
|  | Schemas: auth | users | tenants | billing | plans | ai   |    |
|  |          notifications | webhooks | storage | audit      |    |
|  |          core_catalog | core_inventory | core_sales      |    |
|  +----------------------------------------------------------+    |
+------------------------------------------------------------------+
|                  SERVICIOS EXTERNOS                               |
|  +--------+ +--------+ +--------+ +--------+ +--------+          |
|  | Stripe | |SendGrid| | S3/R2  | | Redis  | |OpenRouter|        |
|  +--------+ +--------+ +--------+ +--------+ +--------+          |
|  +--------+ +--------+                                            |
|  |WhatsApp| | Vision |                                            |
|  +--------+ +--------+                                            |
+------------------------------------------------------------------+
```

### Modelo de Extension

```
+------------------------------------------------------------------+
|                        ERP CORE                                   |
|  Modulos Genericos (MGN-001 a MGN-022)                           |
|  60-70% funcionalidad comun                                      |
|                                                                   |
|  +-- Core Business: auth, users, tenants, catalog, inventory     |
|  +-- SaaS Layer: billing, plans, webhooks, feature-flags         |
|  +-- IA Layer: ai-integration, whatsapp, mcp-server             |
+------------------------------------------------------------------+
                         | EXTIENDE
        +----------------+----------------+
        |                |                |
+---------------+ +---------------+ +---------------+
| Construccion  | |Vidrio Templado| |    Retail     |
|   (MAI-*)     | |    (MVT-*)    | |    (MRT-*)    |
| 30-40% extra  | | 30-40% extra  | | 30-40% extra  |
+---------------+ +---------------+ +---------------+
```

---

## Modulos Core (MGN-*)

### Fase Foundation (P0)

| Codigo | Modulo | Descripcion | Prioridad | Estado |
|--------|--------|-------------|-----------|--------|
| MGN-001 | auth | Autenticacion JWT, OAuth, sessions | P0 | En desarrollo |
| MGN-002 | users | Gestion de usuarios CRUD | P0 | En desarrollo |
| MGN-003 | roles | Roles y permisos (RBAC) | P0 | Planificado |
| MGN-004 | tenants | Multi-tenancy, aislamiento RLS | P0 | Planificado |

### Fase Core Business (P1)

| Codigo | Modulo | Descripcion | Prioridad | Estado |
|--------|--------|-------------|-----------|--------|
| MGN-005 | catalogs | Catalogos maestros genericos | P1 | Planificado |
| MGN-006 | settings | Configuracion del sistema | P1 | Planificado |
| MGN-007 | audit | Auditoria y logs | P1 | Planificado |
| MGN-008 | notifications | Sistema de notificaciones multicanal | P1 | Planificado |
| MGN-009 | reports | Reportes genericos | P2 | Planificado |
| MGN-010 | financial | Contabilidad basica | P1 | Planificado |
| MGN-011 | inventory | Inventario basico | P1 | Planificado |
| MGN-012 | purchasing | Compras basicas | P1 | Planificado |
| MGN-013 | sales | Ventas basicas | P1 | Planificado |
| MGN-014 | crm | CRM basico | P2 | Planificado |
| MGN-015 | projects | Proyectos genericos | P2 | Planificado |

### Fase SaaS Platform (P3)

| Codigo | Modulo | Descripcion | Prioridad | Estado |
|--------|--------|-------------|-----------|--------|
| MGN-016 | billing | Suscripciones y pagos (Stripe) | P3 | Planificado |
| MGN-017 | plans | Planes, limites y feature gating | P3 | Planificado |
| MGN-018 | webhooks | Webhooks outbound con firma HMAC | P3 | Planificado |
| MGN-019 | feature-flags | Feature flags por tenant/usuario | P3 | Planificado |

### Fase IA Intelligence (P3)

| Codigo | Modulo | Descripcion | Prioridad | Estado |
|--------|--------|-------------|-----------|--------|
| MGN-020 | ai-integration | Gateway LLM multi-proveedor | P3 | Planificado |
| MGN-021 | whatsapp-business | WhatsApp Business con IA | P3 | Planificado |
| MGN-022 | mcp-server | MCP Server para herramientas | P3 | Planificado |

---

## Alcance SaaS (Plataforma)

> Ver detalles completos en [ARQUITECTURA-SAAS.md](ARQUITECTURA-SAAS.md)

### Billing y Suscripciones (MGN-016)

**Proveedor:** Stripe

**Caracteristicas:**
- Suscripciones recurrentes (mensual/anual)
- Trial gratuito configurable
- Upgrade/downgrade con prorateo automatico
- Facturas y recibos
- Webhooks Stripe sincronizados
- Portal de cliente Stripe integrado

### Planes y Limites (MGN-017)

| Plan | Precio | Usuarios | Storage | Features |
|------|--------|----------|---------|----------|
| Free | $0/mes | 1 | 100MB | Core basico |
| Starter | $29/mes | 5 | 1GB | + API access |
| Pro | $79/mes | 20 | 10GB | + AI assistant + Webhooks |
| Enterprise | $199/mes | Unlimited | Unlimited | + Custom branding + SLA |

### Notificaciones Multicanal (MGN-008)

**Canales:**
- Email (SendGrid, AWS SES, SMTP)
- Push Web (Web Push API con VAPID)
- In-App (WebSocket real-time)
- WhatsApp Business (Meta Cloud API)

### Webhooks Outbound (MGN-018)

**Eventos:** user.*, subscription.*, invoice.*, tenant.*

**Seguridad:** Firma HMAC-SHA256, reintentos exponenciales

### Feature Flags (MGN-019)

- Flags por tenant y por usuario
- Rollout gradual
- A/B testing
- Evaluaciones por contexto

---

## Alcance IA (Inteligencia)

> Ver detalles completos en [ARQUITECTURA-IA.md](ARQUITECTURA-IA.md)

### Gateway LLM (MGN-020)

**Gateway:** OpenRouter (acceso a 50+ modelos)

| Modelo | Costo/1M tokens | Uso |
|--------|-----------------:|-----|
| Claude 3 Haiku | $0.25 | Default |
| Claude 3 Sonnet | $3.00 | Premium |
| GPT-4o-mini | $0.15 | Fallback |
| Mistral 7B | $0.06 | Economico |

**Caracteristicas:**
- Cambio de modelo sin modificar codigo
- Fallback automatico entre modelos
- Token tracking por tenant
- Configuracion por tenant

### MCP Server (MGN-022)

**Herramientas de Negocio:**
- **Productos:** list, details, availability
- **Inventario:** stock, low-stock, movements
- **Ventas:** create_order, status, update
- **Clientes:** search, balance
- **Fiados:** balance, create, payment

### WhatsApp Business (MGN-021)

**Flujo:** Cliente -> WhatsApp -> LLM -> MCP -> Respuesta

**Tipos de mensaje:** texto, audio, imagen, ubicacion

### Prediccion de Inventario

**Algoritmos:**
- Demanda: Promedio movil ponderado (4 semanas)
- Reorden: (Demanda_diaria x Lead_time) + Stock_seguridad
- Dias de inventario: Stock_actual / Demanda_diaria

---

## Integraciones Externas

> Ver catalogo completo en [INTEGRACIONES-EXTERNAS.md](INTEGRACIONES-EXTERNAS.md)

| Categoria | Servicio | Modulo | Uso |
|-----------|----------|--------|-----|
| Pagos | Stripe | MGN-016 | Billing y suscripciones |
| Email | SendGrid/SES | MGN-008 | Notificaciones |
| Push | Web Push API | MGN-008 | Notificaciones |
| WhatsApp | Meta Cloud API | MGN-021 | Mensajeria |
| Storage | S3/R2/MinIO | - | Archivos |
| Cache | Redis/BullMQ | - | Cache y colas |
| LLM | OpenRouter | MGN-020 | Inteligencia artificial |

---

## Stack Tecnologico

> Ver detalle completo en [STACK-TECNOLOGICO.md](STACK-TECNOLOGICO.md)

### Backend

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| Node.js | 20+ | Runtime |
| Express.js | 4.x | Framework HTTP |
| TypeScript | 5.3+ | Lenguaje |
| TypeORM | 0.3.17 | ORM |
| BullMQ | 5.x | Colas asincronas |
| Socket.io | 4.x | WebSocket |
| Stripe SDK | Latest | Billing |

### Frontend

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| React | 18.x | Framework UI |
| Vite | 5.x | Build tool |
| Zustand | 4.x | State management |
| Tailwind CSS | 4.x | Styling |
| React Query | 5.x | Data fetching |

### Database

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| PostgreSQL | 16+ | Base de datos |
| RLS | - | Multi-tenancy |
| Redis | 7.x | Cache y colas |

---

## Principios de Diseno

### 1. Multi-Tenancy First
Toda tabla tiene `tenant_id`. Todo query filtra por tenant via RLS.

### 2. Documentation Driven
Documentar antes de desarrollar. La documentacion es el contrato.

### 3. Extension over Modification
Las verticales extienden, nunca modifican el core.

### 4. Patterns from Odoo
Adaptar patrones probados de Odoo al stack TypeScript.

### 5. Single Source of Truth
Un lugar para cada dato. Sincronizacion automatica.

### 6. SaaS by Design
Billing, planes y self-service desde el inicio.

### 7. AI-First Architecture
IA integrada en flujos de negocio, no como addon.

### 8. Event-Driven Communication
Webhooks y eventos para comunicacion entre sistemas.

---

## Entregables por Fase

### Fase 1: Foundation (En progreso)
- [ ] MGN-001 Auth completo
- [ ] MGN-002 Users completo
- [ ] MGN-003 Roles completo
- [ ] MGN-004 Tenants completo
- [ ] Documentacion de todos los modulos

### Fase 2: Core Business
- [ ] MGN-005 Catalogs
- [ ] MGN-010 Financial basico
- [ ] MGN-011 Inventory
- [ ] MGN-012 Purchasing
- [ ] MGN-013 Sales

### Fase 3: Extended
- [ ] MGN-006 Settings
- [ ] MGN-007 Audit
- [ ] MGN-008 Notifications (multicanal)
- [ ] MGN-009 Reports
- [ ] MGN-014 CRM
- [ ] MGN-015 Projects

### Fase 4: SaaS Platform
- [ ] MGN-016 Billing (Stripe)
- [ ] MGN-017 Plans
- [ ] MGN-018 Webhooks
- [ ] MGN-019 Feature Flags
- [ ] Portal de autocontratacion

### Fase 5: IA Intelligence
- [ ] MGN-020 AI Integration (OpenRouter)
- [ ] MGN-021 WhatsApp Business
- [ ] MGN-022 MCP Server
- [ ] Prediccion de inventario
- [ ] Asistente de negocio inteligente

---

## Referencias

| Recurso | Path |
|---------|------|
| Arquitectura SaaS | [ARQUITECTURA-SAAS.md](ARQUITECTURA-SAAS.md) |
| Arquitectura IA | [ARQUITECTURA-IA.md](ARQUITECTURA-IA.md) |
| Integraciones | [INTEGRACIONES-EXTERNAS.md](INTEGRACIONES-EXTERNAS.md) |
| Stack Tecnologico | [STACK-TECNOLOGICO.md](STACK-TECNOLOGICO.md) |
| Directivas | `orchestration/directivas/` |
| Templates | `orchestration/templates/` |
| Template SaaS | `projects/template-saas/` |
| MiChangarrito | `projects/michangarrito/` |

---

## Metricas de Exito

### Metricas Core

| Metrica | Objetivo |
|---------|----------|
| Cobertura de tests | >80% |
| Documentacion | 100% antes de desarrollo |
| Reutilizacion en verticales | >60% |
| Tiempo de setup nueva vertical | <1 semana |

### Metricas SaaS

| Metrica | Objetivo |
|---------|----------|
| Tiempo de onboarding self-service | <5 minutos |
| Conversion trial a paid | >10% |
| Churn mensual | <5% |
| Uptime SLA | >99.5% |

### Metricas IA

| Metrica | Objetivo |
|---------|----------|
| Precision de respuestas IA | >85% |
| Latencia promedio LLM | <2 segundos |
| Adopcion de chat IA | >50% usuarios activos |
| Precision prediccion inventario | >70% |

---

*Ultima actualizacion: Enero 2026*