Theme architecture

Overview

Zenit follows Nuvemshop’s section-based architecture (reference: Ipanema theme):

• Demos (theme/demos/demos.json) register distributed verticals; clothing is the current base
• JSON templates (theme/demos/<demo>/templates/pages/*.json) define each page’s initial composition
• Sections (theme/sections/*.tpl) render full-width units with {% schema %}
• Blocks (theme/blocks/*.tpl) are components within sections
• Snippets (theme/snippets/*.tpl) are partials without a schema (cart, shipping, variants…)
• Layout (theme/layouts/layout.tpl) wraps everything with header/footer through {% layout_template %}

Full technical documentation in the repository: docs/ai/architecture.md.

Rendering flow

theme/demos/clothing/templates/pages/<page>.json
  → theme/sections/<type>.tpl
    → theme/blocks/<type>.tpl
      → theme/snippets/...
theme/layouts/layout.tpl (header + main + footer)

Where to customize

Goal	Where
New reusable section	theme/sections/ + preset in JSON template
New generic block	theme/blocks/ with "tags": ["general"]
Cart/variant logic	theme/snippets/ + theme/static/js/store.js
Global colors/typography	theme/config/settings_schema.json + theme/layouts/resources/style-tokens.tpl

Contracts — do not break

• data-store on canonical nodes (product, cart, account)
• {{ block | block_attributes }} on every block
• {{ component('nubesdk-slot', { type: ... }) }} at documented anchors

See the full list in docs/ai/architecture.md § Contratos invariantes.