# Theme Architecture

Understanding the architecture and design principles of themes.

## Overview

Finqu themes are built to be modular, flexible, and easy to customize. The architecture separates content, layout, and presentation, so you can create unique storefronts that stay maintainable and scalable.

A theme consists of templates, sections, blocks, assets, and configuration files. These components work together to define the structure, appearance, and behavior of a storefront.

## Theme Engine

The theme engine processes theme files and renders storefront pages dynamically. It interprets Liquid templates, processes section and block schemas, and merges user settings to generate the final HTML output. The engine supports localization, dynamic content, and extensibility through custom sections and blocks.

## Template Structure

Templates define the overall layout and structure of pages. They use placeholders like `content_for_index` to render sections and can include specific sections or blocks using tags. Templates are stored in the `templates` directory and are responsible for the page's main structure, such as headers, footers, and content areas.

## Section Groups

**Section groups** are ordered, merchant-managed collections of sections shared across pages — for example a header or footer region that appears on every template. Unlike a template's own sections (which live only on that template), sections in a group are stored once and rendered wherever the group is included via the `{% sections %}` tag. Group definitions live in the `section-groups/` directory. See [Sections](/build-with-finqu/liquid-themes/sections#section-groups) and [Templates & Layouts](/build-with-finqu/liquid-themes/templates-layouts#section-groups) for details.

## Sections

Sections are modular components that can be added, removed, or reordered within templates or section groups. They are stored in the `sections` directory and defined by a schema that describes their settings, blocks, and appearance. Sections are rendered using the `content_for_index` placeholder, the `section` tag, or as part of a section group.

## Blocks

Blocks are reusable content elements that live inside sections. They are defined in the `blocks` directory and configured via a schema. Most blocks render content directly; **layout blocks** can contain child blocks in named containers (nesting is limited to a single level). Blocks are rendered within sections using the `container` tag or can be rendered statically with the `block` tag. See [Blocks](/build-with-finqu/liquid-themes/blocks) for placement rules.

## Placement Model

Placement is controlled along three independent axes. All fields are opt-in and backward compatible — a schema with none of them behaves exactly as before.

| Axis | Where declared | Question it answers |
|------|----------------|---------------------|
| **Template** | `templates` on a section/block schema | On which page types may this be used? |
| **Region** | `section_groups` on a section + `allowed_sections` on a group | Which group/region may this section live in? |
| **Block target** | `private` on a block + `allowed_blocks` on a container/section | Which blocks may live in this container or section? |

See [Sections](/build-with-finqu/liquid-themes/sections) and [Blocks](/build-with-finqu/liquid-themes/blocks) for schema details and examples.

## Asset Pipeline

Assets such as CSS, JavaScript, images, and fonts are stored in the `assets` directory. The asset pipeline processes and delivers these files efficiently to the storefront, supporting features like minification, versioning, and caching.

## Settings and Configuration

Theme settings are defined in `settings_schema.json` and individual section/block schemas. These settings allow merchants to customize the look and feel of their store without editing code. Settings are exposed in the theme editor and merged with defaults during rendering.

## Best Practices

- Keep templates, sections, and blocks modular and reusable.
- Use settings and schema definitions to maximize flexibility.
- Organize assets and configuration files logically.
- Test themes thoroughly to ensure compatibility and performance.

This architecture enables developers to build powerful, maintainable, and customizable themes for the Finqu platform.