workspace/projects/gamilit/apps/backend/_MAP.md

_MAP: apps/backend/

Última actualización: 2025-11-07 Estado: 🟢 En desarrollo activo Versión: 2.0

---

📋 Propósito de esta Carpeta

Esta carpeta contiene el backend API REST + WebSocket de GAMILIT, implementado en Node.js + Express + TypeScript.

Arquitectura: API REST modular con 13 módulos funcionales

Audiencia:

• Desarrolladores Backend
• Tech Leads
• DevOps Engineers
• Agentes de IA

---

📁 Estructura de Contenido

Stack Tecnológico

Tecnología	Versión	Propósito
Node.js	18+	Runtime
Express.js	4.18+	Framework web
TypeScript	5+	Lenguaje (strict mode)
PostgreSQL	15+	Base de datos (via node-postgres)
Socket.IO	4.6+	WebSocket server
Jest	29+	Testing framework
ESLint	8+	Linter
Prettier	3+	Code formatter
PM2	5+	Process manager

---

🗂️ Estructura de Carpetas

backend/
├── src/                      # Código fuente
│   ├── __tests__/            # Tests (40+ tests)
│   │   ├── fixtures/         # Test fixtures
│   │   ├── helpers/          # Test helpers
│   │   ├── setup/            # Test setup
│   │   └── shared/           # Shared test utils
│   ├── config/               # Configuraciones
│   │   ├── database.config.ts
│   │   ├── jwt.config.ts
│   │   ├── cors.config.ts
│   │   └── socket.config.ts
│   ├── database/             # DB connection
│   │   ├── pool.ts           # PostgreSQL pool
│   │   └── connection.ts     # Connection manager
│   ├── middleware/           # Express middleware
│   │   ├── auth.middleware.ts
│   │   ├── error.middleware.ts
│   │   └── logging.middleware.ts
│   ├── modules/              # 13 módulos funcionales
│   │   ├── auth/             # Autenticación (JWT)
│   │   ├── admin/            # Portal admin
│   │   ├── teacher/          # Portal teacher
│   │   ├── educational/      # Contenido educativo
│   │   ├── gamification/     # Gamificación
│   │   ├── progress/         # Progress tracking
│   │   ├── social/           # Social features
│   │   ├── content/          # Content management
│   │   ├── notifications/    # Notificaciones
│   │   ├── mail/             # Email service
│   │   ├── missions/         # Misiones
│   │   ├── powerups/         # Power-ups
│   │   └── core/             # Core utilities
│   ├── shared/               # Código compartido
│   │   ├── constants/        # Constants SSOT
│   │   ├── types/            # Tipos TypeScript
│   │   ├── utils/            # Utilidades
│   │   ├── decorators/       # Decoradores custom
│   │   ├── guards/           # Auth guards
│   │   ├── filters/          # Exception filters
│   │   ├── interceptors/     # Interceptors
│   │   ├── pipes/            # Validation pipes
│   │   ├── middleware/       # Shared middleware
│   │   ├── mappers/          # DTO mappers
│   │   └── services/         # Shared services
│   ├── app.module.ts         # App module principal
│   └── main.ts               # Entry point
├── dist/                     # Build output
├── logs/                     # Application logs
├── coverage/                 # Test coverage reports
├── node_modules/             # Dependencies (~95 MB)
├── __tests__/                # Tests adicionales (root)
├── package.json              # NPM config
├── tsconfig.json             # TypeScript config
├── jest.config.js            # Jest config
├── .eslintrc.js              # ESLint config
├── .prettierrc               # Prettier config
├── .env.example              # Environment variables template
└── README.md                 # Documentación

---

🧩 Módulos Funcionales (13 módulos)

auth/ - Autenticación

Responsabilidad: Login, registro, JWT tokens, refresh tokens

Endpoints: ~15

• POST /api/v1/auth/login
• POST /api/v1/auth/register
• POST /api/v1/auth/refresh
• POST /api/v1/auth/logout
• GET /api/v1/auth/me

Archivos:

• auth.controller.ts
• auth.service.ts
• auth.module.ts
• dto/login.dto.ts
• dto/register.dto.ts

Tests: ~8 tests

---

educational/ - Contenido Educativo

Responsabilidad: Módulos educativos, ejercicios (27 mecánicas), contenido

Endpoints: ~60

• GET /api/v1/educational/modules
• GET /api/v1/educational/exercises/:id
• POST /api/v1/educational/exercises/:id/submit
• GET /api/v1/educational/modules/:id/progress

Archivos:

• educational.controller.ts
• educational.service.ts
• exercises.controller.ts
• exercises.service.ts
• modules.controller.ts
• modules.service.ts

Tests: ~5 tests (insuficiente)

---

gamification/ - Gamificación

Responsabilidad: ML Coins, rangos maya, achievements, power-ups, leaderboards

Endpoints: ~45

• GET /api/v1/gamification/ranking
• GET /api/v1/gamification/ml-coins/balance
• POST /api/v1/gamification/ml-coins/spend
• GET /api/v1/gamification/achievements
• POST /api/v1/gamification/achievements/:id/claim

Archivos:

• gamification.controller.ts
• gamification.service.ts
• ml-coins.controller.ts
• ml-coins.service.ts
• achievements.controller.ts
• achievements.service.ts
• leaderboards.controller.ts
• leaderboards.service.ts

Tests: ~6 tests

---

progress/ - Progress Tracking

Responsabilidad: Tracking de progreso de estudiantes, intentos, sesiones

Endpoints: ~40

• GET /api/v1/progress/student/:id
• GET /api/v1/progress/module/:moduleId
• POST /api/v1/progress/exercise/:exerciseId/attempt
• GET /api/v1/progress/analytics

Archivos:

• progress.controller.ts
• progress.service.ts
• attempts.controller.ts
• attempts.service.ts

Tests: ~4 tests

---

social/ - Social Features

Responsabilidad: Escuelas, aulas, teams, competencias, amigos

Endpoints: ~55

• GET /api/v1/social/schools
• GET /api/v1/social/classrooms
• POST /api/v1/social/friends/add
• GET /api/v1/social/teams
• GET /api/v1/social/competitions

Archivos:

• social.controller.ts
• social.service.ts
• schools.controller.ts
• classrooms.controller.ts
• friends.controller.ts

Tests: ~3 tests

---

admin/ - Portal Admin

Responsabilidad: Gestión de usuarios, organizaciones, sistema

Endpoints: ~80

• GET /api/v1/admin/users
• POST /api/v1/admin/users
• PUT /api/v1/admin/users/:id
• DELETE /api/v1/admin/users/:id
• GET /api/v1/admin/organizations

Archivos:

• admin.controller.ts
• admin.service.ts
• users.controller.ts
• organizations.controller.ts

Tests: ~2 tests

---

teacher/ - Portal Teacher

Responsabilidad: Classroom management, asignaciones, calificación

Endpoints: ~70

• GET /api/v1/teacher/classrooms
• POST /api/v1/teacher/assignments
• PUT /api/v1/teacher/grades/:id
• GET /api/v1/teacher/students/:id/progress

Archivos:

• teacher.controller.ts
• teacher.service.ts
• classrooms.controller.ts
• assignments.controller.ts
• grading.controller.ts

Tests: ~2 tests

---

content/ - Content Management

Responsabilidad: Upload de archivos, gestión de media (MinIO/S3)

Endpoints: ~30

• POST /api/v1/content/upload
• GET /api/v1/content/files/:id
• DELETE /api/v1/content/files/:id

Archivos:

• content.controller.ts
• content.service.ts
• upload.controller.ts

Tests: ~1 test

---

notifications/ - Notificaciones

Responsabilidad: Push notifications, in-app, email, real-time (Socket.IO)

Endpoints: ~25

• GET /api/v1/notifications
• PUT /api/v1/notifications/:id/read
• POST /api/v1/notifications/send

WebSocket Events:

• notification:new
• notification:read

Archivos:

• notifications.controller.ts
• notifications.service.ts
• socket.gateway.ts

Tests: ~2 tests

---

mail/ - Email Service

Responsabilidad: Envío de emails (SendGrid)

Archivos:

• mail.service.ts
• templates/

Tests: ~1 test

---

missions/ - Misiones

Responsabilidad: Sistema de misiones diarias/semanales

Endpoints: ~15

• GET /api/v1/missions
• POST /api/v1/missions/:id/start
• POST /api/v1/missions/:id/complete

Archivos:

• missions.controller.ts
• missions.service.ts

Tests: ~1 test

---

powerups/ - Power-ups

Responsabilidad: Power-ups temporales (2x XP, skip exercise, etc)

Endpoints: ~10

• GET /api/v1/powerups
• POST /api/v1/powerups/:id/use

Archivos:

• powerups.controller.ts
• powerups.service.ts

Tests: ~1 test

---

core/ - Core Utilities

Responsabilidad: Utilidades core del sistema

Archivos:

• health.controller.ts
• system.controller.ts

Endpoints:

• GET /api/health
• GET /api/health/db
• GET /api/system/info

Tests: ~2 tests

---

📊 Métricas del Backend

Código

Métrica	Valor
Archivos TypeScript	375
LOC	~45,000
Módulos	13
Controllers	33
Services	43
Endpoints API	~470+

Testing

Métrica	Actual	Objetivo	Gap
Tests totales	40	210	🔴 81%
Coverage	~15%	70%	🔴 55%
Tests unitarios	35	150	🔴 77%
Tests integración	5	60	🔴 92%

Tamaño

Componente	Tamaño
Total	108 MB
node_modules	~95 MB
src	~10 MB
dist	~2 MB
logs	~500 KB
coverage	~500 KB

---

🔗 Interdependencias

Database (apps/database/)

• Consume DDL de apps/database/ddl/
• Constants referencian schemas y tablas
• Queries usan funciones PL/pgSQL
• RLS policies enforced en queries

Frontend (apps/frontend/)

• Provee API REST endpoints
• WebSocket para real-time
• ENUMs sincronizados (Constants SSOT)
• CORS configurado para frontend

DevOps (apps/devops/)

• Scripts de validación (Constants SSOT)
• Sincronización de ENUMs
• Validación de hardcoding

---

🚨 Issues Conocidos

P0 (Crítico)

• P0-001: Test coverage bajo (15% vs 70% objetivo)
  • Exercise engine sin tests (27 mecánicas)
  • Gamification system sin tests
  • Esfuerzo: 20-30 horas

P1 (Alto)

• P1-001: No usa TypeORM/Prisma

  • Usa node-postgres directo
  • Queries SQL manuales propensas a errores
  • Recomendación: Considerar migración

• P1-002: WebSocket no documentado completamente

  • Eventos sin tipado fuerte
  • Esfuerzo: 4-6 horas

P2 (Medio)

• P2-001: Logging básico

  • Winston configurado pero sin estructura
  • Falta ELK Stack integration
  • Esfuerzo: 6-8 horas

• P2-002: Sin rate limiting por usuario

  • Solo rate limiting global
  • Esfuerzo: 2-3 horas

---

📐 Estándares Aplicables

Path Aliases

Configurados en tsconfig.json:

{
  "@shared/*": ["src/shared/*"],
  "@modules/*": ["src/modules/*"],
  "@config/*": ["src/config/*"],
  "@database/*": ["src/database/*"],
  "@middleware/*": ["src/middleware/*"]
}

Nomenclatura

• Archivos: kebab-case.ts
• Clases: PascalCase
• Funciones: camelCase
• Constants: UPPER_SNAKE_CASE

Estructura de Módulos

modules/[nombre]/
├── [nombre].controller.ts      # Controller (endpoints)
├── [nombre].service.ts         # Service (business logic)
├── [nombre].module.ts          # Module (dependency injection)
├── dto/                        # Data Transfer Objects
│   ├── create-[nombre].dto.ts
│   └── update-[nombre].dto.ts
├── entities/                   # Database entities (si usa TypeORM)
└── __tests__/                  # Tests
    ├── [nombre].controller.spec.ts
    └── [nombre].service.spec.ts

---

🎯 Próximos Pasos

Fase 1 - Urgente (Esta Semana)

1. ✅ _MAP.md creado (este archivo)
2. ⬜ Implementar tests exercise engine (27 mecánicas)
3. ⬜ Aumentar coverage a 40%
4. ⬜ Documentar WebSocket events

Esfuerzo: 15-20 horas

Fase 2 - Alta Prioridad (Próximas 2 Semanas)

5. ⬜ Implementar tests gamification (ML Coins, achievements)
6. ⬜ Mejorar logging estructurado
7. ⬜ Rate limiting por usuario
8. ⬜ Coverage 70%

Esfuerzo: 20-25 horas

Fase 3 - Media Prioridad (Próximo Mes)

9. ⬜ Evaluar migración a TypeORM/Prisma
10. ⬜ Integrar ELK Stack
11. ⬜ Swagger UI para API docs
12. ⬜ APM (New Relic/Datadog)

Esfuerzo: 25-30 horas

---

🚀 Scripts NPM

# Desarrollo
npm run dev              # Hot reload con ts-node-dev
npm run dev:debug        # Debug mode

# Build
npm run build            # Build production (tsc)
npm run start            # Start production (node dist/main.js)

# Testing
npm test                 # Run tests (Jest)
npm run test:watch       # Tests en modo watch
npm run test:cov         # Tests con coverage
npm run test:e2e         # E2E tests (Supertest)

# Calidad
npm run lint             # ESLint
npm run lint:fix         # ESLint autofix
npm run format           # Prettier
npm run format:check     # Prettier check

# Validaciones (Constants SSOT)
npm run sync:enums       # Sincronizar ENUMs con frontend
npm run validate:constants  # Detectar hardcoding

---

📚 Documentación Relacionada

Guías de desarrollo:

• docs/03-desarrollo/backend/
• docs/03-desarrollo/backend/ESTRUCTURA-Y-MODULOS.md
• docs/03-desarrollo/backend/API-ENDPOINTS.md
• docs/03-desarrollo/backend/SERVICIOS-PRINCIPALES.md

Especificaciones técnicas:

• docs/02-especificaciones-tecnicas/apis/
• docs/02-especificaciones-tecnicas/arquitectura/BACKEND-ARCHITECTURE.md

Testing:

• docs/03-desarrollo/TESTING-GUIDE.md
• docs/02-especificaciones-tecnicas/testing-strategy/

---

📞 Contacto

Owner: @backend-team Tech Lead: @tech-lead

Reportar issues:

• GitHub Issues: [GAMILIT Backend]
• Slack: #gamilit-backend

---

Generado: 2025-11-07 Método: Sistema SIMCO - Fase 3 (Submapas apps/) Versión: 1.0.0