workspace/projects/gamilit/docs/00-vision-general/ONBOARDING.md

Guía de Onboarding - GAMILIT Platform

Versión: 1.0 Última actualización: 2025-11-07 Audiencia: Nuevos desarrolladores Tiempo estimado: 2-3 horas

---

📋 Tabla de Contenidos

1. Bienvenida
2. Prerrequisitos
3. Clonar el Repositorio
4. Configurar Base de Datos
5. Configurar Backend
6. Configurar Frontend
7. Verificar Instalación
8. Siguientes Pasos
9. Troubleshooting
10. Recursos Útiles

---

🎉 Bienvenida

¡Bienvenido al equipo de GAMILIT Platform! Esta guía te ayudará a configurar tu entorno de desarrollo local en 2-3 horas.

GAMILIT Platform es una plataforma educativa gamificada que combina:

• 33 mecánicas educativas de comprensión lectora
• Sistema de gamificación con rangos Maya
• Arquitectura multi-tenant escalable
• Stack moderno: React 19 + NestJS + PostgreSQL

Para entender la visión del producto, lee primero VISION.md.

---

✅ Prerrequisitos

Antes de empezar, asegúrate de tener instalado:

Software Requerido

Software	Versión Mínima	Verificar
Node.js	18.0.0+	node --version
npm	9.0.0+	npm --version
PostgreSQL	15.0+	psql --version
Git	2.0+	git --version

Software Recomendado

• Editor: VS Code con extensiones:

  • ESLint
  • Prettier - Code formatter
  • TypeScript + JavaScript
  • Tailwind CSS IntelliSense
  • PostgreSQL (Chris Kolkman)

• Cliente PostgreSQL: pgAdmin 4 o DBeaver (opcional)

• Cliente API: Postman o Insomnia (opcional)

• Terminal: iTerm2 (macOS), Windows Terminal (Windows), o terminal nativa

Instalación de Prerrequisitos

macOS (usando Homebrew):

# Instalar Homebrew si no lo tienes
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instalar Node.js (incluye npm)
brew install node

# Instalar PostgreSQL
brew install postgresql@15
brew services start postgresql@15

# Verificar instalaciones
node --version  # Debe ser >= 18.0.0
npm --version   # Debe ser >= 9.0.0
psql --version  # Debe ser >= 15.0

Ubuntu/Debian:

# Node.js 18+ (usando NodeSource)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# PostgreSQL 15+
sudo apt-get install postgresql-15 postgresql-contrib-15

# Verificar instalaciones
node --version
npm --version
psql --version

Windows:

1. Descargar Node.js 18+ desde https://nodejs.org/
2. Descargar PostgreSQL 15+ desde https://www.postgresql.org/download/windows/
3. Instalar Git desde https://git-scm.com/download/win

---

📦 Clonar el Repositorio

1. Clonar el monorepo

# Clonar repositorio (reemplazar con URL real)
git clone https://github.com/YOUR_ORG/gamilit.git
cd gamilit/projects/gamilit

# Verificar estructura
ls -la
# Deberías ver: apps/, docs/, orchestration/, artifacts/, etc.

2. Explorar la estructura

# Ver estructura principal
tree -L 2 -d

# Leer documentación clave
cat docs/00-overview/VISION.md
cat README.md

---

🗄️ Configurar Base de Datos

1. Crear base de datos y usuario

# Iniciar PostgreSQL (si no está corriendo)
# macOS: brew services start postgresql@15
# Ubuntu: sudo systemctl start postgresql
# Windows: Iniciar desde servicios

# Conectar como superusuario
psql postgres

# Crear usuario y base de datos
CREATE USER gamilit_user WITH PASSWORD 'gamilit_dev_2025';
CREATE DATABASE gamilit_platform OWNER gamilit_user;
GRANT ALL PRIVILEGES ON DATABASE gamilit_platform TO gamilit_user;

# Salir
\q

2. Verificar conexión

# Conectar a la base de datos
psql -U gamilit_user -d gamilit_platform -h localhost

# Si funciona, verás:
# gamilit_platform=>

# Salir
\q

3. Ejecutar DDL (Definiciones de esquema)

# Navegar a carpeta de database
cd apps/database

# Ejecutar esquema base
psql -U gamilit_user -d gamilit_platform -h localhost -f ddl/base-schema.sql

# Ejecutar DDL por schema (orden importante)
psql -U gamilit_user -d gamilit_platform -h localhost -f ddl/schemas/auth_management/schema.sql
psql -U gamilit_user -d gamilit_platform -h localhost -f ddl/schemas/educational_content/schema.sql
psql -U gamilit_user -d gamilit_platform -h localhost -f ddl/schemas/gamification_system/schema.sql
# ... (continuar con otros schemas según necesidad)

4. Cargar datos de prueba (seeds)

# Cargar seeds de desarrollo
psql -U gamilit_user -d gamilit_platform -h localhost -f seeds/dev/01-users.sql
psql -U gamilit_user -d gamilit_platform -h localhost -f seeds/dev/02-modules.sql
psql -U gamilit_user -d gamilit_platform -h localhost -f seeds/dev/03-exercises.sql

# Verificar datos
psql -U gamilit_user -d gamilit_platform -h localhost -c "SELECT COUNT(*) FROM auth_management.users;"
# Debería mostrar algunos usuarios de prueba

Nota: El orden de ejecución de DDL es importante debido a dependencias entre schemas. Ver apps/database/_MAP.md para detalles.

---

🔧 Configurar Backend

1. Navegar a carpeta backend

cd /path/to/gamilit/projects/gamilit/apps/backend

2. Instalar dependencias

npm install
# Esto puede tomar 2-3 minutos

3. Configurar variables de entorno

# Copiar template de .env
cp .env.example .env

# Editar .env con tu editor favorito
nano .env  # o code .env si usas VS Code

Contenido de .env:

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=gamilit_user
DB_PASSWORD=gamilit_dev_2025
DB_DATABASE=gamilit_platform

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=7d

# Application
NODE_ENV=development
PORT=3000
API_PREFIX=/api/v1

# CORS
CORS_ORIGIN=http://localhost:5173

# Rate Limiting
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

# Logging
LOG_LEVEL=debug

⚠️ IMPORTANTE: Cambia JWT_SECRET por un valor único y seguro. Puedes generarlo con:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. Verificar configuración

# Verificar TypeScript
npm run build

# Si hay errores de compilación, revisar tsconfig.json

5. Iniciar backend en modo desarrollo

npm run dev

Output esperado:

[Nest] 12345  - 2025-11-07 10:00:00     LOG [NestFactory] Starting Nest application...
[Nest] 12345  - 2025-11-07 10:00:00     LOG [InstanceLoader] AppModule dependencies initialized
[Nest] 12345  - 2025-11-07 10:00:01     LOG [RoutesResolver] AuthController {/api/v1/auth}:
[Nest] 12345  - 2025-11-07 10:00:01     LOG [RouterExplorer] Mapped {/api/v1/auth/login, POST} route
[Nest] 12345  - 2025-11-07 10:00:02     LOG [NestApplication] Nest application successfully started
[Nest] 12345  - 2025-11-07 10:00:02     LOG Application is running on: http://localhost:3000

6. Verificar endpoints

Abre otra terminal y prueba:

# Health check
curl http://localhost:3000/api/health
# Debería retornar: {"status":"ok","timestamp":"..."}

# Health check de DB
curl http://localhost:3000/api/health/db
# Debería retornar: {"status":"ok","database":"connected"}

🎉 ¡Backend configurado correctamente!

---

🎨 Configurar Frontend

1. Navegar a carpeta frontend

# Abrir nueva terminal
cd /path/to/gamilit/projects/gamilit/apps/frontend

2. Instalar dependencias

npm install
# Esto puede tomar 2-3 minutos

3. Configurar variables de entorno

# Copiar template de .env
cp .env.example .env.local

# Editar .env.local
nano .env.local  # o code .env.local

Contenido de .env.local:

# API Backend
VITE_API_BASE_URL=http://localhost:3000/api/v1

# WebSocket (si aplica)
VITE_WS_URL=ws://localhost:3000

# Environment
VITE_ENV=development

# Feature Flags (opcional)
VITE_ENABLE_SOCIAL_FEATURES=false
VITE_ENABLE_TEACHER_PORTAL=true
VITE_ENABLE_ADMIN_PORTAL=true

4. Iniciar frontend en modo desarrollo

npm run dev

Output esperado:

VITE v7.1.10  ready in 1543 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

5. Abrir aplicación en navegador

# Abrir navegador automáticamente
open http://localhost:5173  # macOS
xdg-open http://localhost:5173  # Linux
start http://localhost:5173  # Windows

O simplemente abre tu navegador y ve a: http://localhost:5173

🎉 ¡Frontend configurado correctamente!

---

✅ Verificar Instalación

1. Verificar Backend (Terminal 1)

# Debe estar corriendo en http://localhost:3000

# Probar endpoints
curl http://localhost:3000/api/health
curl http://localhost:3000/api/health/db
curl http://localhost:3000/api/v1/auth/login -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"test@gamilit.com","password":"test123"}'

2. Verificar Frontend (Terminal 2)

# Debe estar corriendo en http://localhost:5173

# Verificar build (opcional)
npm run build
# No debería haber errores de TypeScript

3. Verificar Base de Datos (Terminal 3)

# Conectar a PostgreSQL
psql -U gamilit_user -d gamilit_platform -h localhost

# Listar schemas
\dn

# Debería mostrar:
# - auth_management
# - educational_content
# - gamification_system
# - progress_tracking
# - social_features
# - content_management
# - audit_logging
# - system_configuration
# - public

# Listar tablas del schema auth_management
\dt auth_management.*

# Contar usuarios
SELECT COUNT(*) FROM auth_management.users;

# Salir
\q

4. Test End-to-End Manual

1. Abrir frontend: http://localhost:5173
2. Intentar login con usuario de prueba (si existe en seeds)
3. Ver dashboard de estudiante
4. Navegar a módulos educativos
5. Verificar que se cargan ejercicios

Si todo lo anterior funciona: ¡Felicitaciones! Tu entorno está 100% configurado.

---

🚀 Siguientes Pasos

Ahora que tu entorno está configurado, te recomendamos:

1. Familiarizarte con el Codebase (Día 1)

Leer documentación clave:

• VISION.md - Visión del producto
• apps/backend/_MAP.md - Estructura del backend
• apps/frontend/_MAP.md - Estructura del frontend
• apps/database/_MAP.md - Esquema de base de datos

Explorar código:

# Backend
cd apps/backend/src
tree -L 2  # Ver estructura de módulos

# Frontend
cd apps/frontend/src
tree -L 2  # Ver estructura de features

2. Ejecutar Tests (Día 1)

# Backend tests
cd apps/backend
npm test

# Frontend tests
cd apps/frontend
npm test

# Ver coverage
npm run test:cov  # backend
npm run test:coverage  # frontend

3. Configurar Herramientas de Desarrollo (Día 1-2)

ESLint y Prettier:

# Backend
cd apps/backend
npm run lint  # Ver errores de linting
npm run format  # Formatear código

# Frontend
cd apps/frontend
npm run lint
npm run format

VS Code settings (opcional): Crear .vscode/settings.json en la raíz:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

4. Leer Estándares de Código (Día 2)

• docs/standards/CODING-STANDARDS.md - Estándares de código
• docs/standards/GIT-WORKFLOW.md - Workflow de Git
• docs/standards/CODE-REVIEW-GUIDE.md - Guía de code review

5. Tomar Primera Tarea (Día 2-3)

Tasks recomendadas para empezar:

• Corregir un bug P2 (bajo riesgo)
• Escribir tests faltantes
• Mejorar documentación
• Refactorizar código existente

Buscar issues en GitHub:

# Labels recomendados para comenzar
- good-first-issue
- documentation
- tests
- refactoring

6. Unirte a Canales de Comunicación (Día 1)

• Slack: #gamilit-backend, #gamilit-frontend, #gamilit-general
• GitHub: Watch repository para notificaciones
• Reuniones: Daily standup (9:00 AM), Sprint planning (Lunes)

---

🔧 Troubleshooting

Problemas Comunes

1. Backend no inicia - Error de conexión a DB

Síntoma:

Error: connect ECONNREFUSED 127.0.0.1:5432

Solución:

# Verificar que PostgreSQL esté corriendo
# macOS
brew services list | grep postgresql

# Ubuntu
sudo systemctl status postgresql

# Si no está corriendo, iniciarlo
brew services start postgresql@15  # macOS
sudo systemctl start postgresql  # Ubuntu

2. Frontend no conecta con Backend - CORS Error

Síntoma:

Access to fetch at 'http://localhost:3000' from origin 'http://localhost:5173'
has been blocked by CORS policy

Solución:

# Verificar .env del backend
cat apps/backend/.env | grep CORS_ORIGIN

# Debe ser:
CORS_ORIGIN=http://localhost:5173

# Reiniciar backend después de cambiar

3. npm install falla - Permission Error

Síntoma:

EACCES: permission denied

Solución:

# NO uses sudo con npm install

# Arreglar permisos de npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Agregar a PATH en ~/.bashrc o ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Recargar shell
source ~/.bashrc  # o source ~/.zshrc

4. TypeScript errors - Module not found

Síntoma:

Cannot find module '@/shared/constants'

Solución:

# Verificar que tsconfig.json tenga paths configurados
cat tsconfig.json | grep -A 5 "paths"

# Reinstalar dependencias
rm -rf node_modules package-lock.json
npm install

5. Base de datos - Tablas no existen

Síntoma:

ERROR: relation "auth_management.users" does not exist

Solución:

# Ejecutar DDL completo
cd apps/database
./scripts/reset-database.sh  # si existe

# O manualmente
psql -U gamilit_user -d gamilit_platform -h localhost -f ddl/base-schema.sql

Obtener Ayuda

Si ninguna solución funciona:

1. Revisar logs detallados:

   # Backend
   tail -f apps/backend/logs/error.log
   
   # Frontend (console del navegador)
   F12 → Console tab
   

2. Buscar en documentación:

   • docs/03-desarrollo/
   • GitHub Issues

3. Preguntar al equipo:

   • Slack: #gamilit-help
   • Tag a Tech Lead: @tech-lead
   • Email: tech@gamilit.com

---

📚 Recursos Útiles

Documentación del Proyecto

Documento	Propósito	Link
VISION.md	Visión del producto	Ver
Arquitectura Backend	Estructura y módulos	Ver
Arquitectura Frontend	Componentes y features	Ver
Esquema DB	Base de datos completa	Ver
API Reference	Documentación de API	Ver

Tecnologías Principales

Backend:

• NestJS Documentation
• TypeORM Documentation
• Express.js Guide
• PostgreSQL Documentation

Frontend:

• React Documentation
• Vite Guide
• TypeScript Handbook
• Tailwind CSS Documentation
• Zustand Guide

Herramientas de Desarrollo

• VS Code Tips & Tricks
• Git Cheatsheet
• PostgreSQL Cheatsheet

Videos y Tutoriales

• NestJS Crash Course
• React 19 Features
• PostgreSQL Tutorial

---

🎓 Checklist de Onboarding

Usa esta checklist para asegurarte de que completaste todo:

Día 1

• Instalados todos los prerrequisitos (Node, PostgreSQL, Git)
• Clonado el repositorio
• Leído VISION.md y README.md
• Base de datos creada y schemas ejecutados
• Backend corriendo en http://localhost:3000
• Frontend corriendo en http://localhost:5173
• Verificados health checks del backend
• Login manual funcional en frontend

Día 2

• Explorada estructura del backend (apps/backend/src/)
• Explorada estructura del frontend (apps/frontend/src/)
• Leídos _MAP.md de apps/backend, apps/frontend, apps/database
• Ejecutados tests del backend (npm test)
• Ejecutados tests del frontend (npm test)
• Configurado ESLint y Prettier en editor
• Leídos CODING-STANDARDS.md y GIT-WORKFLOW.md

Día 3

• Unido a canales de Slack (#gamilit-*)
• Asistido a daily standup
• Tomada primera tarea (good-first-issue)
• Creada primera branch de feature
• Hecho primer commit siguiendo estándares
• Abierto primer PR (aunque sea draft)

---

¡Bienvenido al equipo! 🚀

Si tienes preguntas, no dudes en preguntar en #gamilit-help o contactar a @tech-lead.

---

Documento preparado por: Tech Lead Última actualización: 2025-11-07 Versión: 1.0