Where pages are composed: the decision tree

Who this is for. Whoever decides how a Core dna site is built, before any code is written: a technical lead, an architect, a developer asked for an opinion at the kickoff. After this page you can place your project in one of the shapes and know which unit of this guide to read next.

Reading the tree

The first question has two answers that lead to headless, and both are requirements rather than preferences: an interface that behaves like an application, keeping state across screens without loading pages, or a front end that must also serve a native app that cannot render HTML. Every other project starts with server-side templating.

The second question is the one most teams answer no at the start and yes a few months later. A sign-in link in the header is enough: it differs between a visitor who is signed in and one who is not. Plan for hybrid from the first sprint. Keeping the per-visitor parts separate costs nothing on day one and a great deal once they are spread through the templates.

Several brands, regions or languages are not on the tree because they are not a choice between the shapes. One codebase serving several brands combines with any of them (Multi-brand as an overlay).

The question is where composition happens

Composing a page means turning a URL into HTML: finding the record at that path, choosing the template its layout names, assembling its areas and components, and rendering them. On Core dna that happens in one of two places. With server-side templating the platform does it on every request, or answers with a copy it stored earlier. With headless, your application does it, and the platform only answers requests for data. Hybrid keeps composition on the platform and lets the browser add a few parts afterwards.

Framing the decision this way keeps it on evidence. A team that wants React or Vue wants islands of JavaScript, which a hybrid site has; that is not by itself a reason to move composition off the platform. Which template engine to use, Smarty or Twig, is a separate decision with its own guide: Smarty and Twig side by side.

Where the platform hands off a request

Every request to a Core dna site goes through the same checks, in this order, and the shapes differ in which of them they use:

1. A file in the site's folder, such as the built CSS and JavaScript, is sent as it is. Templates are never served this way.
2. A path under /cdna-api goes to the API: the REST routes, GraphQL at /cdna-api/graphql, and custom endpoints at /cdna-api/webhook/….
3. A path under /cdna-admin goes to the admin.
4. A copy of the page stored in the page cache is sent, without running any template and without checking who is asking.
5. Everything else reaches the front end: rewrites and custom URLs are applied, the path is routed to a module and a record, and the record's layout chooses your template.

A headless front end uses step 2 only. A server-rendered site lives on steps 4 and 5. A hybrid site serves its pages from steps 4 and 5 and its per-visitor parts from step 2, or from small pages of its own that are never cached. Step 4 is the reason hybrid exists: the cached copy is sent before the platform knows who is asking, so anything per-visitor inside a cached page reaches the wrong people (Why fragments).

Why server-side is the default

Server-side templating is the platform's richest path. Routing, the page cache and its invalidation, revision preview, live preview with in-context editing, SEO output, the sitemap, error pages, forms and member sign-in all work without code of yours (What the platform does that you do not write). Headless trades every one of them for complete freedom in the front end, and you rebuild the ones you need (What a headless build must rebuild).

That is why pure headless is the exception rather than the destination. None of the production sites studied for this guide is headless, and the most API-driven parts of them are islands inside server-rendered pages (Five case studies).