Growth Notes

Headless Architecture

Tags: web-dev commerce concept

Headless Architecture

Date: 2026-08-16

Separating the front end from the commerce or content backend, connected by an API. It buys freedom over presentation and costs you everything the monolithic platform was doing for free — which is usually more than the pitch admits.

What it is

Headless architecture decouples the presentation layer from the system managing data and business logic. The backend exposes an API; the front end is a separate application that consumes it.

MONOLITHIC                        HEADLESS

┌──────────────────────┐          ┌─────────────────┐
│  templates           │          │  your front end │
│  business logic      │          └────────┬────────┘
│  data                │                   │ API
│  checkout            │          ┌────────┴────────┐
│  admin               │          │  commerce API   │
└──────────────────────┘          │  data, checkout │
                                  │  admin          │
  one system, one deploy          └─────────────────┘
                                    two systems, two deploys

What you gain

  • Presentation freedom. No theme system’s constraints; any framework, any rendering strategy — Rendering Strategies
  • Performance control. You own the critical path rather than inheriting a theme’s
  • Multi-channel. One backend serving web, app, kiosk, marketplace
  • Independent release cadence. Front end ships without touching commerce logic
  • Best-of-breed composition — search from one vendor, reviews from another, content from a third

What you give up

This half is systematically understated, and it’s where headless projects fail.

  • Checkout. The most tightly-controlled part of any commerce platform, for good reasons — PCI scope, payment methods, fraud, tax. Going headless usually means keeping the platform’s checkout anyway, which caps the freedom you bought — Checkout Instrumentation Constraints
  • The admin experience. Merchandisers lose preview, drag-to-reorder, and the ability to see what a change looks like. This is the complaint that arrives three months in
  • Apps and integrations. A platform’s app ecosystem assumes its own front end. Headless means most of them stop working, and each becomes a build
  • Everything the theme did. Search, filtering, recommendations, upsells, currency, localisation, cookie consent — all previously free, now yours
  • Two systems to operate, two deploy pipelines, two on-call surfaces
  • A permanent integration seam where data goes stale, out of sync, or missing

In plain terms: headless doesn’t remove work, it moves it to you. The platform was doing a great deal that nobody itemised, and the bill arrives as a backlog.

When it’s justified

Genuinely good reasons:

  • The theme system is the binding constraint on something commercially important, and you’ve established that rather than assumed it
  • Multiple channels need the same catalogue and the same logic
  • Content and commerce are deeply intertwined — editorial-led retail, where the CMS is the primary experience
  • Performance is materially constrained by the platform and you’ve measured it
  • You have the team. Ongoing front-end engineering capacity, not a one-off project budget

Bad reasons, which account for most projects:

  • The current site is slow (usually fixable in place — Performance Budgets)
  • The team wants to use a particular framework
  • A vendor said composable is the future
  • The design is hard to build in the theme (sometimes true, rarely worth the trade)

The middle ground

The choice isn’t binary, and the middle is where most sensible answers sit:

  • Hybrid — headless for high-traffic browse and content pages, platform checkout. Keeps PCI scope and payment complexity where it belongs
  • Modern theme — several platforms now support component-based theming with server rendering, closing much of the gap that motivated headless originally
  • Headless CMS, monolithic commerce — decouple content without decoupling transactions. Often gets 80% of the benefit for 20% of the cost

Practical consequences

  • Measurement gets harder. Two systems, two identity contexts, a checkout on a different origin. Plan instrumentation before, not after — Identity Stitching, The Data Layer
  • SEO risk rises. A framework defaulting to client-side rendering removes indexability that the theme provided by default — Rendering and SEO
  • Caching becomes your problem. The platform handled it; now you own cache keys, invalidation and personalisation boundaries — CDN Caching
  • A replatform to headless is two migrations at once — data and presentation. See Replatforming and Site Migrations and SEO

Graph View

Backlinks