erp-core/docs/00-vision-general/VISION-ERP-CORE.md

id	title	type	status	priority	version	created_date	updated_date
VISION-ERP-CORE	Vision General - ERP Core	Vision	Published	P0	2.0.0	2025-12-01	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

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

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

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

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 IA	ARQUITECTURA-IA.md
Integraciones	INTEGRACIONES-EXTERNAS.md
Stack Tecnologico	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