# Architecture and files

## How a theme becomes a website

A GS Loom theme is a directory of Loom templates, JSON schemas and CSS. Authors can build new themes without adding a React component or PHP class. The compiler validates the directory and builds a registry. The customer editor reads schemas to create controls; the preview and public renderer execute the same Loom runtime.

The pipeline is: **source package → compiler → theme catalog → customer settings → Loom → shared renderer**. Importing source files does not itself publish a customer website. Catalog synchronization makes the theme available; the customer still edits and publishes their own site.

## Directory reference

| Path | Purpose | Example |
| --- | --- | --- |
| `loom.json` | Stable identity, version and default language | `launch-theme`, `1.0.0` |
| `layout/*.html` | Wrapper around page content | `theme.html` |
| `templates/*.json` | Initial page sections and order | `home.json` is required for catalog themes |
| `sections/*.html` | Section markup and schema | `hero.html` |
| `sections/*.json` | Shared section groups | `header.json` |
| `blocks/*.html` | Reusable, nestable blocks | `card.html` |
| `snippets/*.html` | Reusable markup with explicit parameters | `link.html` |
| `config/settings_schema.json` | Global editor controls | Colors and font |
| `config/settings_data.json` | Initial global values in `current` | Brand defaults |
| `locales/*.json` | Storefront and schema translations | `en.json`, `en.schema.json` |
| `assets/*.css` | Automatically scoped theme CSS | `theme.css` |

HTML and schema directories are flat. Use `.html`, `.schema.json` and `.css` files there. Images, fonts and browser bundles belong in `public/`; trusted TypeScript interaction modules belong in `runtime/`.

## Identity and ownership

```json
{"key":"launch-theme","name":"Launch Theme","version":"1.0.0","defaultLocale":"pl","catalog":true}
```

Use a lowercase key starting with a letter, containing letters, digits and hyphens, at most 40 characters. Keep it stable and use it as the directory name. A display-name change does not require a new key. Versions have three numeric components. `catalog: true` makes the compiled theme available to the product synchronization command.

Keep theme-specific files under `packages/templates/src/templates/<key>/`. Shared controls and rendering belong in the shared engine. Generated registries in `packages/templates/src/lib/loom/themes.json` must not be edited by hand.

## Existing content compatibility

Nordic renders editorial sections and cards through Loom. Paylio renders finance sections and its footer through Loom, retaining adapters for forms, FAQ and pricing interactions. Victorie Vending has 80 Loom sections with existing field identifiers; its document mode renders `documents/*.html` and GS Loom sections; builds also generate HTML for the API SEO renderer. Starter Business wraps its existing canvas in Loom while preserving v1 saved nodes.

These adapters preserve existing customer documents. Do not delete them because a theme now contains Loom. New themes should start from the native example rather than copying compatibility-only attributes.

Continue with the [complete workshop](/en/quickstart/) or the [schema reference](/en/schema/).

The installed catalog now contains only Victorie Vending, Paylio and GrowSite Skeleton. Nordic is retired; its compatibility renderer preserves previously saved sections. Starter Business is a test fixture, not an installed theme.

`public/` carries images, fonts and browser assets, including nested directories. Trusted interaction modules in `runtime/` are bundled with the application and require maintainer review. HTML and schema directories remain flat.