# Theme Structure

A Finqu theme is organized into a set of well-defined directories, each serving a specific purpose. Understanding this structure is essential for developing, customizing, and maintaining themes efficiently.

## Directory Overview

The typical theme directory contains the following folders:

| Directory  | Purpose |
|------------|---------|
| `assets`   | Contains images, stylesheets, JavaScript files, and other static assets. Special handling is provided for `.liquid` and Sass files. |
| `blocks`   | Reusable components that can be added to sections. Blocks can have their own settings and are designed for modularity. |
| `config`   | Stores theme configuration files, including `settings_schema.json` (settings schema) and `settings_data.json` (actual settings). |
| `layout`   | Contains layout files such as `theme.liquid`. Layouts define the overall structure of pages. |
| `locales`  | Holds translation files for different languages. Each locale is a JSON file, e.g., `en.json`. |
| `public`   | Publicly accessible files. All files here can be accessed directly via a browser. |
| `section-groups` | JSON definitions for shared section regions (e.g., `header-group.json`). Sections in a group are stored once and rendered wherever the group is included. See [Sections](/build-with-finqu/liquid-themes/sections#section-groups). |
| `sections` | Defines page-level building blocks. Sections can contain blocks and are the main structural elements of a theme. |
| `snippets` | Small reusable code fragments. Snippets are rendered in their own context and can be included in templates. |
| `templates`| Page templates for different store pages (e.g., `frontpage.liquid`, `cart.liquid`). |

## Required Files and Folders

- `layout/theme.liquid`: The main layout file. Additional layouts can be defined as needed.
- `config/settings_schema.json` and `config/settings_data.json`: Define and store theme settings.
- At least one template in the `templates` directory (e.g., `frontpage.liquid`).
- Locale file for each supported language in `locales` (e.g., `en.json`).

## Optional Components

- **Blocks**: Modular components for use within sections. Useful for creating dynamic, customizable content areas.
- **Section groups**: Shared, merchant-managed section regions (header, footer) that appear across multiple templates. Defined in `section-groups/` and rendered with the `{% sections %}` tag.
- **Snippets**: Reusable code pieces for icons, widgets, or other small features.
- **Additional layouts**: For special page types (e.g., `campaign.liquid`).

## Configuration Files

- `settings_schema.json`: Defines the structure and available options for theme settings.
- `settings_data.json`: Stores the actual values for the theme settings and presets.
- `config/.data/` (optional): Used by the Finqu designer to store merchant draft edits. Theme authors normally do not edit this directory.

## Locale files

Each supported language needs a JSON file in `locales/` (e.g. `en.json`, `fi.json`) for storefront strings used in your Liquid templates.

**Schema translations:** Add `locales/{lang}.schema.json` to translate section, block, and setting labels shown in the theme designer — without mixing them into storefront copy. Labels from `.schema.json` are merged into the corresponding locale at runtime.

See [Localization](/build-with-finqu/liquid-themes/localization) for details.

## Deploy lifecycle

1. **Develop locally** — Edit theme files in your project; preview with [Theme Development Kit](/apis-and-tools/theme-dev/overview).
2. **Deploy** — Run `finqu theme deploy` or publish from the partner portal. Finqu compiles `.scss.liquid` assets into `public/` on the merchant store.
3. **Customize** — Merchants edit sections and settings in the admin designer; changes are draft until published.

Your theme repo is the source of truth. After deploy, merchants customize via `settings_data.json` on the store — not by editing your repo directly.

## Best Practices

- Use the `assets` directory for all static files. Sass files are compiled with Dart Sass, and `.liquid` files are processed and cache-busted automatically.
- Reference assets using the `asset_url` filter: `{{ 'my_file.svg' | asset_url }}`.
- Organize blocks and sections for maximum reusability and maintainability.
- Use the translation system in `locales` to support multiple languages and dynamic content.
- Keep configuration files up to date and well-documented.

## Related Articles

- [Blocks](/build-with-finqu/liquid-themes/blocks)
- [Sections](/build-with-finqu/liquid-themes/sections)
- [Settings](/build-with-finqu/liquid-themes/settings)
- [Templates & Layouts](/build-with-finqu/liquid-themes/templates-layouts)
- [Localization](/build-with-finqu/liquid-themes/localization)