architecture-well-architected-commerce

What this skill does

# 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

**Objective:** A secure, reliable, compliant base that earns **trust**.

**Core values:** **Reliability** (consistent performance), **Trust** (transparent, accountable processes), **Integrity** (ethical handling of data, code, and resources).

**Critical areas (examples):** Advanced security (data protection, transaction security, threat awareness); reliable infrastructure (availability, scalability, recovery); compliance (regulations, audit trails, monitoring). **Continuous learning** keeps guidance current with technology and VTEX direction.

_Nothing in Future-proof or Operational Excellence relaxes this pillar._

#### Future-proof

**Objective:** Solutions that stay **adaptable** and **maintainable** as the business and platform evolve.

**Core values:** **Innovation** (current VTEX and industry best practices), **Simplicity** (the overarching value—minimum viable custom surface, whole-solution coherence), **Efficiency** (optimize effort and platform use).

**Critical areas (examples):** Scalable solutions; business and market adaptability; modular / compositional design; rapid deployment (agile delivery, CI/CD); **system integration** (VTEX-centric, API-first connectivity).

#### Operational Excellence

**Objective:** Run the program with **data-informed** decisions and **accountable** execution.

**Core values:** **Accuracy**, **Integrity**, **Accountability**, **Data-driven decision-making** (plus operational excellence as a discipline).

**Critical areas (examples):** Process optimization (efficiency, lean, automation); data-driven strategies (analytics, predictive insight, monitoring); performance improvement (VTEX insights, continuous monitoring, agility); **customer experience** (personalization, feedback, omnichannel).

### Routing to product tracks

Platform-specific **how** belongs in **product skills**, not in this meta-skill. After pillar alignment, use:

| Topic                                                                                                             | Track skill                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| VTEX IO **service paths**, edge/CDN behavior, `Cache-Control` vs data scope                                       | [vtex-io-service-paths-and-cdn](../../../vtex-io/skills/vtex-io-service-paths-and-cdn/SKILL.md)                          |
| VTEX IO **application performance** (caching layers, AppSettings, parallel fetches, tenant-scoped in-memory keys) | [vtex-io-application-performance](../../../vtex-io/skills/vtex-io-application-performance/SKILL.md)                      |
| **Master Data** storage fit (challenge whether MD is the right place), purchase path, BFF, single source of truth | [vtex-io-masterdata](../../../vtex-io/skills/vtex-io-masterdata/SKILL.md)                                                |
| **Marketplace** fulfillment, simulation, integration flow                                                         | [marketplace-fulfillment](../../../marketplace/skills/marketplace-fulfillment/SKILL.md) (and related marketplace skills) |

**Cross-cutting VTEX rules (still architecture-level):**

1. **Native and OOTB before VTEX IO** — Prefer **native VTEX capabilities** and **configuration** before a **VTEX IO** extension. **Use IO only when** there is **no** suitable native path; document **why not native** if IO is chosen anyway.

2. **Simplicity and commodities** — Prefer **platform-native** behaviors for **commodity** capabilities; reserve custom work for **differentiators** or **genuine gaps**, not for substituting process or ownership fixes.

3. **Integration discipline** — Prefer **fewer hops**, clear **ownership**, and **API-centric** design (see Future-proof system integration)—detailed patterns live in IO, headless, and marketplace skills.

## Decision rules

1. **Classify every major decision** under one or more **pillars** (see **Three pillars (framework)**). If a choice does not map to any pillar, question whether it is necessary.
2. **When extending the platform** (VTEX IO, Master Data, integrations), use the **Routing to product tracks** table—implement caching, paths, MD usage, and marketplace flows with those skills, and record how the choice supports **Future-proof** and **Operational Excellence** without weakening **Technical Foundation**.
3. **Prefer fewer integration hops** where custom code remains necessary: each hop adds failure modes and operational load. Additional services or backends are valid when they **isolate failure domains** or **clear team boundaries**, not by default.
4. **After architecture choices are clear**, assign execution to **product track skills** (see **Routing to product tracks** and **Related skills**). This skill sets direction; product skills enforce VTEX-specific contracts.
5. **Operational discipline** requires definable **metrics and ownership** (who runs it, how incidents are detected, how changes are released). Undocumented “best effort” operations violate **Operational Excellence** even if the design is lean.

## Hard constraints

### Constraint: Do not bypass Technical Foundation for speed

Security, credential handling, PCI scope, and private API access **must** follow VTEX and industry baselines. Architectural shortcuts that expose secrets, widen PCI scope, or call private APIs from untrusted clients are **never** acceptable tradeoffs for velocity.

**Why this matters** — Data breaches, fraud, and account compromise destroy customer trust and can invalidate compliance posture for the whole program.

**Detection** — If the design places `VTEX_APP_KEY`/`VTEX_APP_TOKEN`, raw card data, or shopper session tokens in browser code, public repos, or logs → **stop** and redesign using product skills (e.g. headless BFF, payment Secure Proxy).

**Correct** — Classify data and APIs; keep secrets and private calls server-side; reference PCI and authentication guides for the chosen integration style.

```text
Architecture decision log:
- Private VTEX APIs → server-side only (BFF or IO service).
- Card data → Payment Provider Protocol / Secure Proxy patterns only.
```

**Wrong** — “We will call Checkout OMS from the SPA for speed” or “store app token in NEXT_PUBLIC for dev convenience.”

### Constraint: Future-proof means justified complexity, not maximal decomposition

Every new service, queue, or datastore must have a **stated owner**, **failure mode**, and **reason** tied to a pillar (e.g. isolation, scale, regulatory boundary). Unboun