Este documento describe formalmente todas las tecnologías, frameworks, utilidades y servicios integrados en el ciclo de vida del proyecto Pokédex (Desarrollo, CI/CD, Seguridad de la Cadena de Suministro, Infraestructura y Observabilidad).
- Diagrama de Flujo del Ecosistema de Herramientas
- Matriz Exhaustiva de Herramientas del Proyecto
- Hoja de Ruta Tecnológica y Evoluciones Recomendadas
flowchart LR
subgraph PLAN["1. Plan & Track"]
LINEAR["📋 Linear\n(Tickets PEX-X)"]
SLACK["💬 Slack\n(ChatOps & Alertas)"]
LINEAR -. "Alertas automáticas" .-> SLACK
end
subgraph CODE["2. Code & Test"]
TS["🟦 TypeScript 7.x\nNode.js 22 LTS"]
ESBUILD["⚡ esbuild"]
TASK["⚙️ Taskfile\n(go-task)"]
TESTS["🧪 Node Test Runner\n(63 Tests + 7 Fuzz Tests)"]
end
subgraph SECURE_BUILD["3. Build & Supply Chain"]
DOCKER["🐳 Docker 27+"]
GITLEAKS["🔐 Gitleaks"]
SEMGREP["🔍 Semgrep SAST"]
DEP_REV["📦 Dependency Review"]
TRIVY["🛡️ Trivy SCA"]
SYFT["📋 Syft (SBOM)"]
COSIGN["✍️ Cosign Keyless\n(Sigstore OIDC)"]
end
subgraph DEPLOY["4. GitOps & Admission"]
GHCR["📦 GitHub Packages\n(ghcr.io)"]
ARGO["☸️ ArgoCD"]
HELM["⎈ Helm 3.17"]
KYVERNO["🛡️ Kyverno Enforcer"]
ESO["🔐 External Secrets Operator\n& Sealed Secrets"]
end
subgraph RUNTIME["5. Runtime & Observe"]
K8S["☸️ K8s 1.30+ / Proxmox"]
PGB["🛡️ PgBouncer 1.22"]
PG["🗄️ PostgreSQL 16"]
REDIS["⚡ Redis 7"]
PROM["📊 Prometheus"]
GRAFANA["📉 Grafana"]
LOKI["📋 Grafana Loki"]
end
PLAN --> CODE --> SECURE_BUILD --> DEPLOY --> RUNTIME
classDef plan fill:#3b82f6,stroke:#1d4ed8,color:#fff;
classDef code fill:#6366f1,stroke:#4338ca,color:#fff;
classDef sec fill:#ea580c,stroke:#c2410c,color:#fff;
classDef dep fill:#10b981,stroke:#047857,color:#fff;
classDef run fill:#0891b2,stroke:#0e7490,color:#fff;
class PLAN plan;
class CODE code;
class SECURE_BUILD sec;
class DEPLOY dep;
class RUNTIME run;
| Herramienta | Versión | Rol Arquitectónico | Archivo / Configuración |
|---|
| Node.js | 22 LTS | Runtime del servidor de aplicaciones backend | Dockerfile, package.json |
| Express | 4.22+ | Framework HTTP para rutas REST, middlewares y validaciones | server.ts |
| TypeScript | 7.x | Lenguaje de tipado estático estricto y modelos de dominio | tsconfig.json, src/types.ts |
| esbuild | 0.28+ | Empaquetador ultrarrápido a formato CommonJS para producción | package.json |
| Herramienta | Versión | Rol Arquitectónico | Archivo / Configuración |
|---|
| TypeScript + Vite / HTML5 / CSS3 | Vite 6 / TS 7 | Interfaz reactiva SPA con TypeScript, sanitización DOMPurify y filtros | apps/frontend/ |
| Nginx | 1.27 Alpine | Servidor web proxy inverso con gzip, cabeceras CSP y digest pinned | apps/frontend/nginx.conf, apps/frontend/Dockerfile |
| Herramienta | Versión | Rol Arquitectónico | Archivo / Configuración |
|---|
Google AI Studio (@google/genai) | SDK oficial | Integración nativa con Gemini 2.5 Flash para diagramas y mockups | src/services/ai.ts |
| Herramienta | Versión | Rol Arquitectónico | Archivo / Configuración |
|---|
Node Test Runner (node:test) | Nativo Node 22 | Suite de 63 pruebas unitarias, de integración, seguridad y pentesting | tests/ |
| Fuzz Testing Suite | Script custom | 7 pruebas dinámicas de resistencia con payloads malformados (test:fuzz) | tests/fuzz/ |
| k6 (Grafana k6) | Latest | Pruebas de estrés y benchmarking declarativo de endpoints | tests/performance/k6_stress_test.js |
TypeScript Compiler (tsc) | 7.x | Quality gate de verificación estricta de tipos (npm run lint) | package.json |
| Herramienta | Versión | Rol Arquitectónico | Archivo / Configuración |
|---|
| Docker & Buildx | 27+ | Compilación multi-stage en Alpine con usuario no-root UID 1001 | Dockerfile |
| Docker Compose | v2 | Orquestación local multicontenedor (Web, API, Postgres, Redis) | docker-compose.yml |
| Helm | 3.17 | Empaquetado y parametrización de despliegue en Kubernetes | infra/helm/pokedex/ |
| Argo CD | Latest | Motor GitOps para sincronización declarativa continua en clúster | gitops/apps/ |
Para evitar duplicidad y clarificar el origen de cada señal hacia Grafana Cloud:
| Señal / Dominio | Componente Emisor | Mecanismo | Destino en Grafana Cloud |
|---|
| Métricas de Aplicación (RED & Negocio) | pokemon-api | Endpoint HTTP /metrics (prom-client nativo) | Prometheus / Metrics |
| Métricas de Host & Sistema Operativo | node-exporter | DaemonSet recolector de CPU, RAM, disco y red física | Prometheus / Metrics |
| Métricas de Contenedores y Pods | kube-state-metrics / cAdvisor | Métricas de estado de objetos K8s y límites de Pods | Prometheus / Metrics |
| Trazas Distribuidas L7 (eBPF) | grafana-beyla | Auto-instrumentación en espacio de kernel Linux (HTTP/gRPC) | Tempo / Traces |
| Logs de Aplicación y Contenedores | grafana-alloy (DaemonSet) | Lector directo de logs del sistema de archivos (/var/log/pods) | Loki / Logs |
| Agregación y Forwarding OTLP | grafana-alloy | Receptor OTLP en :4317 hacia endpoint SaaS | Grafana Cloud Fleet Management |
| Herramienta | Versión | Rol Arquitectónico | Archivo / Configuración |
|---|
| Taskfile (go-task) | 3.x | Automatizador de comandos multiplataforma (task dev, task audit) | Taskfile.yml |
| Linear | — | Gestión ágil de proyectos con convención estricta de ramas y linkbacks | .github/pull_request_template.md |
| Renovate Bot | Latest | Gestión unificada de dependencias multi-gestor, cooldown de 7 días, ventanas semanales y auto-merge restringido a npm patch | renovate.json |
| Grafana Cloud | SaaS | Telemetría Kubernetes cloud-native vía Grafana Alloy, Beyla eBPF, Node Exporter y Kube-State-Metrics | infra/monitoring/grafana-cloud-values.yaml |
| Grafana MCP Server | Latest | Integración Model Context Protocol (mcp-grafana) para interacción con dashboards, métricas y alertas desde el IDE | .vscode/mcp.json |
Tomando como base las características identificadas en el repositorio, se establecen las herramientas, mejoras a nivel de lenguaje y evoluciones de arquitectura recomendadas para subsanar riesgos remanentes y elevar la madurez operacional de la plataforma Pokédex:
- Drizzle ORM / Prisma: La inicialización actual con
init.sql y seed.ts carece de versionado atómico. La adopción de un ORM o Query Builder moderno provee tipado estricto extremo a extremo (type-safe SQL), parametrización garantizada contra SQLi y migraciones declarativas reproducibles ejecutables desde el seed-job.yaml de Kubernetes.
- Atlas / Flyway: Gestión declarativa del control de versiones del esquema relacional de PostgreSQL integrada directamente en la tubería de CI/CD previo al despliegue productivo.
- Cockatiel / Opossum: Librerías especializadas para la gestión avanzada de políticas de reintento con backoff exponencial, fallbacks y Circuit Breaker en
services/ai.ts, previniendo el agotamiento de sockets de Node.js ante degradaciones de red del proveedor de IA.
- BullMQ: Desacoplamiento de tareas asíncronas pesadas (inferencia multimodal, generación de mockups y reportes masivos) mediante colas de trabajo respaldadas por la instancia existente de Redis (
redis-deployment.yaml).
- OpenTelemetry SDK para Node.js: Complementa los scrapers de Prometheus (
infra/monitoring/alerts.yml) inyectando instrumentación distribuida de traces con propagación de traceId desde el Ingress de Nginx hasta las consultas de PostgreSQL y Redis.
- Pino: Reemplazo de logs estándar de consola por registros JSON estructurados con niveles jerárquicos y correlación de contexto por petición HTTP.
- Turborepo / Nx: Orquestación eficiente de los espacios de trabajo
apps/backend y apps/frontend, habilitando compilación en paralelo, verificación de tipos y caché distribuida de tareas en CI.
- Vite: Empaquetador ultrarrápido para modernizar la capa de presentación web, habilitando minificación, módulos ES nativos, tree-shaking y sustitución de scripts directos en el DOM.
- Migración a TypeScript Estricto en Frontend: Conversión de
pokedex.js, backoffice.js y theme.js a TypeScript bajo "strict": true, eliminando errores de acceso a propiedades no definidas (undefined / null) en tiempo de ejecución.
- Paquete Compartido de Contratos (
@pokedex/contracts): Extracción de interfaces y tipos de datos desde apps/backend/src/types.ts hacia un módulo interno reutilizable por frontend y backend, garantizando sincronización exacta de modelos de datos.
- Zod / Valibot: Reemplazo de las validaciones ad-hoc en
apps/backend/src/validation/pokemon.ts por esquemas Zod con inferencia automática (type Pokemon = z.infer<typeof PokemonSchema>), filtrado estricto de campos no declarados (strip unknown) y reutilización bidireccional en formularios web y API.
neverthrow (Patrón Result / Either): Sustitución de try/catch no estructurados en services/db.ts y services/auth.ts por tipos Result<T, AppError>, forzando en tiempo de compilación el manejo exhaustivo de fallos (entidad no encontrada, credencial inválida, timeout).
- Desacoplamiento Estricto en Capas:
- Capa de Infraestructura: Adaptadores para PostgreSQL, Redis, HTTP Express y cliente Gemini AI.
- Capa de Dominio: Entidades puras de negocio y reglas de validación de Pokémon, independientes de librerías externas.
- Capa de Aplicación / Casos de Uso: Casos de uso atómicos (registro de criaturas, autenticación, cálculo de estadísticas y generación de arte).
- Beneficio: Testabilidad unitaria completa mediante mocks en memoria sin dependencia forzada de bases de datos en tests locales.
- Adopción de Componentes Reactivos (Lit / Preact / React): Sustitución de mutaciones imperativas del DOM (
innerHTML) por un árbol declarativo de componentes. Erradica estructuralmente el riesgo de inyección XSS al delegar la sanitización y escape en el motor de renderizado.
- Guardrails y Delimitación Estricta: Aislamiento total del contexto del sistema frente a datos ingresados por usuarios en
services/ai.ts mediante delimitadores XML (<user_prompt>) y filtrado semántico previo.
- Caché Semántica con Redis: Almacenamiento con TTL de respuestas generativas recurrentes para reducir latencia a menos de 5 ms y abatir costos operativos de API.
- Backend Remoto Cifrado para OpenTofu: Configuración de backend centralizado (S3 / MinIO con cifrado en reposo SSE y bloqueo de concurrencia) en
infra/opentofu/environments/, evitando la retención de secretos de infraestructura en archivos .tfstate locales.
- Inyección Efímera de Secretos: Retiro de scripts Bash imperativos en favor de Ansible con
infra/ansible/deploy_excludes.txt y External Secrets Operator / Sealed Secrets en Kubernetes para consumir credenciales únicamente vía variables de entorno efímeras y vaults centralizados.