In a headless rebuild, the bottleneck isn't the front end — it's the content model

The conversation about choosing a headless CMS almost always begins as a tool comparison. Feature matrices get lined up, pricing models compared, editing interfaces judged. That conversation is legitimate, but it arrives about two weeks too early. Because in nearly every rebuild I observe, the item that actually decides the schedule is neither the tool choice nor the front-end build: it is the invisible, thankless work of deciding what a page is.

That work has a sober name — content modelling — and it suffers from a fatal flaw when it comes to earning attention: it produces nothing you can show in a meeting. No interface, no screenshot, no demo. It consists of writing a list of types, fields and relationships. And yet it is from that list that the data migration load, the future autonomy of the marketing team, and the site’s ability to evolve without redeployment all follow.

The three kinds of disorder you always find

The starting point is always the same: the existing information is not structured, it is rendered. In a classic theme, a product record is a mix of native platform fields, metafields added over the years, rich-text blocks pasted into the description, and sometimes HTML tables written by hand. Together they produce a correct display, which conceals the underlying disorder.

Opening that up holds three recurring surprises.

The first is multiple representations of the same notion. The size guide exists as an HTML table on 2021 records, as an image on 2023 ones, and as a structured metafield on the most recent. None of those three forms is wrong; it is simply that no API can serve them uniformly.

The second is the catch-all field. There is almost always a metafield named additional_info or equivalent, whose content has diversified to the point of holding 5 different kinds of information depending on the record. Breaking it apart means reading the catalogue, not programming.

The third is the one-off page. One, two, sometimes 5 pages were built by hand because they fit no template — the holiday campaign page, the partnership page, the brand story. They are statistically negligible and they consume disproportionate time, because each raises the question of whether you model a type for a single object.

Disorder found	Typical example	What it costs at migration
Multiple representations	Size guide as HTML table, then image, then metafield	One transformation per historical variant
Catch-all field	A metafield holding 5 kinds of information	Manual reading of the catalogue before any code
One-off page	Campaign page built outside any template	Model a type for a single object, or drop it

The central tension: constrain structure, free content

The structural decision in modelling comes down to a single trade-off, and the two symmetric mistakes are equally expensive.

A model that is too rigid defines tight types matching exactly the needs known at rebuild time. It produces a clean database and a dependent marketing team: any campaign page outside the frame requires development work, therefore a ticket, therefore a delay, therefore eventually a workaround. Six months after launch, the editorial team publishes its campaigns on a third-party platform because the site is too slow to change.

A model that is too permissive makes the opposite mistake. It offers a free-form block page builder where editors assemble whatever they want. Autonomy is total in month one. By month 6 there are 11 variants of the same feature section, the visual identity has drifted, and performance has degraded because nobody controls what loads on a given page any more.

The balance point I aim for is this: structure is constrained, content is free. Page types are closed and few. Within each type, the editor gets a set of permitted blocks, each with typed fields and validation rules. They can say anything; they cannot build anything.

A good content model is judged not by what it permits but by what it prevents. What it prevents is the silent drift that makes a site unreadable in 18 months.

Preview: technical debt disguised as convenience

There is a precise moment in every headless rebuild when the editorial team understands what it has lost. It is the first time they want to check what a page will look like before publishing it.

In a coupled system the question does not arise: the CMS and the rendering are the same thing. In headless they are separate by construction, and preview must be built explicitly — a rendering mode that queries drafts rather than published content, a protected route, adapted cache invalidation. It is not hard, but it is not free, and it does not happen by itself.

A team without reliable preview adopts a predictable behaviour: it publishes to production to see, corrects, republishes. Which cancels the benefit of the editorial workflow and introduces real risk on a commerce site. I therefore treat preview as a level-one requirement, to be validated during tool selection and delivered in the first batch — not as an end-of-project refinement.

Multilingual decides more than it appears

For a Canadian brand, the language question is not a configuration option. It has direct consequences on the model.

You must decide, type by type, what is translated and what is shared. A product record has a translated name and description, but a shared price, stock level and identifier. An editorial page may exist in only one language — and the model must represent that absence explicitly, otherwise the site will produce links to pages that do not exist. You must also decide whether URL identifiers are translated, which affects routing, redirects and language alternate markup.

These decisions are easy to make at modelling time and expensive to change afterwards, because they touch the content base, the routing and the search visibility all at once.

The real variable: data migration

That leaves the workstream whose load depends entirely on the quality of the existing content, and which the model finally makes estimable. Migrating content is not copying fields. It is writing transformations that take historical disorder and produce structure. Extracting a size guide from an HTML table. Breaking a catch-all field into three typed fields. Reconciling three naming conventions.

That load is the most variable line item of the whole project — I have seen a factor of 5 between two catalogues of comparable size. Which is precisely why the audit must precede quoting: without it, this item is guessed, and a project whose most variable item is guessed has no date. It joins there the five other items that make a Hydrogen migration schedule slip.

The order in which to run a headless rebuild

Let me restate the sequence I defend, because it inverts the usual order.

First audit the existing content and write the model: types, fields, relationships, translation rules. Only then choose the tool — and choose it against that model, verifying it can represent those precise types, handle those precise languages, offer that precise preview. Finally build, with data migration quoted from observations rather than intuition.

That sequence has a merit beyond methodological comfort: it turns the CMS choice, usually a matter of taste defended with brochure arguments, into a documented decision you can justify three years later. And it puts the hard work at the start of the project, where it costs days, rather than in the middle, where it costs weeks.

---