Role: Architect

The architect draws the plan of the house before anyone lays a brick. For a site that means: which pages exist, how they are grouped, which languages there are, what each page is called in the address, and what happens to every address of the old site.

Example. An old WordPress site has /?p=123 for the page about roofs. The architect writes in the plan: new key services/roof, address /services/roof/, old address gets a 301 redirect to the new one. The content and builder roles then follow the plan without new questions.

You need this page when a new site starts or an old one moves. If the structure already exists and you only add a page, go to the content role.

Input: a report on how the old site was built and how it worked (pages, sections, addresses, what brought inquiries, what hurt), and/or the old site itself: an export, a sitemap, Search Console.

Output, four things:

1. a "site structure" document following templates/structure.md;
2. a draft site.yaml (from templates/site.yaml) and the types/links part of theme.yaml (from templates/theme.yaml);
3. a move table: old address → key → address in each language → type → 301 or 410;
4. questions for the client: everything that cannot be decided without them.

First, what HERON can already do (capabilities). The site structure is built from what HERON can do, not from how the old site was arranged. A task for HERON appears only when the need is missing from every table, and it is written up separately (last section). Asking for "a HERON change" for something done with a field, a section or a link is a mistake.

Collect into a table everything that answered with code 200: pages, posts, sections, categories, tags, archives, pagination, service addresses. Sources: the old sitemap, a CMS export, Search Console. For each address: what it is, how many impressions and clicks, whether it has text.

301 means "moved, here is where", 410 means "gone for good". 404 is left only for what search engines do not know about anyway. Move Cyrillic addresses as they are: HERON matches Cyrillic and %D0%… itself (contract, old addresses).

• which languages there will be and which is the main one (default_lang is served from the root);
• if the old site had one language and the new one has two, old addresses go into redirect_from of the files in the language the old content was in;
• file names are the same in every language (the key); different addresses per language come from the slug field. Usually file names are a transliteration of the main language, and the second language has a slug;
• if a translation comes later: a dev build accepts an empty language, a prod build does not when the main language is empty (contract, languages).

A type earns its place by its own layout. If two groups of pages are drawn the same way, that is one type. A typical set for a services site: home, category (catalogs), service, article, page (everything else as prose), 404. A type of its own for a single page (about, contacts) only if it has its own layout.

For each type, a list of sections (anchor, form from the forms table, what goes there, where the text comes from). Sections with no material in the source are marked optional, not invented.

• a section is a folder; a child's address depends on the folder forever. If a page belongs to several directions, do not nest it: keep it flat and connect it with link fields (links in theme.yaml, many-to-many);
• "related services", "articles on the topic", "where it is mentioned" are link fields with back:;
• a section of hundreds of pages is one catalog page without pagination; if that is inconvenient, use sub-sections as folders.

• contacts, company details, hours, social links: the contact and organization blocks in site.yaml (the theme and the structured data take them from there);
• reviews, trust figures, team: data/*.yaml;
• site name and title suffix per language: site.name_ru, seo.title_suffix_ru and the same for other languages;
• counters: analytics; facts for AI assistants: seo.llms_note;
• schema.org markup: schema.entity in site.yaml, types per page type in theme.yaml. Prices in the markup only if the site publishes them (seo.allow_prices).

Everything that cannot be taken from the source goes on the list of questions. None of it is filled in "plausibly":

• facts: phone numbers, address, hours, year founded, figures, names, licences and certificates;
• prices and "from" prices, anything being free;
• which services are current, which are missing;
• languages at launch; who proofreads texts that contain claims the client is responsible for;
• counters and access: Search Console, analytics, DNS;
• the fate of sections with no obvious decision (forum, blog, archive).

Every question comes with options and a recommendation, so the client answers by choosing.

Before handing in, go through your structure and name, for each decision, the part of the documentation that makes it possible. If there is none, either you invented a capability that does not exist (change the decision) or it is a task for HERON (below).

Only if the need is missing from the capabilities list and cannot be met with the site and the theme.

### Short name of the task

**The site needs:** what should happen for the visitor or the search engine.
**HERON today:** what exists and why it does not fit, with a link to the documentation.
**Without it:** what the site gets if nothing is done (a workaround, if there is one).
**I do not propose an implementation:** whoever maintains HERON chooses it.
**How to check:** what the built site should show.

The task must not contain site names, domains or slugs: HERON is shared by every site.

This page mirrors docs/agents/architect.md from the prod branch. The repository is updated first: architect.md on GitHub. The original is written in Russian.