Modular Component Ecosystem

Modular Component Ecosystem — Diseño de Módulos Base Reutilizables

Cuándo cargar esta skill

Cuando el usuario pida:

• "Crear piezas reutilizables para construir proyectos más grandes"
• "Módulos base como LEGO para montar ERPs"
• "Extraer código compartido entre proyectos"
• "Crear un ecosistema de componentes como Aurora pero para backend"
• "Diseñar un sistema de paquetes internos"
• "No arrastrar deuda técnica entre proyectos"

Concepto

Crear un ecosistema de paquetes npm internos (@namespace/*) que encapsulen responsabilidades únicas, probadas y reutilizables. Cada proyecto nuevo se construye ensamblando estos módulos, no copiando código.

Analogía: Aurora es el "design system visual" (@nous/aurora). Este skill es el "design system de backend" (@nous/time, @nous/http, etc.).

Principios de diseño

1. Cada módulo = una responsabilidad única — nunca más de una razón para cambiar
2. Zero dependencies entre módulos — cada módulo funciona standalone
3. TypeScript first — tipos para todo, JS vanilla compatible con JSDoc
4. Tests obligatorios — sin tests, no se publica
5. SemVer estricto — breaking changes = nueva versión mayor
6. README con ejemplos — cada módulo tiene "quick start"
7. TODO en castellano — nombres de funciones, docs, comentarios
8. No extraer deuda — si el código fuente tiene bugs, reescribir desde cero

Flujo de trabajo (5 pasos)

Paso 1: Analizar señales de interés

Antes de diseñar módulos, entender hacia dónde va el usuario:

# GitHub stars del usuario — señales de dirección
curl -s "https://api.github.com/users/{USER}/starred?per_page=100&page=1" | \
  python3 -c "
import json, sys
for repo in json.load(sys.stdin):
    print(f\"{repo['full_name']:45s} | ⭐{repo['stargazers_count']:5d} | {repo.get('description','')[:80]}\")
"

Qué buscar en las stars:

• Arquitectura modular/plugin-based → QueAI, NocoBase, Huly
• Multi-tenant/multi-usuario → Twenty, EspoCRM, SuiteCRM
• API integrations → Nango, Postgres MCP
• Data privacy/security → Microsoft Presidio
• 3D + geoespacial → GeoLibre, Three.js, maptalks.three

Paso 2: Auditar proyectos existentes

Analizar los proyectos activos del usuario para identificar:

• Módulos que ya existen (código reutilizable)
• Deuda técnica (código que NO se puede extraer)
• Patrones repetidos entre proyectos (candidatos a módulo)

Comandos clave:

# Estructura de directorios
find /path/to/project -type f -name "*.js" -o -name "*.ts" | head -50

# Líneas por archivo (monolitos)
wc -l /path/to/project/server.js

# Código duplicado entre proyectos
diff -rq /path/to/project1/src /path/to/project2/src | grep "Only in"

Categorizar hallazgos:

Paso 2.5: Auditoría detallada módulo por módulo (Plan vs Código)

Cuando el plan indica módulos basados en código existente, hacer auditoría POR CADA módulo candidato:

Checklist por módulo:

1. ✅ ¿Existe en GitHub? — curl -s "https://api.github.com/users/{USER}/repos?per_page=100" | jq '.[].name' | grep -i "modulo"
2. ✅ ¿Existe en local? — find /root/workspace -type d -name "*{modulo}*" 2>/dev/null
3. ✅ Código fuente real — Leer archivos clave (no asumir, leer línea a línea)
4. ✅ Líneas totales — wc -l source/file.js (monolito o módulo limpio)
5. ✅ Tests existentes — find tests/ -name "*.test.js" -exec wc -l {} +
6. ✅ Calidad del código — Patrones limpios vs deuda técnica
7. ✅ Seguridad — PINs plano, SQL injection, secrets hardcodeados
8. ✅ Dependencias externas — ¿Usa librerías? ¿Se pueden eliminar?

Evaluar cada módulo con semáforo:

Ejemplo de evaluación granular (caso real Adela/ESIOS):

Adela_time   → 🟢 ESIOS madrid.js (215 líneas, 9 funciones, tests 62 líneas, edge cases)
Adela_http   → 🟢 ESIOS esios.client.js (236 líneas, batching+retries+backoff+jitter)
Adela_cache  → 🟢 ESIOS memory-cache.js + disk-cache.js (184 líneas, métricas TTL stats)
Adela_env    → 🟡 ESIOS env.js (35 líneas, funcional pero hardcodea ESIOS_API_TOKEN)
Adela_health → 🟡 ESIOS server.js (~20 líneas healthz/readyz, mínimo pero sirve)
Adela_auth   → 🔴 MasterFit (PINs texto plano, SQL injection potencial, sin bcrypt)
Adela_export → 🟡 ESIOS csv.repository.js (65 líneas, solo CSV, pdfkit en deps sin usar)
Adela_ai     → 🟡 ESIOS report.service.js (210 líneas, específico de ESIOS)
Adela_db     → ❌ No existe en ningún lado
Adela_i18n   → ❌ No existe en ningún lado

Paso 2.6: Detectar fuentes complementarias

A veces el código está distribuido en VARIOS proyectos. Mapear:

### Módulo: Adela_X
| Fuente | Archivo | Líneas | Calidad | 
|--------|---------|--------|---------|
| Proyecto A | src/algo.js | 150 | 🟢 |
| Proyecto B | server.js (líneas 200-250) | 50 | 🟡 |

Para módulos parcialmente existentes, verificar si la funcionalidad está completa o falta algo:

• Adela_export: ESIOS tiene CSV ✅, pero falta PDF (pdfkit está en package.json pero sin usar)
• Adela_ai: ESIOS tiene proxy LLM para NaN, pero solo soporta ESIOS, no genérico
• Adela_auth: MasterFit tiene login/PIN, pero en texto plano = inservible

Paso 2.7: Documentar deuda técnica de los proyectos fuente

No solo evaluar módulos — documentar los problemas ESTRUCTURALES de los proyectos fuente:

Paso 3: Definir módulos

Para cada candidato, definir:

### Módulo: @nous/{nombre}
- **Responsabilidad:** Qué hace (una sola cosa)
- **Funciones públicas:** API exacta (import x from '@nous/nombre')
- **Dependencias:** Ninguna (o stdlib solo)
- **Tests:** Qué cubre
- **Fuente:** De dónde viene (proyecto existente o nuevo)
- **Prioridad:** P0/P1/P2

Ejemplos reales de la sesión:

Paso 4: Decidir arquitectura del ecosistema

Presentar al usuario las decisiones clave:

Paso 5: Template de cada módulo

@nous/{nombre}/
├── package.json          # name: "@nous/{nombre}", version: "1.0.0"
├── README.md             # Quick start + API reference
├── src/
│   ├── index.ts          # Exports públicos
│   ├── impl.ts           # Implementación
│   └── types.ts          # Interfaces públicas
├── tests/
│   └── impl.test.ts      # Tests obligatorios
└── dist/                 # Build output (JS + .d.ts)

Paso 6: Plan de implementación por fases

Después de auditar y definir todos los módulos, crear un plan de implementación PRIORIZADO por semanas/fases. Cada fase debe ser autocontenida y entregar valor tangible.

Criterios de priorización:

Formato del plan por fases:

## Fase 1: P0 — Base (semana 1)
Módulos: Adela_env + Adela_time + Adela_http

### Adela_env — Gestión de ENV con validación
- ✅ Validación estricta con tipos
- ✅ Defaults + required diferenciados
- ✅ Validadores custom (puerto, ruta, regex)
- ✅ Soporte `.env` automático
- 🔧 Código fuente: ESIOS env.js (35 líneas, generalizar)

### Adela_time — Utilidades de tiempo
- Extraer de ESIOS madrid.js (215 líneas, 9 funciones, tests 62 líneas)
- Añadir: isWeekend(), nextBusinessDay(), timeAgo()
- TypeScript + tests al 100%

### Adela_http — Cliente HTTP genérico
- Extraer de ESIOS esios.client.js (236 líneas)
- Hacer genérico: configurable URL, headers, auth
- Mantener: retry con backoff + jitter, timeout, batching

Regla: Cada fase son 7 días reales. NO intentar meter 4 fases en 1 semana. Una semana por fase, y si sobra tiempo, mejorar tests y docs.

Pitfalls

❌ NO extraer código con deuda técnica

Si el código fuente tiene bugs críticos (SQL injection, datos en texto plano, monolito), no extraer. Reescribir el módulo desde cero con buenas prácticas. Extraer deuda = distribuir deuda.

❌ NO crear módulos por crear

Solo crear módulos que usen 2+ proyectos. Si solo un proyecto lo necesita, es código específico, no módulo base.

❌ NO hacer todo de golpe

Empezar con P0 (env, time, http). Validar que el patrón funciona antes de escalar.

✅ SÍ mantener zero dependencies

Cada módulo debe funcionar standalone. Si @nous/http necesita @nous/cache, algo va mal.

✅ SÍ testear cada módulo

Sin tests, no hay contrato verificable. Cada módulo debe tener tests unitarios que cubran la API pública.

✅ SÍ documentar con ejemplos

Cada módulo debe tener un "quick start" en el README con 3-5 líneas de código que demuestren su uso.

Referencias

• references/modular-ecosystem-plan.md — Plan completo de ecosistema @nous/* con 10 módulos propuestos, análisis de GitHub stars, auditoría de proyectos, y decisiones pendientes.
• references/nodejs-multiuser-audit-patterns.md (de system-audit) — Patrones de bugs en apps Node.js multi-usuario, útil para validar módulos antes de extraerlos.

Overlap con otros skills

• refactor-nodejs-monolith — cubre refactorizar un monolito en módulos DENTRO de un proyecto. Este skill cubre crear módulos que COMPARTIR entre proyectos. Complementarios.
• geospatial-asset-platform — cubre la plataforma TerrAn con sus módulos de dominio (residuos, policía, sanidad). Este skill cubre los módulos BASE que TerrAn usaría (env, time, http, auth). Complementarios.
• aurora-nightly — cubre mejora continua nocturna del design system visual. Este skill es el equivalente para el backend. Complementarios.