workspace/projects/gamilit/docs/95-guias-desarrollo/_MAP.md

_MAP: docs/03-desarrollo/

Última actualización: 2025-12-18 Estado: 🟡 En desarrollo (estructura creada, contenido pendiente) Versión: 2.0 (RFC-0001) Propósito: Guías de desarrollo que mapean la estructura del código

---

📋 Propósito de esta Carpeta

Esta carpeta contiene guías de desarrollo que documentan la estructura y organización del código sin invadir las carpetas de código. Es el "mapa externo" del código fuente.

Principio Fundamental: La documentación describe el código desde fuera, NO vive dentro del código.

Enfoque:

✅ CORRECTO:
docs/03-desarrollo/backend/ESTRUCTURA-MODULOS.md
    └─> referencia a: apps/backend/src/modules/

❌ INCORRECTO:
apps/backend/src/modules/_MAP.md

Audiencia:

• Desarrolladores Backend (NestJS, TypeScript)
• Desarrolladores Frontend (React, TypeScript)
• Database Administrators (PostgreSQL)
• DevOps Engineers (Deployment, CI/CD)
• QA Engineers (Testing)
• Nuevos desarrolladores (Onboarding)

---

📁 Estructura de Contenido

Guías por Componente

Carpeta	Propósito	Guías	Código que mapea	Owner	Estado	_MAP.md
backend/	Guías desarrollo backend NestJS	7 planeadas	apps/backend/	@backend-team	🟡 14%	✅ Existe
frontend/	Guías desarrollo frontend React	7 planeadas	apps/frontend/	@frontend-team	🟡 0%	✅ Existe
base-de-datos/	Guías PostgreSQL, migrations	5+	apps/database/	@database-team	🟢 Completo	✅ Existe
database/	(duplicado?)	-	apps/database/	@database-team	⚠️ Revisar	✅ Existe
deployment/	Guías de deployment	3+	DevOps configs	@devops-team	🟡 Parcial	✅ Existe
integraciones/	Guías de integraciones externas	2+	Integraciones	@backend-team	🟡 Parcial	✅ Existe
testing/	Guías de testing	5+	Tests	@qa-team	🟡 Parcial	✅ Existe

Total carpetas: 8 (posiblemente 7 tras consolidación)

---

🗂️ Desglose por Carpeta

backend/ - Guías Backend

Descripción: Guías de desarrollo para el backend NestJS

Código que mapea: apps/backend/ (108 MB, ~45k LOC, 13 módulos)

Contenido actual:

• ✅ GUARDS-Y-SEGURIDAD.md - Guards y seguridad

Guías planeadas (CRÍTICAS):

1. ⚪ ESTRUCTURA-MODULOS.md - Mapa de apps/backend/src/modules/ (11 módulos)
2. ⚪ ESTRUCTURA-SHARED.md - Mapa de apps/backend/src/shared/
3. ⚪ DATABASE-INTEGRATION.md - Integración con PostgreSQL
4. ⚪ API-CONVENTIONS.md - Convenciones de APIs (470+ endpoints)
5. ⚪ SETUP-DESARROLLO.md - Setup local del backend
6. ⚪ ERROR-HANDLING.md - Manejo de errores
7. ⚪ TESTING-BACKEND.md - Testing en backend (Jest)

Total planeadas: 7 guías Total existentes: 1 guía Completitud: 14%

Estado: 🟡 Estructura creada, contenido crítico pendiente

_MAP.md: ✅ Existe

Prioridad: 🔥 ALTA - Sin estas guías, los desarrolladores no pueden navegar los 11 módulos

---

frontend/ - Guías Frontend

Descripción: Guías de desarrollo para el frontend React

Código que mapea: apps/frontend/ (15 MB, ~98k LOC, 483 componentes)

Contenido actual:

• ⚪ Ningún documento útil creado

Guías planeadas (CRÍTICAS):

1. ⚪ ESTRUCTURA-FEATURES.md - Mapa de apps/frontend/src/features/ (student/teacher/admin)
2. ⚪ ESTRUCTURA-SHARED.md - Mapa de apps/frontend/src/shared/components/ (180+ componentes)
3. ⚪ COMPONENTES-UI.md - Catálogo de componentes UI
4. ⚪ STATE-MANAGEMENT.md - Zustand stores (8 stores)
5. ⚪ API-INTEGRATION.md - Integración con backend
6. ⚪ SETUP-DESARROLLO.md - Setup local del frontend
7. ⚪ TESTING-FRONTEND.md - Testing en frontend (Vitest)

Total planeadas: 7 guías Total existentes: 0 guías Completitud: 0%

Estado: 🔴 Estructura creada, sin contenido

_MAP.md: ✅ Existe

Prioridad: 🔥 ALTA - Sin estas guías, imposible navegar 180+ componentes

---

base-de-datos/ - Guías Database

Descripción: Guías de PostgreSQL, migrations, y DDL

Código que mapea: apps/database/ (3.8 MB, 16 schemas, 123 tablas)

Contenido:

• Guías de schemas
• Migrations
• Seeds
• Funciones y triggers

Total guías: ~5

Estado: 🟢 Completo

_MAP.md: ✅ Existe

Nota: Esta carpeta tiene buen contenido (a diferencia de backend/frontend)

---

database/ - (Duplicado?)

Descripción: Posible duplicado de base-de-datos/

Acción recomendada: Consolidar con base-de-datos/ o eliminar

Estado: ⚠️ Revisar duplicación

_MAP.md: ✅ Existe

---

deployment/ - Guías Deployment

Descripción: Guías de deployment y DevOps

Código que mapea: Configuraciones de deployment (planeadas en devops/)

Contenido:

• Guías de deployment
• CI/CD pipelines
• Docker configs

Total guías: ~3

Estado: 🟡 Parcial

_MAP.md: ✅ Existe

---

integraciones/ - Guías de Integraciones

Descripción: Guías de integraciones con servicios externos

Integraciones:

• OAuth providers (Google, Facebook, Apple, Microsoft, GitHub)
• Storage (S3, Cloudflare R2)
• Email (SendGrid, Mailgun)
• Otros servicios externos

Total guías: ~2

Estado: 🟡 Parcial

_MAP.md: ✅ Existe

---

testing/ - Guías de Testing

Descripción: Guías de testing (unit, integration, E2E)

Contenido:

• Unit testing (Jest, Vitest)
• Integration testing
• E2E testing
• Test coverage

Total guías: ~5

Estado: 🟡 Parcial

_MAP.md: ✅ Existe

---

🔗 Interdependencias

Esta Carpeta Mapea (sin invadir):

• apps/backend/ - Guías describen estructura de backend
• apps/frontend/ - Guías describen estructura de frontend
• apps/database/ - Guías describen schemas y DDL

Esta Carpeta Consume De:

• docs/02-especificaciones-tecnicas/ - Especificaciones técnicas
• apps/ - Inspección del código real
• Desarrolladores - Feedback de experiencia

Esta Carpeta Alimenta A:

• Nuevos desarrolladores - Onboarding rápido
• Agentes de IA - Navegación del código
• Documentación - Referencias cruzadas

Flujo de Información:

docs/02-especificaciones-tecnicas/
         ↓
docs/03-desarrollo/ (guías de "cómo desarrollar")
         ↓
    apps/ (código real)

---

📊 Métricas de Guías

Cobertura General

Métrica	Valor
Total carpetas	8
Total archivos .md	127
Guías completadas	~15
Guías planeadas	~35
Completitud	~43%
Archivos _MAP.md	7/8 (88%)

Completitud por Componente

Componente	Guías planeadas	Guías existentes	%
Backend	7	1	14%
Frontend	7	0	0%
Database	5	5	100%
Deployment	3	1	33%
Integraciones	2	1	50%
Testing	5	2	40%

Promedio: ~43% completitud

Impacto del Gap

14 guías críticas faltantes:

• 7 guías backend (mapeo de 11 módulos, 45k LOC)
• 7 guías frontend (mapeo de 180+ componentes, 85k LOC)

Sin estas guías:

• ❌ Desarrolladores nuevos no pueden navegar el código
• ❌ Agentes de IA no tienen contexto de estructura
• ❌ Difícil entender organización de 11 módulos backend
• ❌ Imposible localizar entre 180+ componentes frontend

---

🚨 Issues Conocidos

P0 (Crítico)

• P0-001: Falta contenido crítico en backend/ (86% vacío)

  • Solo 1/7 guías creadas
  • Impacto: No hay mapa de 11 módulos NestJS
  • Esfuerzo: 12 horas (7 guías × 1.5h c/u)

• P0-002: Falta contenido crítico en frontend/ (100% vacío)

  • 0/7 guías creadas
  • Impacto: No hay mapa de 180+ componentes React
  • Esfuerzo: 12 horas (7 guías × 1.5h c/u)

Total P0: 24 horas para resolver gaps críticos

P1 (Alto)

• P1-001: Carpetas duplicadas
  • base-de-datos/ vs database/
  • Impacto: Confusión sobre cuál usar
  • Recomendación: Consolidar en base-de-datos/
  • Esfuerzo: 2 horas

P2 (Medio)

• P2-001: Guías de deployment incompletas
  • Solo 1/3 guías
  • Impacto: Setup de deployment no documentado
  • Esfuerzo: 4 horas

---

📐 Estándares Aplicables

Principio Fundamental

"Documentación Externa Referencia, No Invade"

✅ CORRECTO:
docs/03-desarrollo/backend/ESTRUCTURA-MODULOS.md
    └─> Describe: apps/backend/src/modules/

❌ INCORRECTO:
apps/backend/src/modules/_MAP.md

Formato de Guías

Cada guía debe incluir:

1. Título descriptivo
2. Código que mapea - Path desde raíz del monorepo
3. Propósito - Qué resuelve esta guía
4. Estructura - Organización del código
5. Convenciones - Patrones aplicados
6. Ejemplos - Código de ejemplo
7. Referencias - Enlaces a especificaciones técnicas

Ejemplo:

# ESTRUCTURA-MODULOS.md

## Código que mapea
`apps/backend/src/modules/`

## Propósito
Esta guía documenta los 11 módulos funcionales del backend NestJS.

## Módulos Implementados

| Módulo | Path | Propósito | Endpoints |
|--------|------|-----------|-----------|
| **auth/** | `apps/backend/src/modules/auth/` | Autenticación | 15 |
| **educational/** | `apps/backend/src/modules/educational/` | Contenido educativo | 42 |
...

## Estructura Estándar de un Módulo

modules/{nombre}/ ├── controllers/ ├── services/ ├── dto/ ├── entities/ └── {nombre}.module.ts

## Convenciones
...

Referencias a Código

Formato: Paths absolutos desde raíz del monorepo

**Backend:** `apps/backend/src/modules/auth/`
**Frontend:** `apps/frontend/src/features/auth/`
**Database:** `apps/database/ddl/schemas/auth_management/`

Con números de línea (opcional):

**Enum:** `apps/backend/src/shared/enums/gamilit-role.enum.ts:15-20`

---

🔍 Validación (Go/No-Go)

Criterios de Aceptación

• _MAP.md creado (este archivo) ✅
• 7 carpetas con _MAP.md (100%) ✅
• Guías de database completas ✅
• 14 guías críticas (backend + frontend) (0/14) 🔴
• Carpetas duplicadas consolidadas 🔴
• 80% guías completadas (actual: 43%) 🔴

Decisión: 🔴 NO-GO - Estructura creada pero sin contenido crítico

Blocker: Sin las 14 guías de backend/frontend, los desarrolladores no pueden navegar el código efectivamente.

---

📞 Contacto y Soporte

Owner principal: @tech-lead Maintainers:

• Backend: @backend-team
• Frontend: @frontend-team
• Database: @database-team
• Deployment: @devops-team
• Testing: @qa-team

Reporte de issues:

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

---

🎯 Próximos Pasos (CRÍTICOS)

Fase 1 - URGENTE (Esta Semana) 🔥

1. ✅ _MAP.md creado (este archivo)

2. ⬜ Crear 7 guías backend (12 horas)

   • ESTRUCTURA-MODULOS.md (2h) - CRÍTICA
   • ESTRUCTURA-SHARED.md (1.5h)
   • DATABASE-INTEGRATION.md (2h)
   • API-CONVENTIONS.md (2h)
   • SETUP-DESARROLLO.md (1.5h)
   • ERROR-HANDLING.md (1.5h)
   • TESTING-BACKEND.md (1.5h)

3. ⬜ Crear 7 guías frontend (12 horas)

   • ESTRUCTURA-FEATURES.md (2h) - CRÍTICA
   • ESTRUCTURA-SHARED.md (2h) - CRÍTICA
   • COMPONENTES-UI.md (2h)
   • STATE-MANAGEMENT.md (2h)
   • API-INTEGRATION.md (1.5h)
   • SETUP-DESARROLLO.md (1.5h)
   • TESTING-FRONTEND.md (1.5h)

Total Fase 1: 24 horas → +14 guías críticas

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

4. ⬜ Consolidar base-de-datos/ y database/ (2 horas)
5. ⬜ Completar guías de deployment (4 horas)
6. ⬜ Completar guías de testing (6 horas)
7. ⬜ Actualizar guías con feedback de desarrolladores (4 horas)

Total Fase 2: 16 horas

Fase 3 - Media Prioridad (Próximo Mes)

8. ⬜ Crear guías avanzadas (arquitectura, patterns) (10 horas)
9. ⬜ Automatizar generación de mapas desde código (16 horas)
10. ⬜ Integrar guías en onboarding (4 horas)

Total Fase 3: 30 horas

---

🚀 Navegación Rápida

Para Nuevos Desarrolladores

# Setup inicial
cat docs/03-desarrollo/backend/SETUP-DESARROLLO.md
cat docs/03-desarrollo/frontend/SETUP-DESARROLLO.md

# Entender estructura
cat docs/03-desarrollo/backend/ESTRUCTURA-MODULOS.md
cat docs/03-desarrollo/frontend/ESTRUCTURA-FEATURES.md

# Testing
cat docs/03-desarrollo/testing/

Para Desarrolladores Activos

# Buscar módulo específico
cat docs/03-desarrollo/backend/ESTRUCTURA-MODULOS.md

# Encontrar componente
cat docs/03-desarrollo/frontend/COMPONENTES-UI.md

# Integración con DB
cat docs/03-desarrollo/backend/DATABASE-INTEGRATION.md

Para Agentes de IA

# Leer mapa de backend
cat docs/03-desarrollo/backend/ESTRUCTURA-MODULOS.md

# Leer mapa de frontend
cat docs/03-desarrollo/frontend/ESTRUCTURA-FEATURES.md

# Referencias a código real
# (los paths en las guías apuntan a apps/)

---

📚 Recursos Adicionales

Documentación relacionada:

• Especificaciones técnicas: ../02-especificaciones-tecnicas/
• Arquitectura: ../02-especificaciones-tecnicas/arquitectura/
• APIs: ../02-especificaciones-tecnicas/apis/

Código fuente:

• Backend: apps/backend/
• Frontend: apps/frontend/
• Database: apps/database/

Repositorios de código:

• Monorepo raíz: /home/isem/workspace/workspace-gamilit/gamilit/projects/gamilit/

---

⚠️ ADVERTENCIA IMPORTANTE

Esta carpeta NO debe contener _MAP.md dentro de apps/

El código debe permanecer libre de documentación SIMCO.

Solo docs/ contiene _MAP.md y referencias al código.

---

Generado: 2025-12-18 Método: Sistema SIMCO - Fase 1 (Mapas P0) Próxima actualización: Tras crear 14 guías críticas Versión: 1.0.0