# Architecture

Source: <https://docs.ictsviluppo.example/dossier/developers/architecture/>

Dossier is built on Shopify’s Skeleton theme with theme blocks, JSON templates, section groups and custom elements, and no JavaScript framework. This page explains the conventions that hold the theme together, so that your changes follow them.

## Section groups and templates

Every template is JSON, except `gift_card.liquid`. Three section groups are shared by every page of `theme.liquid`:

- `g-header.json`: Announcement bar and Header;
- `g-sidebars.json`: Mobile menu, Cart drawer and Cart notification, rendered last in `<body>`;
- `g-footer.json`: Footer.

Each section of a group accepts only its own group and appears at most once. `password.liquid` renders no group.

## Names tell you where a file is used

File names, section and block `type`s carry a prefix:

| Prefix | Meaning |
| - | - |
| `g-` | Section group |
| `h-`, `f-`, `a-` | Sections of the header, footer and sidebars groups |
| `main-` | Main section of a template |
| `section-` | Sections merchants add to any template |
| `sra-` | Sections rendered only through the Section Rendering API, invisible in the theme editor |
| `gen-` | Public theme blocks, shared by several sections |
| `_<parent>-` | Private theme blocks of one section, for example `_section-slideshow-slide` |
| `_prod-` | Private blocks shared by Product information and Featured product |
| `wc-` | Custom elements and their modules |
| `util-` | Shared JavaScript modules and Liquid utility snippets |

Snippets are grouped by area: `head-`, `media-`, `prod-`, `coll-`, `blog-`, `cart-`, `nav-`, `form-`, `util-`.

## Theme blocks

Blocks are theme blocks in `blocks/`, private by default (the file name starts with `_`), so they appear only in the section that declares them. The only section blocks are the `@app` blocks and the mega menu promotions of the Header.

Theme blocks are not visible to their section as `section.blocks` with their type and settings. When a section needs to know something about its blocks, it reads the rendered HTML of `{% content_for 'blocks' %}`, captured once, or the block receives what it needs as a parameter.

## Color schemes

Colors come only from the theme’s color scheme group. Every section has a `color_scheme` setting and applies `color-{{ section.settings.color_scheme }}` to its root element; the class sets the CSS variables of the scheme (`--color-surface`, `--color-ink`, `--color-brand`…) and the background and text color. The classes are generated in Liquid from the schemes that exist, so a scheme added by the merchant works everywhere. Use the variables, never fixed colors, for anything that must keep its contrast.

## Custom elements and progressive enhancement

Every page works without JavaScript: navigation and menus are `<details>` elements, the product form is a real `<form>` that posts to `/cart/add`, the cart updates with real forms. JavaScript adds behavior on top through custom elements, one ES module per element (`wc-<name>.js`), loaded with `<script type="module">` only where the element is rendered.

The header comment of each Liquid file declares its JavaScript: `web-component: wc-<name>`, a module name, or `none`. Data that only Liquid knows reaches the scripts in `<script type="application/json">` tags, and texts in `data-` attributes, already translated.

Partial updates, such as variant changes, the cart and predictive search, use the Section Rendering API: the element requests the section’s HTML for the new state and replaces part of the page. The product page has no variant JSON: the variant picker re-renders the section with `option_values`.

## Events you can listen to

Components talk to each other through DOM events on `document`:

| Event | When | `detail` |
| - | - | - |
| `cart:added` | After a product is added from the product form or a product card. Cancelable: the component that shows the confirmation (cart drawer or cart notification) cancels it. | `item`: the line returned by Shopify |
| `cart:rendered` | After the cart HTML is updated on the page. Bubbles. | — |
| `cart:refreshed` | After the cart section is requested again following an add. Bubbles. | — |
| `scheduled-content:change` | When a scheduled section or block appears or disappears. Bubbles. | — |

Listen to `cart:added` to react to an add, for example to update a third-party counter; don’t cancel it, or the customer won’t see a confirmation.

## Right-to-left languages

`<html>` carries `dir` from the storefront language. The CSS uses only logical properties (`margin-inline-start`, `inset-inline-end`, Tailwind’s `ms-`, `pe-`, `start-` and so on), and directional icons are mirrored. Scripts read the direction from the document. Keep to logical properties in your CSS so the theme keeps working in Arabic and Hebrew.

## Translations

Every visible text is a key in `locales/en.default.json`, and every theme editor label a key in `locales/en.default.schema.json`, both translated in 31 more languages. A new text needs a key in every language file.