Saltar a contenido

Arquitectura — EcommerceV2Backend

Visión general

Backend de comercio de Compulandia construido sobre Medusa v2.15.5 (Node ≥ 20, TypeScript). Expone la API de tienda (/store/*), la API de administración (/admin/*) y el dashboard de administración de Medusa, todo desde un mismo proceso. Persiste en PostgreSQL 15 y usa Redis 7 para caché, bus de eventos, motor de workflows y locking. Se despliega como una única imagen Docker publicada en GHCR.

Alcance de este documento: describe el código de las ramas publicadas (main, staging, develop — las tres en 14749d6 al 2026-08-19). Varios documentos de docs/integraciones/ y docs/analisis/ describen módulos (Bancard QR, fulfillment MC Group, notificaciones por email, login con Google) que no están en esas ramas: viven en una línea de trabajo aún no integrada. Están publicados con nota de vigencia y marcados en el triage.

Componentes

Componente Responsabilidad Tecnología
Servidor Medusa API de tienda, API de admin, dashboard y procesamiento asíncrono en un solo proceso (workerMode por defecto: shared) Medusa 2.15.5 / Node 20
Módulo bank-transfer Payment provider propio: pago por transferencia bancaria (src/modules/bank-transfer) Medusa Payment Module
Widgets de admin — listas de precios Alta, búsqueda y edición de variantes y precios especiales dentro de una price list (src/admin) React 18 + Medusa Admin SDK
Rutas API propias /store/custom/products/:id (producto con precio calculado por región), /admin/custom/price-lists/current (src/api) Medusa file-based routing
Subscriber product-created Escucha product.created/updated/deleted; hoy solo loguea (src/subscribers/product-created.ts) Medusa Event Bus
Imagen Docker Build multi-stage: medusa build en el builder, npm install --omit=dev sobre .medusa/server en el runner; arranca con start.sh Docker / node:20-alpine
Pipeline CI/CD Build en GitHub Actions → GHCR → runners self-hosted → deploy.sh con backup y auto-rollback GitHub Actions + GHCR

Dependencias externas

Dependencia Uso ¿Qué pasa si no está?
PostgreSQL 15 (medusa_postgres) Toda la persistencia del comercio El servidor no arranca: db:migrate falla en start.sh y el health check nunca pasa → deploy.sh hace auto-rollback
Redis 7 (medusa_redis) Caché, event bus, workflow engine y locking (los cuatro módulos apuntan a REDIS_URL) Sin Redis el arranque falla o el sistema queda sin eventos, workflows ni locking distribuido
GHCR (ghcr.io/compulandiati/ecommercev2backend) Registry de la imagen desplegable No se puede desplegar ni hacer rollback por tag; lo ya corriendo sigue en pie
GitHub Actions + runners self-hosted Build y despliegue a staging/producción Sin pipeline: el despliegue debe hacerse a mano ejecutando deploy.sh en el servidor
Registry de npm Instalación de dependencias durante el build de la imagen El build de la imagen falla; no afecta a lo desplegado

Diagrama

flowchart LR
    Dev[Desarrollador] -->|push staging / main| GH[GitHub Actions]
    GH -->|docker build + push| GHCR[(GHCR<br/>ecommercev2backend)]
    GH -->|job deploy-*| Runner[Runner self-hosted]
    Runner -->|./deploy.sh| Compose[docker compose]
    GHCR -->|pull tag| Compose
    Compose --> Medusa[medusa_backend<br/>API store + admin]
    Medusa -->|SQL| PG[(PostgreSQL 15)]
    Medusa -->|cache · eventos · workflows · locking| Redis[(Redis 7)]
    Store[Storefront] -->|HTTP /store| Medusa
    Admin[Dashboard admin] -->|HTTP /admin| Medusa

Flujo principal — despliegue de una versión a producción

  1. Se mergea staging en main y se pushea: el job build corre en ubuntu-latest, construye la imagen multi-stage y la publica en GHCR con los tags latest y sha-<7 primeros del commit>.
  2. Un humano dispara Run workflow (workflow_dispatch, environment: production) — el push a main por sí solo no despliega.
  3. El job deploy-prod toma el runner con label ecommerce-srv-production, hace docker login a GHCR con el secret GHCR_PAT y ejecuta ./deploy.sh con MEDUSA_TAG=sha-<7>.
  4. deploy.sh hace pg_dump de la base a ./backups/; si el dump falla, aborta el despliegue.
  5. Etiqueta la imagen en ejecución como rollback-prev, hace pull del tag objetivo y docker compose up -d medusa.
  6. Al arrancar, el contenedor ejecuta start.sh: medusa db:migrate → npm run seed (tolerado si falla) → creación del usuario admin (tolerada si ya existe) → npm run start.
  7. deploy.sh consulta http://localhost:9000/health hasta 30 veces cada 3 s. Si responde 200, el despliegue termina OK; si no, re-levanta rollback-prev y vuelve a verificar.

Configuración

Toda la configuración vive en medusa-config.ts y se alimenta de variables de entorno (.env, fuera de git): DATABASE_URL, REDIS_URL, STORE_CORS, ADMIN_CORS, AUTH_CORS, JWT_SECRET, COOKIE_SECRET. JWT_SECRET y COOKIE_SECRET tienen un valor por defecto inseguro heredado del starter de Medusa: en cualquier ambiente real deben venir del .env.

Pendientes conocidos

  • El repositorio no tiene tests propios más allá del starter de Medusa: el único spec es integration-tests/http/health.spec.ts. El pipeline no ejecuta tests pese al nombre del workflow ("Build, Test & Deploy").
  • npm run seed y la creación del usuario admin corren en cada arranque del contenedor de producción (ver ADR-0002).
  • El split server/worker está diseñado pero no implementado (análisis).