Visión General del Backend

El backend es una API REST construida con NestJS 11 en apps/api. Corre en el puerto 3000 en desarrollo.

Módulos registrados

AuthModule ✅

JWT, Passport, OAuth2 (Google, LinkedIn). Login, signup, refresh tokens.

8 endpoints

UsersModule ✅

Perfiles de usuario, roles, suspensión.

5 endpoints

PathsModule ✅

Catálogo de cursos, módulos y lecciones.

12 endpoints

ProgressModule ✅

Seguimiento de progreso por lección/módulo/path.

6 endpoints

CertificatesModule ✅

Emisión SHA-256 y verificación pública.

4 endpoints

AdminModule ✅

Panel CONTENT_ADMIN y SUPER_ADMIN.

20 endpoints

AIModule ✅

Proxy hacia apps/ai-backend + gestión de credentials y routing.

12 endpoints

OrganizationsModule ✅

Multi-tenancy, seats, invitaciones.

8 endpoints

PaymentsModule ✅

Stripe — suscripciones y webhooks.

5 endpoints

DashboardModule ✅

Datos del dashboard personal del usuario.

3 endpoints

FluidityTestModule ✅

Test diagnóstico de fluencia en IA.

4 endpoints

CreatorsModule ✅

Perfiles de creador, badges, reviews y rutas del Creator Studio.

10 endpoints

InstructorApplicationsModule ✅

Solicitudes de instructor — flujo apply → approve (SUPER_ADMIN).

5 endpoints

GuideModule ✅

Guías técnicas con secciones, bloques y versionado snapshot (ADR-012).

8 endpoints

ResourcesModule ✅

Materiales educativos adjuntos a lecciones/módulos.

6 endpoints

DemoRequestsModule ✅

Captación de leads B2B.

2 endpoints

AuditLogsModule ✅

Trazabilidad de acciones admin y negocio. Decorador @AuditLog(), interceptor global, panel en /admin/audit-logs.

5 endpoints

ScheduledJobsModule ✅

Cron jobs con tracking de ejecución, enable/disable desde admin (/admin/platform/jobs).

7 endpoints

NotificationsModule ✅

Notificaciones in-app: 101 tipos, deduplicación 24h, severidad crítica, preferencias por usuario.

9 endpoints

Estructura estándar de un módulo

modules/{name}/
  {name}.module.ts        ← Imports, providers, exports, controllers
  {name}.controller.ts    ← Endpoints HTTP, decoradores, DTOs
  {name}.service.ts       ← Lógica de negocio, queries Prisma
  dto/
    create-{name}.dto.ts
    update-{name}.dto.ts
  {name}.service.spec.ts  ← Unit tests Jest

Guards de uso obligatorio

Guard	Cuándo usar
JwtAuthGuard	Cualquier endpoint que requiera usuario autenticado
AccessLevelGuard	Endpoints de contenido con @RequireAccessLevel()
RolesGuard	Endpoints admin con @Roles(UserRole.SUPER_ADMIN)
InternalGuard	Endpoints /internal/* llamados solo por ai-backend

Configuración global

main.ts

app.setGlobalPrefix('api');
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
app.enableCors({ origin: process.env.FRONTEND_URL });
// Swagger en /api/docs (solo en development)

Patrón de operaciones asíncronas (BullMQ)

Operaciones que van a cola y no bloquean la request:

Cola	Worker	Operaciones
certificates.queue	certificates.processor	Emisión de certificados
email.queue	email.processor	Emails transaccionales
ai.queue	ai.processor	Llamadas IA de baja urgencia (adaptive engine)
reports.queue	reports.processor	Reportes corporativos