Arquitectura de la plataforma — panorama general¶

Mapa transversal de los tres sistemas. El detalle de cada uno vive en su propia documentación.

Contexto¶

flowchart TB
    Cliente([Cliente]):::actor
    Editor([Editor de contenido]):::actor
    Comercial([Equipo comercial]):::actor
    Integrador([Integrador externo]):::actor

    subgraph Plataforma[" "]
        SF[Storefront<br/>Next.js 15]
        MED[Backend<br/>Medusa 2.15.5]
        CMS[CMS<br/>Payload 3.61]
    end

    Terceros[[Servicios externos<br/>Algolia · Cloudflare Images · Bancard<br/>Google · reCAPTCHA · SMTP]]:::ext

    Cliente --> SF
    Editor --> CMS
    Comercial --> MED
    Integrador -->|sincronización de catálogo| MED

    SF --> MED
    SF --> CMS
    SF --> Terceros
    MED --> Terceros
    CMS --> Terceros

    classDef actor fill:#eef2ff,stroke:#4f46e5,color:#1e1b4b
    classDef ext fill:#f8fafc,stroke:#64748b,color:#0f172a

Aplicaciones¶

Aplicación	Rol	Stack	Repositorio
Storefront	Catálogo, búsqueda, carrito, checkout y cuentas de cliente. Sin persistencia propia	Next.js 15 · App Router · RSC	`EcommerceV2Frontend`
Backend	API de tienda, API de administración, dashboard de admin y procesamiento asíncrono en un único proceso (`workerMode: shared`)	Medusa 2.15.5 · Node 20	`EcommerceV2Backend`
CMS	Panel de administración de contenido y API REST/GraphQL de lectura	Payload 3.61.1 · Next.js 15	`payload-cms`

Componentes internos¶

Sistema	Componente	Rol
Storefront	Middleware de región	Resolución de región y ruteo por `countryCode`
Storefront	Capa de datos `server-only`	Server Actions contra Medusa, Payload y Algolia
Storefront	Módulos de UI	Producto, carrito, checkout, cuenta, búsqueda, envíos, crédito
Storefront	Sesión y caché	Cookies HTTP-only; cache tags de Next scopeados por usuario
Storefront	Lógica propia	Promesa de entrega por sucursal y simulador de cuotas
Backend	Payment provider `bank-transfer`	Cierre de orden sin cobro confirmado; captura manual
Backend	Payment provider `bancard-qr`	QR de la red Bancard, confirmación por webhook, push por SSE
Backend	Fulfillment provider `mc-fulfillment`	Tarifa por tipo de caja, geozona y categorías con precio propio
Backend	Notification provider `email-notification`	SMTP con plantillas propias sobre suscriptores de eventos
Backend	Descuento por medio de pago	Promoción por middleware y hooks de workflow
Backend	Widgets de administración	Listas de precios, geozonas, configuración de envíos, detalle de pago
CMS	Colecciones y globales	`banners`, `sliders`, `main-navigation`, páginas, medios
CMS	Capa de medios	Hooks de colección contra Cloudflare Images; URLs sintetizadas en lectura
CMS	Bloques comerciales	`hero`, `heroSlider`, `productGrid`: esquema sin componente de render

Estado de los componentes del backend¶

Componente	Estado
`bank-transfer`	En producción
Widgets de listas de precios	En producción
`bancard-qr`	En desarrollo
`mc-fulfillment`	En desarrollo
`email-notification`	En desarrollo
Descuento por medio de pago	En desarrollo
Widgets de geozonas, envíos y pago	En desarrollo

3 de 12 funcionalidades en ramas publicadas · Inventario del desarrollo custom

Bases de datos y almacenamiento¶

Almacén	Dueño	Contenido
PostgreSQL — comercio	Backend	Catálogo, precios, stock, carritos, órdenes, clientes, envíos
PostgreSQL — contenido	CMS	Colecciones, globales y referencias a medios
Redis	Backend	Caché, event bus, motor de workflows y locking
Algolia	—	Réplica del catálogo indexada para búsqueda y facetas
Cloudflare Images	CMS	Binarios de imagen

Servicios externos¶

Servicio	Consumidor	Uso	Criticidad
Algolia	Storefront	Búsqueda, autocompletado y resolución de grillas de producto	Alta
Cloudflare Images	CMS (escritura) · navegador (entrega)	Almacenamiento y CDN de medios	Alta
Bancard	Backend	Emisión de QR, confirmación y reversión de pagos	Alta con el provider habilitado
SMTP	Backend	Correo transaccional	Media
Google OAuth	Storefront · Backend	Autenticación federada de clientes	Baja
reCAPTCHA v3	Storefront	Antibot del formulario de crédito	Baja
Stripe · PayPal	Storefront	Sin uso — heredado del starter	—

Integraciones¶

flowchart LR
    N([Navegador])
    SF[Storefront]
    MED[Backend]
    CMS[CMS]
    ALG[(Algolia)]
    CDN[(Cloudflare Images)]
    BAN[(Bancard)]
    INT([Integrador externo])

    N --> SF
    N -->|búsqueda client-side| ALG
    N -->|variantes de imagen| CDN
    N -->|estado de pago en vivo| MED

    SF -->|catálogo · carrito · checkout · clientes · pedidos| MED
    SF -->|contenido y navegación| CMS
    SF -->|resolución de grillas y filtros| ALG

    CMS -->|carga y borrado de binarios| CDN
    MED <-->|emisión y confirmación de pagos| BAN
    INT -->|escritura de productos| MED

Integración	Dirección	Propósito
Storefront ↔ Backend	Bidireccional	Regiones, catálogo, carrito, checkout, clientes y pedidos
Storefront → CMS	Lectura autenticada	Contenido de home, navegación, páginas y formularios
Storefront → Algolia	Lectura	Búsqueda, facetas y resolución de las grillas descritas por el CMS
Navegador → Backend	Lectura en vivo	Cambio de estado de la sesión de pago sin recarga
Navegador → Cloudflare	Lectura	Entrega de variantes de imagen
CMS → Cloudflare	Escritura	Alta y baja de binarios
Backend ↔ Bancard	Bidireccional	Emisión de QR y confirmación por webhook
Integrador externo → Backend	Escritura	Sincronización de catálogo. Equipo externo, fuera de los repositorios relevados
CMS → Storefront	Indirecta	Descriptores de consulta que el storefront resuelve contra Algolia