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

---
id: "ANALISIS-PROYECTOS-REFERENCIA"
title: "Analisis de Proyectos de Referencia"
type: "Analysis"
status: "Draft"
project: "platform_marketing_content"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "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

```typescript
// 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

```typescript
// 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/`

```typescript
// 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

```typescript
@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

```yaml
# 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