workspace/projects/gamilit/apps/_MAP.md

_MAP: apps/

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

---

📋 Propósito de esta Carpeta

Esta carpeta contiene todo el código fuente de las aplicaciones GAMILIT, incluyendo backend (API), frontend (SPA), base de datos (DDL/migrations), y scripts de DevOps.

Arquitectura: Monorepo con 4 aplicaciones principales

Audiencia:

• Desarrolladores Backend (Node.js/TypeScript)
• Desarrolladores Frontend (React/TypeScript)
• Database Administrators (PostgreSQL)
• DevOps Engineers
• Tech Leads

---

📁 Estructura de Contenido

Aplicaciones Principales

Aplicación	Propósito	Tecnología	Tamaño	Owner	Estado	_MAP.md
backend/	API REST + WebSocket	Node.js + Express + TypeScript	108 MB	@backend-team	🟢 Activo	⚪ Pendiente
frontend/	SPA Multi-portal	React + Vite + TypeScript	15 MB	@frontend-team	🟢 Activo	⚪ Pendiente
database/	Esquema DB + Migrations	PostgreSQL DDL + SQL	3.8 MB	@database-team	🟢 Activo	⚪ Pendiente
devops/	Scripts DevOps + Validación	TypeScript scripts	60 KB	@devops-team	🟡 Parcial	⚪ Pendiente

---

🗂️ Detalle por Aplicación

backend/ (108 MB)

Descripción: API REST + WebSocket para GAMILIT

Tecnologías:

• Runtime: Node.js 18+
• Framework: Express.js
• Language: TypeScript 5+ (strict mode)
• Database: PostgreSQL 15+ (via node-postgres)
• Testing: Jest
• Linting: ESLint + Prettier
• Process Manager: PM2

Estructura:

backend/
├── src/
│   ├── shared/         # Código compartido (utils, decorators, types)
│   │   ├── constants/  # Constants SSOT (database, routes, enums)
│   │   ├── types/      # Tipos TypeScript compartidos
│   │   ├── utils/      # Utilidades generales
│   │   └── decorators/ # Decoradores personalizados
│   ├── middleware/     # Middleware de Express
│   │   ├── auth.middleware.ts
│   │   ├── validation.middleware.ts
│   │   ├── error.middleware.ts
│   │   └── logging.middleware.ts
│   ├── config/         # Configuraciones
│   │   ├── database.config.ts
│   │   ├── jwt.config.ts
│   │   └── cors.config.ts
│   ├── database/       # Conexión DB, migrations, seeds
│   │   ├── connection.ts
│   │   └── pool.ts
│   ├── modules/        # Módulos de negocio (11 módulos)
│   │   ├── auth/
│   │   ├── educational/
│   │   ├── gamification/
│   │   ├── progress/
│   │   ├── social/
│   │   ├── content/
│   │   ├── admin/
│   │   ├── teacher/
│   │   ├── analytics/
│   │   ├── notifications/
│   │   └── system/
│   └── main.ts         # Entry point
├── __tests__/          # Tests
├── dist/               # Build output
├── logs/               # Application logs
├── node_modules/       # Dependencies (largest folder)
├── package.json        # NPM config
├── tsconfig.json       # TypeScript config
├── jest.config.js      # Jest config
├── .eslintrc.js        # ESLint config
└── README.md           # Documentación

Scripts:

npm run dev         # Desarrollo con hot reload (ts-node-dev)
npm run build       # Build producción
npm run start       # Iniciar producción
npm test            # Ejecutar tests (Jest)
npm run test:cov    # Tests con coverage
npm run lint        # Linter (ESLint)
npm run format      # Formatear código (Prettier)

Path Aliases:

• @shared/* → src/shared/*
• @middleware/* → src/middleware/*
• @config/* → src/config/*
• @database/* → src/database/*
• @modules/* → src/modules/*

Métricas:

• LOC: ~45,000 líneas
• Módulos: 11 módulos funcionales
• Endpoints: 470+ API endpoints
• Tests: ~40 tests (objetivo: 210)
• Coverage: ~15% (objetivo: 70%)

Port: 3000 (default)

Estado: ✅ En producción (desarrollo activo) _MAP.md: ⚪ Pendiente creación

Ver documentación: docs/03-desarrollo/backend/

---

frontend/ (15 MB)

Descripción: SPA Multi-portal con 3 aplicaciones (Student, Teacher, Admin)

Tecnologías:

• Framework: React 18+
• Build Tool: Vite 5+
• Language: TypeScript 5+ (strict mode)
• Styling: Tailwind CSS 3+
• Router: React Router v6
• State Management: Zustand (8 stores)
• Forms: React Hook Form + Zod validation
• HTTP Client: Axios
• Animations: Framer Motion
• Testing: Vitest + React Testing Library
• Storybook: 7+ (component documentation)

Arquitectura: Feature-Sliced Design (FSD)

Estructura:

frontend/
├── src/
│   ├── shared/         # Código compartido (components, hooks, utils)
│   │   ├── components/  # 180+ componentes UI reutilizables
│   │   ├── hooks/       # Custom React hooks
│   │   ├── utils/       # Utilidades generales
│   │   ├── types/       # Tipos TypeScript (sincronizados con backend)
│   │   └── constants/   # Constantes (API endpoints, ENUMs)
│   ├── services/       # API clients, WebSocket
│   │   ├── api/         # API REST clients
│   │   └── websocket/   # Socket.IO client
│   ├── app/            # Providers, layouts, routing
│   │   ├── providers/   # Context providers
│   │   ├── layouts/     # Layout components
│   │   └── router/      # React Router config
│   ├── features/       # Features de negocio (por rol)
│   │   ├── student/     # Portal estudiante
│   │   ├── teacher/     # Portal profesor
│   │   └── admin/       # Portal administrador
│   └── pages/          # Páginas/Vistas
│       ├── student/
│       ├── teacher/
│       └── admin/
├── public/             # Assets estáticos
├── node_modules/       # Dependencies
├── dist/               # Build output
├── package.json        # NPM config
├── vite.config.ts      # Vite config
├── tsconfig.json       # TypeScript config
├── tailwind.config.js  # Tailwind config
├── .storybook/         # Storybook config
└── README.md           # Documentación

Scripts:

npm run dev         # Desarrollo (Vite)
npm run build       # Build producción
npm run preview     # Preview build
npm test            # Tests (Vitest)
npm run test:ui     # Tests con UI
npm run lint        # Linter (ESLint)
npm run format      # Formatear (Prettier)
npm run storybook   # Storybook dev server

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/*

Métricas:

• LOC: ~85,000 líneas
• Componentes: 180+ componentes
• Mecánicas educativas: 33 implementadas
• Zustand stores: 8 (auth, gamification, progress, exercise, notification, social, tenant, ui)
• Tests: ~15 tests (objetivo: 60)
• Coverage: ~13% (objetivo: 70%)

Port: 5173 (Vite default)

Features:

• Mobile-first responsive design
• Dark mode support
• Accesibilidad WCAG 2.1 AA
• PWA ready

Estado: ✅ En producción (desarrollo activo) _MAP.md: ⚪ Pendiente creación

Ver documentación: docs/03-desarrollo/frontend/

---

database/ (3.8 MB)

Descripción: Esquema completo de PostgreSQL, DDL, migrations y seeds

Tecnologías:

• Database: PostgreSQL 16+
• SQL: Pure SQL (DDL)
• Migrations: Custom versioning
• Scripts: Bash + psql

Estructura:

database/
├── ddl/                # Definiciones de esquema (DDL)
│   ├── schemas/        # 9 schemas con objetos DB
│   │   ├── auth_management/      # Autenticación
│   │   │   ├── tables/           # 12 tablas
│   │   │   ├── indexes/          # Índices
│   │   │   ├── functions/        # Funciones
│   │   │   ├── triggers/         # Triggers
│   │   │   └── rls-policies/     # RLS policies
│   │   ├── educational_content/  # Contenido educativo
│   │   ├── gamification_system/  # Gamificación
│   │   ├── progress_tracking/    # Progress tracking
│   │   ├── social_features/      # Social
│   │   ├── content_management/   # CMS
│   │   ├── audit_logging/        # Auditoría
│   │   ├── system_configuration/ # Config
│   │   └── public/               # Schema público
│   ├── base-schema.sql           # Schema base inicial
│   └── README.md                 # Guía de DDL
├── migrations/         # Migraciones versionadas
│   ├── 001_initial_schema.sql
│   ├── 002_add_rls_policies.sql
│   └── ...
├── seeds/              # Datos de prueba
│   ├── dev/            # Seeds para desarrollo
│   └── test/           # Seeds para testing
└── scripts/            # Scripts de mantenimiento
    ├── backup.sh
    ├── restore.sh
    └── migrate.sh

Esquema DB:

• Schemas: 9 (auth_management, educational_content, gamification_system, etc.)
• Tablas: 44 tablas principales
• Índices: 279+ índices (optimización)
• Funciones: 50+ funciones PL/pgSQL
• Triggers: 35+ triggers
• RLS Policies: 159 policies planeadas (41 activas)
• Views: 15+ vistas
• Materialized Views: 5+ (performance)

Sistema de Archivos DDL: Cada schema tiene:

• tables/_MAP.md - Lista de tablas
• indexes/_MAP.md - Índices
• functions/_MAP.md - Funciones
• triggers/_MAP.md - Triggers
• rls-policies/_MAP.md - Políticas RLS
• views/_MAP.md - Vistas

Total _MAP.md en database/: 85+ archivos (sistema SIMCO ejemplar)

Estado: ✅ Bien estructurado y documentado _MAP.md: ⚪ Pendiente creación (raíz de database/)

Ver documentación: docs/03-desarrollo/base-de-datos/

---

devops/ (60 KB)

Descripción: Scripts de DevOps y validación

Tecnologías:

• Language: TypeScript + Bash
• Validaciones: ts-node scripts

Estructura:

devops/
└── scripts/            # Scripts de automatización
    ├── sync-enums.ts               # Sincronizar ENUMs Backend → Frontend
    ├── validate-constants-usage.ts # Detectar hardcoding (33 patrones)
    └── validate-api-contract.ts    # Validar Backend ↔ Frontend sync

Scripts Disponibles (desde root):

npm run sync:enums          # Sincronizar ENUMs Backend → Frontend
npm run validate:constants  # Detectar hardcoding (33 patrones)
npm run validate:api-contract  # Validar Backend ↔ Frontend sync
npm run validate:all        # Todas las validaciones
npm run postinstall         # Auto-sync ENUMs (automático)

Constants SSOT (Single Source of Truth):

• Sistema de constantes centralizadas
• Backend como source of truth
• Sincronización automática a Frontend
• Validación en CI/CD

Estado: 🟡 Funcional pero incompleto Pendiente:

• Docker configs
• CI/CD workflows
• Kubernetes manifests
• Deployment scripts

_MAP.md: ⚪ Pendiente creación

Ver documentación: README.md (root)

---

🔗 Interdependencias

Flujo de Datos

┌────────────────────────────────────────────────────────┐
│                      frontend/                         │
│  React SPA (Student, Teacher, Admin)                   │
│  Port 5173                                             │
└────────────────────┬───────────────────────────────────┘
                     │
                     │ REST API (Axios)
                     │ WebSocket (Socket.IO)
                     │
┌────────────────────▼───────────────────────────────────┐
│                     backend/                            │
│  Express.js API + WebSocket Server                      │
│  Port 3000                                              │
└────────────────────┬───────────────────────────────────┘
                     │
                     │ node-postgres (pg)
                     │ TypeORM (planeado)
                     │
┌────────────────────▼───────────────────────────────────┐
│                    database/                            │
│  PostgreSQL 16+ (9 schemas, 44 tablas)                 │
│  Port 5432                                              │
└────────────────────────────────────────────────────────┘
           ▲
           │ DDL, Migrations, Seeds
           │
     database/ddl/

Interdependencias Entre Apps

backend/ ↔ database/

• Backend consume DDL de database/
• Constants referencian schemas/tablas
• Queries usan funciones PL/pgSQL
• RLS policies enforced en queries

frontend/ ↔ backend/

• Frontend consume API endpoints
• Tipos compartidos (ENUMs sincronizados)
• WebSocket para real-time notifications
• Axios interceptors para auth (JWT)

devops/ → backend/ + frontend/

• Scripts validan consistencia
• Sincronización automática de ENUMs
• Detección de hardcoding
• Validación de contratos API

---

📊 Métricas Globales

Líneas de Código

Aplicación	LOC	Porcentaje
Frontend	~85,000	65%
Backend	~45,000	35%
Database	~10,000 (SQL)	-
DevOps	~500	-
TOTAL	~130,000	100%

Test Coverage

Aplicación	Tests	Coverage	Objetivo
Backend	~40	~15%	70%
Frontend	~15	~13%	70%
TOTAL	~55	~14%	70%

Gap crítico: 55 tests vs 300 objetivo (🔴 81.7% faltante)

Tamaño de Aplicaciones

Aplicación	Tamaño	node_modules	Código
Backend	108 MB	~95 MB	~13 MB
Frontend	15 MB	~10 MB	~5 MB
Database	3.8 MB	-	3.8 MB
DevOps	60 KB	-	60 KB

---

🚨 Issues Conocidos

P0 (Crítico)

• P0-001: Test coverage crítico (14% vs 70% objetivo)
  • Backend: 40 tests (objetivo: 210)
  • Frontend: 15 tests (objetivo: 60)
  • Impacto: Alto riesgo de bugs en producción
  • Esfuerzo: 20-30 horas

P1 (Alto)

• P1-001: Falta _MAP.md en apps principales

  • backend/, frontend/, database/, devops/ sin _MAP.md
  • Impacto: Navegación para agentes incompleta
  • Esfuerzo: 4-6 horas

• P1-002: DevOps incompleto

  • Falta: Docker, CI/CD, Kubernetes
  • Impacto: Deployment manual y propenso a errores
  • Esfuerzo: 10-15 horas

P2 (Medio)

• P2-001: Backend no usa TypeORM

  • Usa node-postgres (pg) directamente
  • Queries SQL manuales propensas a errores
  • Recomendación: Migrar a TypeORM o Prisma

• P2-002: Frontend no implementa PWA

  • PWA ready pero no configurado
  • Service workers no implementados

---

📐 Estándares Aplicables

Nomenclatura de Archivos

Backend/Frontend:

• kebab-case.ts - Archivos de código
• PascalCase.tsx - Componentes React
• camelCase - Variables y funciones
• UPPER_SNAKE_CASE - Constantes

Database:

• kebab-case.sql - Archivos SQL
• 01-nombre-tabla.sql - Con prefijo numérico
• snake_case - Nombres de tablas/columnas

Path Aliases

✅ Todos los proyectos usan path aliases

• Evitar imports relativos (../../../)
• Usar aliases (@shared/*, @modules/*)
• Configurado en tsconfig.json

Linting y Formatting

✅ ESLint + Prettier en todos los proyectos

• Configuración compartida desde root
• Consistent code style
• Pre-commit hooks (planeado)

---

🔍 Validación (Go/No-Go)

Criterios de Aceptación - Apps

• Backend funcional y desplegado
• Frontend funcional y desplegado
• Database schema completo
• Constants SSOT implementado
• Test coverage ≥70% (14% actual) 🔴
• _MAP.md en aplicaciones principales (0/4) 🔴
• DevOps completo (Docker, CI/CD) 🔴
• PWA configurado 🟡

Decisión: 🟡 Parcial GO - Funcional pero con deuda técnica

---

📞 Contacto y Soporte

Owner principal: @tech-lead Maintainers:

• Backend: @backend-team
• Frontend: @frontend-team
• Database: @database-team
• DevOps: @devops-team

Reporte de issues:

• GitHub Issues: [GAMILIT Apps]
• Slack: #gamilit-dev

---

🎯 Próximos Pasos

Fase 1 - Urgente (Esta Semana)

1. ✅ _MAP.md creado (este archivo)
2. ⬜ Crear _MAP.md en 4 aplicaciones principales
3. ⬜ Implementar tests críticos (exercise engine)
4. ⬜ Configurar Docker para desarrollo

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

5. ⬜ Aumentar test coverage a 40%
6. ⬜ Implementar CI/CD básico
7. ⬜ Configurar PWA
8. ⬜ Documentar APIs faltantes

Fase 3 - Media Prioridad (Próximo Mes)

9. ⬜ Test coverage 70%
10. ⬜ Kubernetes manifests
11. ⬜ Migrar a TypeORM (considerar)
12. ⬜ Storybook completo

---

🚀 Quick Start

Desarrollo Local

# 1. Instalar dependencias
npm install  # En root (instala todas las apps)

# 2. Setup database
cd apps/database
psql -U postgres -f ddl/base-schema.sql
# Ejecutar migrations y seeds

# 3. Variables de entorno
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env
# Configurar variables

# 4. Iniciar todo
cd ../..  # Volver a root
npm run dev  # Backend + Frontend concurrentemente

# O iniciar por separado:
npm run backend:dev   # Solo backend (port 3000)
npm run frontend:dev  # Solo frontend (port 5173)

Scripts Globales

# Desde root del monorepo:
npm run dev                 # Backend + Frontend
npm run build               # Build completo
npm run test                # Tests completos
npm run lint                # Lint completo
npm run validate:all        # Validaciones SSOT

---

Generado: 2025-11-07 Método: Sistema SIMCO - Fase 1 (Mapas P0) Próxima actualización: Tras crear submapas Versión: 1.0.0