workspace/PLAN-ORGANIZACION-WORKSPACE.md

PLAN DE ORGANIZACIÓN DEL WORKSPACE

Fecha: 2025-12-08 Versión: 1.0.0 Estado: Propuesta

---

RESUMEN EJECUTIVO

Este documento presenta un plan integral para organizar el workspace, centralizando funcionalidades compartidas en core/, definiendo módulos claros para cada proyecto, y eliminando duplicación de código.

Estado Actual

Proyecto	Estado	Backend	Frontend	BD
Gamilit	✅ 60% MVP	NestJS	React 19	PostgreSQL 9 schemas
Trading Platform	🔄 50%	Express	React 18	PostgreSQL 8 schemas
ERP Suite	🔄 35%	Express	React 18	PostgreSQL 12+ schemas
Marketing Content	📋 Inicio	Express	React	-
Betting/Inmobiliaria	📋 Planificación	-	-	-

Problemas Identificados

1. core/modules/ vacío - Solo carpetas sin código
2. core/catalog/_reference/ vacío - Documentación sin implementación
3. Código duplicado entre proyectos (~5,000+ líneas)
4. Frameworks mixtos - NestJS vs Express
5. Patrones inconsistentes - Diferentes formas de hacer lo mismo

---

PARTE 1: ESTRUCTURA DE CORE/

1.1 Estructura Propuesta

core/
├── modules/                    # CÓDIGO COMPARTIDO EJECUTABLE
│   ├── utils/                  # Utilidades universales
│   │   ├── date.util.ts
│   │   ├── string.util.ts
│   │   ├── validation.util.ts
│   │   ├── format.util.ts
│   │   ├── crypto.util.ts
│   │   └── index.ts
│   │
│   ├── auth/                   # Autenticación (adapter pattern)
│   │   ├── jwt/
│   │   │   ├── jwt.service.ts
│   │   │   ├── jwt.guard.ts
│   │   │   └── jwt.strategy.ts
│   │   ├── passport/
│   │   │   ├── google.strategy.ts
│   │   │   ├── facebook.strategy.ts
│   │   │   └── github.strategy.ts
│   │   ├── adapters/
│   │   │   ├── nestjs.adapter.ts
│   │   │   └── express.adapter.ts
│   │   └── index.ts
│   │
│   ├── database/               # Schemas y migraciones base
│   │   ├── schemas/
│   │   │   ├── auth.base.sql
│   │   │   ├── audit.base.sql
│   │   │   └── notifications.base.sql
│   │   ├── entities/
│   │   │   ├── base.entity.ts
│   │   │   └── tenant.entity.ts
│   │   └── migrations/
│   │
│   ├── api/                    # Patrones de API
│   │   ├── response.ts         # ApiResponse format
│   │   ├── pagination.ts
│   │   ├── filters.ts
│   │   └── interceptors/
│   │       ├── transform-response.interceptor.ts
│   │       └── logging.interceptor.ts
│   │
│   ├── notifications/          # Sistema de notificaciones
│   │   ├── email/
│   │   ├── push/
│   │   ├── in-app/
│   │   └── index.ts
│   │
│   ├── payments/               # Integración de pagos
│   │   ├── stripe/
│   │   ├── webhooks/
│   │   └── index.ts
│   │
│   ├── websocket/              # WebSocket patterns
│   │   ├── socket.service.ts
│   │   ├── rooms.ts
│   │   └── index.ts
│   │
│   └── multitenant/            # Multi-tenancy
│       ├── rls.interceptor.ts
│       ├── tenant.context.ts
│       └── index.ts
│
├── catalog/                    # DOCUMENTACIÓN + REFERENCIA (ya existe)
│   ├── auth/
│   │   ├── README.md
│   │   ├── IMPLEMENTATION.md
│   │   └── _reference/         # ← POBLAR CON CÓDIGO DE GAMILIT
│   ├── ...
│
├── constants/                  # CONSTANTES GLOBALES (NUEVO)
│   ├── enums.constants.ts      # Enums universales
│   ├── regex.constants.ts      # Patrones regex
│   └── index.ts
│
├── types/                      # TIPOS COMPARTIDOS (NUEVO)
│   ├── api.types.ts
│   ├── auth.types.ts
│   ├── common.types.ts
│   └── index.ts
│
├── frontend/                   # COMPONENTES FRONTEND COMPARTIDOS (NUEVO)
│   ├── components/
│   │   ├── atoms/
│   │   ├── molecules/
│   │   └── organisms/
│   ├── hooks/
│   ├── utils/
│   └── themes/
│
├── orchestration/              # Sistema de agentes (ya existe)
├── standards/                  # Estándares técnicos (ya existe)
└── package.json                # Para publicar como paquete npm

1.2 Prioridad de Implementación

Prioridad	Módulo	Origen	Impacto
P0	utils/	Gamilit	Todos los proyectos
P0	constants/	Gamilit	Todos los proyectos
P0	types/	Nuevo	Todos los proyectos
P1	auth/	Gamilit + Trading	Backend
P1	api/interceptors/	Gamilit	Backend
P2	database/schemas/	ERP + Gamilit	Base de datos
P2	notifications/	Gamilit	Backend
P3	payments/	Trading	Backend
P3	websocket/	Trading + Gamilit	Backend
P3	frontend/	Gamilit	Frontend

---

PARTE 2: ORGANIZACIÓN DE TRADING PLATFORM

2.1 Estado Actual

trading-platform/apps/
├── backend/          # Express.js - 55 archivos, 15K+ líneas ✅
├── frontend/         # React 18 - 49 archivos ✅
├── ml-engine/        # Python FastAPI - 27 archivos ✅
├── llm-agent/        # Python FastAPI - 18 archivos ✅
├── trading-agents/   # Python FastAPI - 19 archivos ✅
├── data-service/     # Python FastAPI - 8 archivos ⚠️ INCOMPLETO
└── database/         # PostgreSQL - 98 archivos DDL ✅

2.2 Problemas Identificados

1. data-service incompleto - Solo 20% implementado
2. Sin tests - Framework configurado pero sin tests reales
3. URLs hardcodeadas entre servicios
4. Sin retry/circuit breaker en comunicación inter-servicios
5. Documentación API incompleta

2.3 Reorganización Propuesta

trading-platform/
├── apps/
│   ├── backend/                 # API principal (mantener)
│   │   └── src/
│   │       ├── modules/
│   │       │   ├── auth/        # ← Usar @core/auth adapter
│   │       │   ├── users/
│   │       │   ├── trading/
│   │       │   ├── portfolio/
│   │       │   ├── education/
│   │       │   ├── payments/    # ← Usar @core/payments
│   │       │   └── admin/
│   │       └── shared/
│   │           ├── clients/     # Clientes para otros servicios
│   │           ├── middleware/
│   │           └── utils/       # ← Usar @core/utils
│   │
│   ├── frontend/                # UI (mantener)
│   │
│   ├── ml-services/             # RENOMBRAR: Agrupa ML
│   │   ├── prediction-engine/   # Ex ml-engine
│   │   └── signal-generator/    # Nuevo: extraer de ml-engine
│   │
│   ├── ai-services/             # RENOMBRAR: Agrupa IA
│   │   ├── copilot/             # Ex llm-agent
│   │   └── market-analyst/      # Nuevo: análisis de mercado
│   │
│   ├── trading-services/        # RENOMBRAR: Agrupa trading
│   │   ├── agents/              # Ex trading-agents
│   │   └── order-executor/      # Nuevo: ejecución de órdenes
│   │
│   ├── data-services/           # COMPLETAR
│   │   ├── market-data/         # Datos de mercado en tiempo real
│   │   ├── historical/          # Datos históricos
│   │   └── providers/           # Integraciones (Binance, etc.)
│   │
│   └── database/                # Mantener
│
├── packages/                    # NUEVO: Código compartido interno
│   ├── sdk-typescript/          # Cliente para frontend/backend
│   ├── sdk-python/              # Cliente para servicios Python
│   ├── config/                  # Configuración centralizada
│   └── types/                   # Tipos compartidos
│
└── docker/
    ├── docker-compose.yml
    └── docker-compose.dev.yml

2.4 Módulos por Funcionalidad

Funcionalidad	App	Responsabilidad
Autenticación	backend	Login, OAuth, JWT, 2FA
Usuarios	backend	Perfiles, preferencias
Trading	backend + trading-services	Watchlists, órdenes, posiciones
Portafolio	backend	Gestión de inversiones
Educación	backend + frontend	Cursos, lecciones, certificados
Pagos	backend	Stripe, suscripciones
Predicciones	ml-services	Modelos ML, señales
Copiloto IA	ai-services	Chat, análisis, recomendaciones
Agentes	trading-services	Ejecución automática
Datos	data-services	Market data, históricos

2.5 Tareas Pendientes Trading Platform

Tarea	Prioridad	Esfuerzo
Completar data-service	P0	Alto
Agregar tests unitarios	P0	Alto
Implementar retry/circuit breaker	P1	Medio
Crear SDK compartido	P1	Medio
Documentar APIs (OpenAPI)	P1	Medio
Implementar métricas Prometheus	P2	Bajo
Centralizar logging	P2	Bajo
Migrar auth a @core/auth	P2	Medio

---

PARTE 3: ORGANIZACIÓN DE ERP-SUITE

3.1 Estado Actual

erp-suite/apps/
├── erp-core/                    # Base 60% ✅
│   ├── backend/                 # 14 módulos, 100+ archivos
│   ├── frontend/                # 165 archivos
│   └── database/                # 12 schemas, 130+ tablas
│
├── verticales/
│   ├── construccion/            # 35% - DDL parcial ⚠️
│   ├── vidrio-templado/         # 25% - Solo docs 📋
│   ├── mecanicas-diesel/        # 95% - DDL completo ✅
│   ├── retail/                  # 25% - Solo docs 📋
│   └── clinicas/                # 25% - Solo docs 📋
│
├── products/
│   ├── pos-micro/               # 80% MVP ✅
│   └── erp-basico/              # 0% ❌
│
├── saas/                        # Billing layer
└── shared-libs/                 # VACÍO ❌

3.2 Problemas Identificados

1. shared-libs vacío - Sin código compartido entre verticales
2. Verticales sin código - Solo documentación en la mayoría
3. Inconsistencia de stack - Express en core, NestJS en POS
4. Sin herencia clara - Verticales no extienden erp-core

3.3 Arquitectura de Herencia Propuesta

                    ┌─────────────────┐
                    │   @core/        │
                    │   (workspace)   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   erp-core      │
                    │   (60-70%)      │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼───────┐   ┌───────▼───────┐   ┌───────▼───────┐
│  Construcción │   │    Retail     │   │   Clínicas    │
│  (+30% custom)│   │  (+40% custom)│   │  (+50% custom)│
└───────────────┘   └───────────────┘   └───────────────┘

3.4 Reorganización Propuesta

erp-suite/
├── apps/
│   ├── erp-core/                    # BASE GENÉRICA
│   │   ├── backend/
│   │   │   └── src/
│   │   │       ├── modules/
│   │   │       │   ├── auth/        # Autenticación base
│   │   │       │   ├── core/        # Catálogos maestros
│   │   │       │   ├── partners/    # Clientes/Proveedores
│   │   │       │   ├── inventory/   # Inventario base
│   │   │       │   ├── sales/       # Ventas base
│   │   │       │   ├── purchases/   # Compras base
│   │   │       │   ├── financial/   # Contabilidad base
│   │   │       │   ├── hr/          # RRHH base
│   │   │       │   ├── projects/    # Proyectos base
│   │   │       │   ├── crm/         # CRM base
│   │   │       │   └── system/      # Sistema
│   │   │       └── shared/          # Compartido dentro de core
│   │   ├── frontend/
│   │   └── database/
│   │
│   ├── verticales/
│   │   ├── construccion/
│   │   │   ├── backend/
│   │   │   │   └── src/
│   │   │   │       ├── modules/
│   │   │   │       │   ├── construction/  # Proyectos de obra
│   │   │   │       │   ├── hse/           # Seguridad e higiene
│   │   │   │       │   ├── budgets/       # Presupuestos
│   │   │   │       │   ├── progress/      # Avances de obra
│   │   │   │       │   └── infonavit/     # Integración INFONAVIT
│   │   │   │       └── extends/           # EXTENSIONES de erp-core
│   │   │   │           ├── hr.extension.ts
│   │   │   │           └── projects.extension.ts
│   │   │   ├── frontend/
│   │   │   └── database/
│   │   │
│   │   ├── mecanicas-diesel/
│   │   │   ├── backend/
│   │   │   │   └── src/modules/
│   │   │   │       ├── service-orders/    # Órdenes de servicio
│   │   │   │       ├── diagnostics/       # Diagnósticos
│   │   │   │       ├── vehicles/          # Vehículos
│   │   │   │       └── parts/             # Refacciones
│   │   │   └── ...
│   │   │
│   │   ├── vidrio-templado/
│   │   │   └── ... (por definir)
│   │   │
│   │   ├── retail/
│   │   │   ├── backend/
│   │   │   │   └── src/modules/
│   │   │   │       ├── pos/               # Punto de venta
│   │   │   │       ├── cash/              # Caja
│   │   │   │       ├── pricing/           # Precios
│   │   │   │       └── ecommerce/         # E-commerce
│   │   │   └── ...
│   │   │
│   │   └── clinicas/
│   │       ├── backend/
│   │       │   └── src/modules/
│   │       │       ├── patients/          # Pacientes
│   │       │       ├── appointments/      # Citas
│   │       │       ├── consultations/     # Consultas
│   │       │       ├── prescriptions/     # Recetas
│   │       │       ├── laboratory/        # Laboratorio
│   │       │       └── pharmacy/          # Farmacia
│   │       └── ...
│   │
│   └── products/
│       ├── pos-micro/                     # POS standalone
│       └── erp-basico/                    # ERP simplificado
│
├── packages/                              # NUEVO: Shared interno
│   ├── erp-sdk/                           # SDK para verticales
│   ├── erp-types/                         # Tipos compartidos
│   ├── erp-components/                    # Componentes UI
│   └── erp-utils/                         # Utilidades
│
└── docker/

3.5 Módulos por Vertical

Módulo	Core	Construcción	Mecánicas	Retail	Clínicas
Auth	✅	Hereda	Hereda	Hereda	Hereda
Partners	✅	Hereda	Hereda	Hereda	Hereda
Inventory	✅	Extiende	Extiende	Extiende	Extiende
Sales	✅	-	-	Extiende	-
Purchases	✅	Extiende	Extiende	Extiende	Extiende
Financial	✅	Extiende	Hereda	Hereda	Hereda
HR	✅	Extiende	Hereda	Hereda	Hereda
Projects	✅	Extiende	-	-	-
Construction	-	✅	-	-	-
HSE	-	✅	-	-	-
Service Orders	-	-	✅	-	-
Diagnostics	-	-	✅	-	-
POS	-	-	-	✅	-
Cash	-	-	-	✅	-
Patients	-	-	-	-	✅
Appointments	-	-	-	-	✅
Medical Records	-	-	-	-	✅

3.6 Tareas Pendientes ERP-Suite

Tarea	Vertical	Prioridad	Esfuerzo
Implementar backend Mecánicas	mecanicas-diesel	P0	Alto
Completar backend Construcción	construccion	P0	Alto
Crear DDL Retail	retail	P1	Medio
Crear DDL Clínicas	clinicas	P1	Medio
Crear DDL Vidrio Templado	vidrio-templado	P2	Medio
Crear packages/erp-sdk	global	P1	Alto
Implementar herencia de módulos	global	P1	Alto
Poblar shared-libs	global	P1	Medio

---

PARTE 4: PATRONES A REPLICAR DE GAMILIT

4.1 Sistema SSOT (Single Source of Truth)

Qué es: Constantes centralizadas que son la única fuente de verdad.

Archivos a crear en core/constants/:

// core/constants/database.constants.ts
export const DB_SCHEMAS = {
  AUTH: 'auth_management',
  CORE: 'core',
  // ... universales
};

export const getFullTableName = (schema: string, table: string) =>
  `${schema}.${table}`;

// core/constants/api.constants.ts
export const API_VERSION = 'v1';
export const API_BASE = `/api/${API_VERSION}`;

export const buildApiUrl = (route: string) => `${API_BASE}${route}`;

4.2 Sincronización Backend-Frontend

Script: sync-enums.ts

# Copia enums de backend a frontend
cp backend/src/shared/constants/enums.ts frontend/src/shared/constants/enums.ts

Agregar a package.json:

{
  "scripts": {
    "sync:enums": "ts-node scripts/sync-enums.ts",
    "postinstall": "npm run sync:enums"
  }
}

4.3 Estructura de Módulos Backend

module/
├── module.module.ts       # Decorador @Module
├── module.controller.ts   # Endpoints
├── module.service.ts      # Lógica de negocio
├── dto/                   # Data Transfer Objects
│   ├── create-x.dto.ts
│   ├── update-x.dto.ts
│   └── query-x.dto.ts
├── entities/              # Entidades TypeORM
│   └── x.entity.ts
└── __tests__/             # Tests
    ├── module.service.spec.ts
    └── module.controller.spec.ts

4.4 Estructura de Features Frontend

features/
└── gamification/
    ├── components/        # Componentes del feature
    ├── hooks/             # Hooks del feature
    ├── services/          # API calls
    ├── types/             # Tipos
    └── utils/             # Utilidades

4.5 Shared Components (Atomic Design)

shared/components/
├── atoms/                 # Button, Input, Label
├── molecules/             # FormField, Card, Alert
├── organisms/             # DataTable, Modal, Sidebar
└── templates/             # Layouts completos

---

PARTE 5: ACCIONES INMEDIATAS

Fase 1: Core Modules (Semana 1-2)

1. Poblar core/modules/utils/

   • Copiar de /projects/gamilit/apps/backend/src/shared/utils/
   • Adaptar para ser framework-agnostic

2. Crear core/constants/

   • Copiar enums universales de Gamilit
   • Crear regex patterns

3. Crear core/types/

   • Tipos de API response
   • Tipos de paginación
   • Tipos de auth

4. Poblar core/catalog/_reference/

   • Copiar código de referencia de Gamilit para auth, notifications, etc.

Fase 2: Trading Platform (Semana 2-4)

1. Completar data-service

   • Implementar feeds de datos de mercado
   • Integrar con Binance/otros providers

2. Crear packages/sdk-typescript

   • Cliente HTTP compartido
   • Tipos de API

3. Agregar tests básicos

   • Tests unitarios para servicios críticos

Fase 3: ERP-Suite (Semana 3-6)

1. Implementar backend Mecánicas Diesel

   • Basarse en DDL existente (100% completo)
   • Crear services y controllers

2. Completar backend Construcción

   • Implementar services para módulos existentes

3. Crear packages/erp-sdk

   • SDK para que verticales extiendan erp-core

Fase 4: Estandarización (Semana 6-8)

1. Decisión de framework

   • Opción A: Migrar todo a NestJS
   • Opción B: Mantener Express, crear adapters
   • Recomendación: Opción B para minimizar reescritura

2. Implementar patrones SSOT en todos los proyectos

3. Configurar CI/CD con validación de contratos

---

PARTE 6: MATRIZ DE RESPONSABILIDADES

Por Proyecto

Proyecto	Responsable	Stack	Prioridad
core/modules	Arquitecto	Agnostic	P0
Gamilit	Dev Team A	NestJS	Mantenimiento
Trading Platform	Dev Team B	Express/Python	P1
ERP-Suite/Core	Dev Team C	Express	P1
ERP/Verticales	Dev Teams	Express	P2

Por Módulo Core

Módulo	Propietario	Consumidores
utils	Core Team	Todos
auth	Core Team	Backend
database	Core Team	Backend, DDL
api	Core Team	Backend
notifications	Core Team	Backend
payments	Trading Team	Trading, ERP
frontend	Core Team	Frontend

---

PARTE 7: MÉTRICAS DE ÉXITO

Corto Plazo (1 mes)

• core/modules/utils/ implementado y en uso
• core/constants/ creado con enums universales
• data-service de Trading Platform funcional
• Backend de Mecánicas Diesel iniciado

Mediano Plazo (3 meses)

• 70% de código duplicado eliminado
• Todos los proyectos usando @core/utils
• DDL completo para todas las verticales ERP
• Tests con cobertura >50% en servicios críticos

Largo Plazo (6 meses)

• Arquitectura de herencia ERP funcionando
• CI/CD con validación de contratos API
• Documentación completa (OpenAPI) para todas las APIs
• Todos los proyectos con estructura consistente

---

ANEXO A: DECISIONES ARQUITECTÓNICAS

ADR-001: Mantener Múltiples Frameworks

Contexto: Tenemos NestJS (Gamilit) y Express (Trading, ERP).

Decisión: Mantener ambos frameworks, crear adapters en core/.

Razón:

• Reescribir Gamilit a Express sería costoso
• NestJS tiene ventajas para proyectos modulares grandes
• Adapters permiten reutilización de lógica

ADR-002: Monorepo con Packages Compartidos

Contexto: Código duplicado entre proyectos.

Decisión: Usar estructura de packages internos.

Razón:

• npm workspaces para gestionar dependencias
• Cada proyecto puede importar @core/utils, @erp/sdk
• Versionado independiente si es necesario

ADR-003: SSOT para Constantes

Contexto: Constantes hardcodeadas en múltiples lugares.

Decisión: Centralizar en core/constants/ con sincronización automática.

Razón:

• Evita inconsistencias
• Facilita refactoring
• Validación automática en CI

---

ANEXO B: ARCHIVOS CLAVE

# Gamilit (Referencia)
/projects/gamilit/apps/backend/src/shared/constants/enums.constants.ts
/projects/gamilit/apps/backend/src/shared/constants/database.constants.ts
/projects/gamilit/apps/backend/src/shared/constants/routes.constants.ts
/projects/gamilit/apps/backend/src/shared/utils/

# Trading Platform
/projects/trading-platform/apps/backend/src/
/projects/trading-platform/apps/ml-engine/src/
/projects/trading-platform/apps/database/ddl/

# ERP Suite
/projects/erp-suite/apps/erp-core/backend/src/modules/
/projects/erp-suite/apps/erp-core/database/ddl/
/projects/erp-suite/apps/verticales/mecanicas-diesel/database/init/

# Core (a poblar)
/core/modules/
/core/constants/
/core/types/
/core/catalog/*/reference/

---

Fin del documento