architecture-well-architected-commerce
Well-Architected Commerce on VTEX
When this skill applies
Use this skill when the task is cross-cutting or decision-oriented across VTEX commerce capabilities — not when a single product skill already fully defines the work.
- Defining or reviewing solution architecture (storefront model + integrations + operations).
- Choosing between native VTEX capabilities and custom services (IO apps, external BFFs, middleware).
- Running an architecture or readiness review (security baseline, scalability posture, observability, delivery process).
- Scoping work that will span FastStore, Headless, VTEX IO, Marketplace, Payments and/or any other VTEX module.
Do not use this skill as a substitute for product skills when the task is already localized (e.g. “implement PPP refunds” → payment track; “Feed v3 vs Hook” → marketplace track).
Three pillars (framework)
These pillars are the Well-Architected Commerce lens for every architecture choice. Summaries below follow the internal framework narrative; for full objectives, core values, and critical areas of focus, use the Well-Architected Commerce MCP (and your program’s canonical framework document).
Technical Foundation
More from vtex/skills
vtex-io-react-apps
Apply when building React components under react/ or configuring store blocks in store/ for VTEX IO apps. Covers interfaces.json, contentSchemas.json for Site Editor, VTEX Styleguide for admin apps, and css-handles for storefront styling. Use for creating custom storefront components, admin panels, pixel apps, or any frontend development within the VTEX IO react builder ecosystem.
270vtex-io-masterdata
Apply when working with MasterData v2 entities, schemas, or MasterDataClient in VTEX IO apps, or when anyone designing or implementing a solution must scrutinize whether Master Data is the correct storage. The skill prompts hard questions: native Catalog or other VTEX stores, OMS, or an external database may be better; do not default to MD because it is convenient. Covers JSON Schema, CRUD, triggers, search and scroll, schema lifecycle, purchase-path avoidance, single source of truth, and BFF handoffs. Use for justified custom persistence while avoiding the 60-schema limit.
260vtex-io-storefront-react
Apply when building VTEX IO storefront components under react/ for Store Framework experiences. Covers storefront component structure, css-handles, storefront context hooks, browser-safe data fetching, and how components should behave when used as theme blocks. Use for custom storefront UI, product widgets, banners, forms, or reviewing shopper-facing React code in VTEX IO apps.
260vtex-io-graphql-api
Apply when working with GraphQL schema files in graphql/ or implementing resolvers in node/resolvers/ for VTEX IO apps. Covers schema.graphql definitions, @cacheControl and @auth directives, custom type definitions, and resolver registration in the Service class. Use for exposing data through GraphQL queries and mutations with proper cache control and authentication enforcement.
257vtex-io-application-performance
Apply when improving VTEX IO Node or .NET services for latency, throughput, and resilience: in-process LRU, VBase, stale-while-revalidate, AppSettings loading, request context, parallel client calls, and avoiding duplicate work. Covers application-level performance patterns that complement edge/CDN caching. Use when optimizing backends beyond route-level Cache-Control.
256vtex-io-service-apps
Apply when building backend service apps under node/ in a VTEX IO project or configuring service.json routes. Covers the Service class, middleware functions, ctx.clients pattern, JanusClient, ExternalClient, MasterDataClient, and IOClients registration. Use for implementing backend APIs, event handlers, or integrations that must use @vtex/api clients instead of raw HTTP libraries.
255