workspace/projects/gamilit/apps/frontend/README.md

GAMILIT Frontend

Frontend para la plataforma educativa gamificada GAMILIT.

Stack Técnico

• Framework: React 19.2.0
• Build Tool: Vite 7.1.10
• Language: TypeScript 5.9.3 (strict mode)
• Styling: Tailwind CSS 4.1.14
• Router: React Router DOM 7.9.4
• State Management: Zustand 5.0.8
• Forms: React Hook Form 7.65.0 + Zod 4.1.12
• HTTP Client: Axios 1.12.2
• WebSocket: Socket.io Client 4.8.1
• Icons: Lucide React 0.545.0
• Animations: Framer Motion 12.23.24
• Charts: Recharts 3.3.0
• Testing: Vitest + React Testing Library
• Storybook: 7+ (configurado)

Arquitectura

Feature-Sliced Design (FSD)

src/
├── shared/                 # Código compartido (68 hooks, components reutilizables)
├── services/               # API clients (11 servicios), WebSocket
├── app/                    # Providers (AuthContext, layouts, routing)
│   ├── providers/          # AuthContext, ThemeProvider
│   ├── layouts/            # Layouts de aplicación
│   └── routes/             # Configuración de rutas (18 rutas)
├── features/               # Features de negocio (10 features)
│   ├── auth/               # Autenticación (16 componentes, 5 hooks)
│   ├── gamification/       # Gamificación (74 componentes, 15 hooks)
│   └── mechanics/          # Mecánicas educativas (33 tipos implementados)
└── apps/                   # Aplicaciones (student, teacher, admin)
    └── student/pages/      # 28 páginas implementadas

Rutas Implementadas (React Router v7.9.4)

Públicas (5 rutas)

• /login - Login de usuarios
• /register - Registro de usuarios
• /forgot-password - Recuperación de contraseña
• /reset-password - Reset de contraseña
• /verify-email - Verificación de email

Protegidas (13 rutas)

• / - Redirect a dashboard
• /dashboard - Dashboard principal del estudiante
• /progress - Progreso del estudiante
• /modules/:moduleId - Detalle de módulo educativo
• /exercises/:exerciseId - Ejercicio individual
• /achievements - Logros del estudiante
• /leaderboard - Tabla de clasificación
• /missions - Misiones diarias/semanales
• /profile - Perfil del usuario
• /settings - Configuración
• /friends - Lista de amigos
• /shop - Tienda de ML Coins
• /inventory - Inventario de powerups
• /guilds - Equipos/Gremios

Sistema de Autenticación

Implementado en src/app/providers/AuthContext.tsx:

• Login/Logout con JWT
• Registro de usuarios
• Recuperación y reset de contraseña
• Verificación de email
• Protected routes con componente ProtectedRoute
• Persistencia de sesión en localStorage
• Auto-refresh de token

API Configuration

Definición de Rutas

REGLA OBLIGATORIA: TODAS las rutas API deben estar definidas en: src/services/api/apiConfig.ts

Este archivo es el ÚNICO source of truth para rutas de API. NUNCA hardcodees rutas fuera de apiConfig.ts.

Uso Correcto

✅ CORRECTO:

import { API_ENDPOINTS } from '@/services/api/apiConfig';

// Usar endpoints centralizados
await apiClient.get(API_ENDPOINTS.admin.dashboard.alerts);
await axiosInstance.get(API_ENDPOINTS.teacher.classrooms);
await apiClient.post(API_ENDPOINTS.auth.login, credentials);

❌ INCORRECTO:

// Hardcoded routes - PROHIBIDO
await apiClient.get('/v1/admin/dashboard/alerts');
await axiosInstance.get('/v1/teacher/classrooms');
await apiClient.post('/v1/auth/login', credentials);

// BASE_URL hardcoded - PROHIBIDO
const BASE_URL = '/v1/teacher';
await apiClient.get(`${BASE_URL}/classrooms`);

Agregar Nueva Ruta

1. Agregar a apiConfig.ts:

export const API_ENDPOINTS = {
  admin: {
    newFeature: '/v1/admin/new-feature',
    newFeatureDetail: (id: string) => `/v1/admin/new-feature/${id}`,
  },
};

2. Usar en código:

import { API_ENDPOINTS } from '@/services/api/apiConfig';

// Simple endpoint
await apiClient.get(API_ENDPOINTS.admin.newFeature);

// Endpoint con parámetros
await apiClient.get(API_ENDPOINTS.admin.newFeatureDetail('123'));

Validación Automática

El linter detectará automáticamente rutas hardcodeadas:

npm run lint
# Error: API routes must be imported from apiConfig.ts
# Do not hardcode routes starting with /v1/

Beneficios:

• Cambio centralizado de rutas
• Autocomplete y type safety
• Detección automática de errores
• Fácil refactorización
• Documentación implícita de todos los endpoints

Scripts

npm run dev         # Desarrollo
npm run build       # Build producción
npm run preview     # Preview build
npm test            # Tests
npm run test:ui     # Tests con UI
npm run lint        # Linter
npm run format      # Formatear
npm run storybook   # Storybook dev

Path Aliases

• @/* → src/*
• @shared/* → src/shared/*
• @components/* → src/shared/components/*
• @hooks/* → src/shared/hooks/*
• @utils/* → src/shared/utils/*
• @types/* → src/shared/types/*
• @services/* → src/services/*
• @app/* → src/app/*
• @features/* → src/features/*
• @pages/* → src/pages/*

Features Implementadas

1. Autenticación (auth) - 16 componentes, 5 hooks, 3 stores
2. Gamificación (gamification) - 74 componentes, 15 hooks, 11 stores
3. Mecánicas Educativas (mechanics) - 33 tipos de ejercicios
4. Portal de Estudiante - 28 páginas completas
5. Sistema de Progreso - Tracking y analytics
6. Social Features - Friends, guilds, classrooms

Mecánicas Educativas (33 tipos)

El sistema incluye 33 tipos diferentes de ejercicios implementados en src/features/mechanics/:

• Módulo 1 (Literal): Crucigrama, Línea de Tiempo, Sopa de Letras, Mapa Conceptual, Emparejamiento
• Módulo 2 (Inferencial): Puzzle Contexto, Rueda Inferencias, Construcción Hipótesis, Detective Pistas, Análisis Fotografías
• Módulo 3 (Crítica): Tribunal Opiniones, Matriz Perspectivas, Análisis Fuentes, Debate Deliberativo, Podcast Argumentativo
• Módulo 4 (Digital): Quiz TikTok, Análisis Memes, Fact-Checking, Navegación Crítica, Infográfico Interactivo
• Módulo 5 (Creativo): Ensayo Argumentativo, Video Carta, Call to Action

Testing

• Tests unitarios: 8 archivos
• Coverage actual: ~13% (necesita mejora urgente)
• Coverage objetivo: ≥70%
• Gap: -57 puntos

Tests implementados:

• EmailVerificationPage.test.tsx
• LoginPage.test.tsx
• RegisterPage.test.tsx
• UserManagementPage.test.tsx
• DeactivateUserModal.test.tsx
• authStore.test.ts
• LiveLeaderboard.test.tsx
• useSanitizedHTML.test.ts

Guía de Estilo

• Mobile-first responsive design
• Dark mode support (configurado)
• Accesibilidad WCAG 2.1 AA
• Gamificación integrada en toda la UI
• Animaciones con Framer Motion

Documentación Adicional

• Inventario completo: docs/90-transversal/inventarios/FRONTEND_INVENTORY.yml
• Correcciones aplicadas: Ver sección corrections_2025_11_09 en inventario
• Arquitectura de rutas: Ver sección routing en inventario (18 rutas documentadas)
• Usuarios de prueba: USUARIOS-PRUEBA-2025-11-09.md