platform-marketing-content/docs/01-analisis-referencias/ANALISIS-PROYECTOS-REFERENCIA.md

id	title	type	status	project	version	created_date	updated_date
ANALISIS-PROYECTOS-REFERENCIA	Analisis de Proyectos de Referencia	Analysis	Draft	platform_marketing_content	1.0.0	2026-01-04	2026-01-04

Analisis de Proyectos de Referencia

Version: 1.0.0 Fecha: 2025-12-08 Proyecto: Platform Marketing Content (PMC)

---

Proposito

Este documento analiza los proyectos existentes en el workspace que pueden servir como referencia para patrones de implementacion, estructuras de codigo y decisiones arquitectonicas.

---

Proyectos Analizados

Proyecto	Estado	Stack	Relevancia PMC
gamilit	Operativo	NestJS + React + PostgreSQL	ALTA
trading-platform	En desarrollo	NestJS + PostgreSQL	MEDIA
erp-suite	En documentacion	NestJS + PostgreSQL	BAJA

---

1. Gamilit - Sistema de Gamificacion Educativa

Ubicacion: projects/gamilit/

Metricas del Proyecto

Componente	Cantidad
Schemas PostgreSQL	18
Tablas	117
Entidades Backend	87
DTOs	318
Endpoints	356
Componentes Frontend	399

Patrones Reutilizables para PMC

1.1 Estructura de Modulos NestJS

apps/backend/src/modules/
├── {modulo}/
│   ├── {modulo}.module.ts
│   ├── controllers/
│   │   └── {modulo}.controller.ts
│   ├── services/
│   │   └── {modulo}.service.ts
│   ├── entities/
│   │   └── {entidad}.entity.ts
│   ├── dto/
│   │   ├── create-{entidad}.dto.ts
│   │   ├── update-{entidad}.dto.ts
│   │   └── {entidad}-response.dto.ts
│   └── __tests__/
│       └── {modulo}.service.spec.ts

Aplicacion PMC: Usar esta estructura para todos los modulos (CRM, Projects, Generation, etc.)

1.2 Patron de Repositorios con TypeORM

// Patron usado en Gamilit
@Injectable()
export class ClientService {
  constructor(
    @InjectRepository(Client)
    private readonly clientRepository: Repository<Client>,
  ) {}

  async findAllByTenant(tenantId: string): Promise<Client[]> {
    return this.clientRepository.find({
      where: { tenant_id: tenantId },
      relations: ['brands', 'contacts'],
    });
  }
}

1.3 Sistema de Guards Compuestos

// Patron de guards encadenados
@Controller('admin')
@UseGuards(JwtAuthGuard, RolesGuard, TenantMemberGuard)
@Roles(RoleEnum.ADMIN)
export class AdminController {
  // ...
}

1.4 Estructura de Base de Datos

Gamilit usa schemas funcionales:

• auth - Usuarios base
• auth_management - Perfiles, sesiones, tokens
• gamification_system - Logica de gamificacion
• system_configuration - Settings, feature flags

Mapeo a PMC:

Schema Gamilit	Schema PMC Equivalente
auth	auth
auth_management	auth
-	crm
-	projects
-	generation
-	assets
system_configuration	config

Archivos de Referencia Clave

Proposito	Archivo en Gamilit
Auth Module	apps/backend/src/modules/auth/
Session Service	apps/backend/src/modules/auth/services/session-management.service.ts
RLS Policies	apps/database/ddl/policies/
Feature Flags	apps/backend/src/modules/admin/services/feature-flags.service.ts
Notifications	apps/backend/src/modules/notifications/

---

2. Trading Platform

Ubicacion: projects/trading-platform/

Patrones Reutilizables para PMC

2.1 Integracion con Stripe

Ubicacion: apps/api/src/payments/

// Patron de checkout session
async createCheckoutSession(dto: CreateCheckoutDto): Promise<string> {
  const customer = await this.getOrCreateCustomer(dto.userId);

  const session = await this.stripe.checkout.sessions.create({
    customer: customer.stripeCustomerId,
    line_items: [{
      price: dto.stripePriceId,
      quantity: 1,
    }],
    mode: 'subscription',
    success_url: `${this.frontendUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${this.frontendUrl}/pricing`,
    metadata: {
      userId: dto.userId,
      planId: dto.planId,
    },
  });

  return session.url;
}

Aplicacion PMC: Copiar patron para implementar suscripciones SaaS

2.2 WebSocket para Tiempo Real

@WebSocketGateway({
  cors: { origin: '*' },
  namespace: '/updates',
})
export class UpdatesGateway {
  @WebSocketServer()
  server: Server;

  async notifyJobProgress(jobId: string, progress: number): Promise<void> {
    this.server.to(`job:${jobId}`).emit('progress', { jobId, progress });
  }
}

Aplicacion PMC: Usar para mostrar progreso de generacion de imagenes en tiempo real

Archivos de Referencia Clave

Proposito	Archivo en Trading Platform
Stripe Integration	apps/api/src/payments/services/stripe.service.ts
Subscription Service	apps/api/src/payments/services/subscription.service.ts
WebSocket Gateway	apps/api/src/websocket/updates.gateway.ts
Wallet Service	apps/api/src/payments/services/wallet.service.ts

---

3. ERP Suite - Verticales

Ubicacion: projects/erp-suite/

Patrones Reutilizables para PMC

3.1 Estructura Multi-Vertical

ERP Suite tiene verticales independientes:

apps/verticales/
├── construccion/
├── retail/
├── clinicas/
└── vidrio-templado/

Cada vertical hereda del core pero tiene personalizaciones.

Aplicacion PMC: Si en futuro PMC tiene "verticales" (agencias de diferentes industrias), puede seguir este patron.

3.2 Patron de Inventarios de Orchestration

# Estructura de inventario
modules:
  MOD-001-NAME:
    name: "Nombre Modulo"
    status: definido | en_desarrollo | completado
    entities:
      - Entity1
      - Entity2
    endpoints_count: N
    dependencies:
      modules: []
      catalog: []

Aplicacion PMC: Ya implementado en MASTER_INVENTORY.yml

---

Comparativa de Decisiones Arquitectonicas

Decision	Gamilit	Trading	PMC (Recomendado)
ORM	TypeORM	TypeORM	TypeORM
Auth	JWT custom	JWT + OAuth	JWT (catalogo)
Multi-tenant	RLS	Schemas	RLS (catalogo)
Queue	Bull	BullMQ	BullMQ
Storage	S3	S3	MinIO/S3
WebSocket	Socket.io	Socket.io	Socket.io
Payments	-	Stripe	Stripe (catalogo)

---

Lecciones Aprendidas de Proyectos Existentes

De Gamilit

1. RLS desde el inicio - Implementar Row Level Security desde la primera tabla
2. Feature flags - Usar flags para rollout gradual de features
3. Inventarios actualizados - Mantener inventarios sincronizados con el codigo
4. Clean creation - DDL debe poder recrear BD desde cero

De Trading Platform

1. Webhooks robustos - Stripe requiere manejo cuidadoso de webhooks
2. Idempotencia - Todas las operaciones de pago deben ser idempotentes
3. WebSocket con rooms - Separar updates por contexto (job, tenant)

De ERP Suite

1. Documentacion antes de codigo - Validar con stakeholders primero
2. Herencia de patterns - Verticales heredan del core
3. Orchestration system - Usar SIMCO para consistencia

---

Recursos a Copiar/Adaptar

Codigo Base Recomendado

Necesidad PMC	Fuente	Archivos
Auth module	gamilit	apps/backend/src/modules/auth/
Session management	gamilit	apps/backend/src/modules/auth/services/session*.ts
RLS policies	gamilit	apps/database/ddl/policies/
Stripe service	trading	apps/api/src/payments/services/stripe.service.ts
WebSocket gateway	trading	apps/api/src/websocket/
Feature flags	gamilit	apps/backend/src/modules/admin/services/feature-flags.service.ts
Notifications	gamilit	apps/backend/src/modules/notifications/

Configuraciones Base

Archivo	Fuente	Proposito
tsconfig.json	gamilit	TypeScript paths
docker-compose.yml	gamilit	PostgreSQL + Redis
jest.config.ts	gamilit	Testing config
.env.example	gamilit	Variables de entorno

---

Proximos Pasos

1. Clonar estructura base de Gamilit para backend PMC
2. Copiar modulos del catalogo (@CATALOG_AUTH, @CATALOG_TENANT)
3. Adaptar configuraciones segun ADRs de PMC
4. Implementar modulos propios (CRM, Projects, Generation)

---

Referencias

• Inventario Gamilit: projects/gamilit/orchestration/inventarios/MASTER_INVENTORY.yml
• Inventario Trading: projects/trading-platform/orchestration/inventarios/MASTER_INVENTORY.yml
• Catalogo: shared/catalog/CATALOG-INDEX.yml

---

Generado por: Requirements-Analyst Fecha: 2025-12-08