Sección 01

01 · La arquitectura Shopify

Las cinco superficies, OAuth, webhooks — mapa mental.

En una frase

Shopify no es una plataforma monolítica donde todo tu código vive en el mismo lugar. Es un sistema de cinco superficies independientes — cada una con su propio runtime, sus propias APIs, sus propias reglas de seguridad y su propio proceso de publicación. La confusión más común entre desarrolladores nuevos en Shopify es tratar al ecosistema como si fuera uno solo.

Qué es y por qué existe

Cuando alguien dice “desarrollar en Shopify”, la pregunta correcta es: ¿en qué parte de Shopify? La respuesta cambia todo: el lenguaje que vas a usar, cómo se despliega, quién lo consume, qué APIs tienes disponibles y qué restricciones de seguridad aplican.

Shopify nació como una plataforma de e-commerce en 2006. Durante los primeros años, “desarrollar en Shopify” significaba una sola cosa: escribir templates en Liquid para el storefront público. Eso bastó hasta que los comerciantes empezaron a pedir personalización del checkout, automatización de pedidos, lógica de descuentos propia, y experiencias de compra fuera del storefront de Shopify. Cada una de esas necesidades requería un tipo de extensión diferente, con garantías de seguridad diferentes.

El resultado es una arquitectura multi-superficie donde Shopify controla las fronteras: tú extiendes desde adentro usando los puntos de extensión que Shopify provee para cada superficie. No accedes a la base de datos directamente. No puedes modificar el HTML del checkout con JavaScript arbitrario. No puedes leer cookies de sesión del admin. Estas restricciones no son descuidos de diseño: son el núcleo del modelo de seguridad que le permite a Shopify garantizar que tu extensión no rompe la plataforma del comerciante.

Las cinco superficies

Storefront (themes)

El storefront es la tienda pública que ven los visitantes. Se sirve desde la CDN de Shopify y se construye con Liquid — un lenguaje de templates server-side — más archivos JSON de configuración, assets estáticos y secciones declarativas.

Cuando desarrollas un theme, entregas código Liquid directamente al store del comerciante. No hay servidor tuyo corriendo en producción: Shopify renderiza todo. El comerciante puede personalizar el theme desde el Theme Editor sin tocar código.

El storefront es la superficie más madura del ecosistema. Online Store 2.0 (lanzado en 2021) modernizó su modelo de composición con JSON templates, sections everywhere y theme blocks. La sección 04 cubre esto en profundidad.

Admin

El admin es la interfaz del comerciante: donde gestiona productos, pedidos, clientes, descuentos, y configuraciones. Tú, como desarrollador de apps, puedes embeber interfaces dentro del admin usando iframes que se renderizan como páginas dentro del panel. Eso se logra con App Bridge (la librería de JavaScript de Shopify para comunicación host-iframe) y autenticación por session tokens.

El admin no es un espacio donde puedas “instalar un widget”: los renders de tu app dentro del admin son páginas completas que Shopify controla. Tu app vive en tu servidor — Shopify solo carga un iframe apuntando a tu URL.

Checkout

El checkout es la superficie más restringida del ecosistema. Es donde el dinero cambia de manos, y Shopify no permite código arbitrario ahí. No puedes modificar el checkout con JavaScript externo, con scripts de theme, ni instalando un snippet de Liquid.

La única forma de extender el checkout es con Checkout UI Extensions: componentes declarativos escritos en JavaScript/TypeScript que se ejecutan en un sandbox aislado dentro del proceso de checkout de Shopify. Tienes acceso a un conjunto limitado de APIs para leer y modificar datos del carrito, mostrar mensajes y UI controlada. Lo que no puedes hacer: acceder al DOM directamente, ejecutar código de terceros sin auditoría, o modificar el flujo de pago.

Esta restricción es intencional. Un checkout confiable es la diferencia entre que el comerciante mantenga el negocio o no.

Customer Accounts

Las Customer Accounts son el portal autenticado donde los clientes gestionan sus pedidos, suscripciones, devoluciones y datos de cuenta. Shopify lanzó una versión completamente nueva de esta superficie en 2024, que en 2026 ya está en GA. La versión legacy está deprecada — este tutorial solo cubre las nuevas.

Las nuevas Customer Accounts se extienden con Customer Account UI Extensions: mismo modelo de sandbox que el checkout, pero con acceso a APIs específicas del contexto del cliente autenticado (historial de pedidos, metafields del cliente, etc.).

Headless (storefronts fuera de la CDN de Shopify)

Un storefront headless es cualquier frontend que consume la Storefront API de Shopify pero se despliega en infraestructura propia. El comerciante tiene los datos en Shopify, pero la experiencia de compra la controlas tú completamente.

Shopify tiene su propio stack headless oficial: Hydrogen (basado en React Router v7 desde septiembre de 2025, versión 2026.4.0) desplegado en Oxygen (el runtime de Shopify para storefronts headless). Puedes usar cualquier otro framework o lenguaje llamando a la Storefront API directamente, pero Hydrogen + Oxygen es el camino con menos fricción.

La sección 15 cubre Hydrogen en detalle.

Los dos modos de construir

Hay dos maneras distintas de contribuir código a Shopify, y la distinción es importante:

Themes: entregas archivos Liquid, JSON, CSS y JavaScript directamente al store del comerciante. No hay OAuth. No hay servidor tuyo en producción (salvo que uses un servidor proxy para datos externos, lo cual es avanzado). El code delivery es el código mismo. Los themes se distribuyen por el Theme Store de Shopify o se instalan directamente en el store.

Apps: tienes un servidor propio que habla con Shopify por OAuth. Shopify instala tu app en el store del comerciante y te otorga un access token. Tus extensiones — UI del admin, UI del checkout, Theme App Extensions, Functions — todas están empaquetadas dentro de la app. Las apps se distribuyen por el App Store de Shopify o se instalan directamente (custom apps).

Un proyecto puede necesitar ambas cosas. Brew Atlas tiene un theme y una app: el theme controla el storefront, la app gestiona la lógica de suscripciones y extiende el checkout.

Infraestructura transversal

Tres conceptos atraviesan todas las superficies:

Webhooks: cuando algo ocurre en Shopify (se crea un pedido, se actualiza un producto, un cliente cancela su suscripción), Shopify puede enviar un HTTP POST a tu servidor con los datos del evento. Tu servidor procesa el evento de forma asíncrona. Los webhooks son la base de cualquier integración real-time entre Shopify y sistemas externos.

Metafields y metaobjects: Shopify tiene un modelo de datos fijo para sus entidades (productos, clientes, pedidos, colecciones). Cuando necesitas datos adicionales — el origen del grano de café, la frecuencia de suscripción, la puntuación de tueste — los agregas como metafields en una entidad existente, o como metaobjects (entidades completamente nuevas). Son la plataforma de contenido de Shopify. Las secciones 06 y 07 lo cubren en profundidad.

GraphQL APIs: tanto la Storefront API como la Admin API son GraphQL. No hay REST equivalente con el mismo nivel de funcionalidad. REST está deprecado en la práctica para código nuevo. Conocer GraphQL no es opcional.

Puentes mentales

Desde Angular/React

Angular y React tienen un runtime. Shopify tiene cinco. El mapeo más útil es este: Storefront es tu ruta pública, la que consume el navegador del visitante sin autenticación. Admin es el portal administrativo autenticado, como un backoffice protegido por roles. Checkout es un microservicio de pagos en sandbox — no puedes inyectarle código libremente, igual que no inyectarías JavaScript arbitrario en el form de pago de Stripe. Customer Account es el dashboard del usuario autenticado, comparable a la sección “Mi cuenta” de cualquier app. Headless es el SPA completamente custom que consume una API — la misma Storefront API que usa el theme, pero desde tu propio servidor.

Cada superficie tiene su propio framework, sus propias reglas y sus propios límites. Si vienes de un ecosistema donde todo tu código convive en el mismo bundle, el salto conceptual principal es aceptar que aquí hay fronteras duras entre superficies.

Estado 2026

Las novedades de mayor impacto en los últimos 12 meses:

Hydrogen migró de Remix a React Router v7 en septiembre de 2025. Si ves tutoriales que mencionan “Remix + Hydrogen”, están desactualizados. El CLI todavía ofrece la opción “remix” al hacer scaffold, pero el proyecto generado usa React Router v7.
Theme Blocks son el primitivo actual para themes. El modelo de section blocks locales sigue funcionando, pero el ecosistema se está moviendo al modelo de blocks reutilizables que viven en /blocks/. Horizon, el tema de referencia de Shopify lanzado en 2025, está construido completamente sobre theme blocks.
Customer Accounts legacy está deprecada. Si ves documentación sobre “Customer Accounts v1”, ignórala. Las nuevas Customer Accounts (GA desde 2024) son el camino.
API versioning: las APIs de GraphQL siguen el cadence trimestral. La versión estable actual es 2026-04, la RC es 2026-07.

Shopify.dev — hub de documentación oficial rev: 2026-04

La matriz de decisión: ¿qué superficie necesito?

Esta es la pregunta que te vas a hacer al inicio de cada proyecto o feature. Respóndela en orden:

¿El usuario final es un visitante anónimo comprando en la tienda? → Storefront (theme) o headless (Hydrogen + Storefront API).

¿El usuario es el comerciante gestionando su negocio? → Admin app con App Bridge + Polaris.

¿La funcionalidad vive dentro del proceso de pago? → Checkout UI Extension (solo opción posible).

¿El usuario es un cliente autenticado gestionando su cuenta post-compra? → Customer Account UI Extension.

¿Necesitas lógica de negocio que corra del lado de Shopify — descuentos, personalización del carrito, filtros de pago? → Shopify Functions (Rust o JavaScript).

¿El comerciante quiere un storefront completamente custom sin las restricciones del sistema de themes? → Headless con Hydrogen en Oxygen, o cualquier stack consumiendo la Storefront API.

Un proyecto real típicamente toca más de una superficie. Brew Atlas toca las cinco: theme para el storefront principal, app para gestión de suscripciones, checkout extension para el selector de frecuencia, customer account UI para autoservicio, y Hydrogen para la réplica headless.

Sintaxis y anatomía

No hay código de plataforma en esta sección — el objetivo es el mapa mental, no la implementación. Pero vale la pena ver cómo Shopify nombra las piezas en su documentación, porque el vocabulario importa:

Surfaces (superficies)
├── Online Store (storefront)        → themes, theme app extensions
├── Admin                            → embedded apps, admin extensions
├── Checkout                         → checkout UI extensions
├── Customer Accounts (new)          → customer account UI extensions
└── Headless                         → Hydrogen / Storefront API
 
APIs
├── Storefront API (GraphQL)         → acceso público, no requiere OAuth
├── Admin API (GraphQL)              → acceso autenticado, requiere OAuth + scopes
└── Partner API (GraphQL)            → gestión de apps y partners
 
App infrastructure
├── OAuth 2.0                        → instalación de apps en stores
├── Session tokens (HMAC)            → autenticación de requests embed-to-server
├── Webhooks                         → eventos asincrónicos de Shopify → tu servidor
└── Functions (Wasm)                 → código tuyo corriendo dentro de Shopify

La estructura en árbol de arriba no es de ningún archivo de configuración — es un modelo mental. Úsalo como referencia cuando no sepas dónde vive algo.

Proyecto · Brew Atlas

Brew Atlas · Paso 1

En esta sección no hay código de plataforma que agregar al repositorio. Lo que sí existe es una decisión de arquitectura: Brew Atlas va a tocar las cinco superficies de Shopify. Esa decisión necesita estar documentada antes de escribir una sola línea de código, porque determina qué scaffolds vamos a crear, qué APIs vamos a llamar, y qué curva de aprendizaje nos espera.

El archivo brew-atlas/ARCHITECTURE.md documenta esa decisión con el razonamiento.

El documento de arquitectura ya está en el repositorio en brew-atlas/ARCHITECTURE.md. No es un documento de diseño exhaustivo — es la respuesta a “¿por qué este proyecto usa estas cinco superficies y no menos?”, escrita antes de que el proyecto exista para que cualquier colaborador entienda el scope desde el primer commit.

Errores comunes

Cuidado

El error más frecuente al empezar con Shopify es asumir que un tema puede modificar el checkout. No puede. El checkout es una superficie separada con acceso restringido. Si el cliente pide “cambiar el diseño del checkout” o “agregar un campo en el checkout”, la respuesta es una Checkout UI Extension — no hay otra opción soportada.

Nota

Los scripts de theme (JavaScript incluido en el theme) no tienen acceso al checkout. Tampoco los snippets de Liquid. El HTML del checkout no es parte del DOM del theme. Esta separación existe desde que Shopify introdujo Checkout Extensibility y reemplazó el modelo antiguo de Script Editor.

Tip

Antes de empezar cualquier proyecto de Shopify, dibuja las cinco superficies y marca cuáles vas a tocar. Eso determina qué necesitas aprender primero. Si solo tocas el storefront, puedes ignorar App Bridge, Functions y Customer Accounts por ahora. Si el proyecto requiere lógica de descuentos custom, Functions es obligatoria desde el día uno.

Checklist senior

Puedes nombrar las cinco superficies de Shopify y decir en una oración qué corre en cada una
Sabes distinguir entre un theme y una app, y cuándo necesitas cada uno
Entiendes por qué el checkout está aislado y cuál es la única forma soportada de extenderlo
Puedes explicar para qué sirven los webhooks y en qué se diferencian de una API call
Sabes qué son los metafields y cuándo usarlos en lugar de un campo de producto estándar
Conoces la diferencia entre Storefront API y Admin API en términos de autenticación
Dado un requisito de negocio, puedes identificar en cuál de las cinco superficies vive la solución

La siguiente sección configura el entorno completo: Partner account, dev store, Shopify CLI 3.x, y los scaffolds iniciales de Brew Atlas. Es trabajo de setup — tedioso pero necesario — y vale la pena hacerlo bien desde el principio para no tener que reconfigurarlo en el peor momento.