Headless Architecture

A system architecture where the core engine has no built-in UI; consumers (web, mobile, CLI, agent skill, third-party integrations) all access it through an API. The "head" — the user-facing presentation layer — is unbundled from the body.

The term entered mainstream tech vocabulary via headless CMS (Contentful 2013, Strapi, Sanity). It's now generalised: headless commerce, headless browsers, headless analytics. For local tools, the local-daemon pattern is one specific embodiment.

What's "headless" vs traditional

   Traditional CMS (e.g. WordPress)
   ─────────────────────────────────
   ┌──────────────────────────────┐
   │  WordPress: UI + content +   │
   │  templating + serving + DB   │
   └──────────────────────────────┘
                  │
                  ▼
              user's browser

   Headless CMS (e.g. Contentful)
   ──────────────────────────────
   ┌──────────────────────────────┐
   │  Contentful: content + DB +  │
   │  API. No UI for end users.   │
   └──────────────────────────────┘
                  │  REST/GraphQL API
                  │
       ┌──────────┼──────────┬──────────────┐
       ▼          ▼          ▼              ▼
   Next.js     iOS app   Slack bot    Custom integration

The headless CMS just stores and serves content via API. Anyone can be the rendering layer.

Why this shape works

• Content team and frontend team move independently. Content is updated in the CMS; the frontend can be rebuilt without touching content.
• Multiple frontends from one source. Same content powers the web, mobile app, smartwatch — all consumers of the same API.
• Future-proofing. Today's frontend technology won't be tomorrow's. The content (and CMS) survives. Frontend rewrites don't require migrations.
• Composable. The headless CMS is one of N services in the stack; pick best-of-breed for each layer.

Headless beyond CMS

The pattern shows up in:

• Headless commerce (Shopify Hydrogen, commercetools) — same idea for e-commerce. Inventory, cart, checkout in the backend; storefronts everywhere.
• Headless browsers (Puppeteer, Playwright) — browsers without UI, controlled by APIs. For automation, scraping, testing.
• Headless analytics (PostHog backend, Plausible) — collect events via API, visualise wherever.
• Headless authentication (Auth0, Clerk, Stytch as service) — auth backend, your UI.
• Headless TestRail / project tools — same.
• API gateways generally — Kong, KrakenD, Tyk: routing layer for headless services.
• Local daemons with multiple clients (Mxr, Lazydap) — same pattern, scaled down to one machine.

The unifying observation: whenever a system might have multiple consumers, decoupling the core from any one consumer pays off.

Headless vs API-first

The terms overlap but emphasise different things:

• API-First Design: a methodology. Design the API before any client.
• Headless: an architecture. The system has no privileged UI.

You can do API-first and ship a UI alongside (Stripe — they have a Dashboard, but it's just another client). You can be headless without strict API-first discipline (some headless CMSes ship messy APIs).

In practice, the two reinforce each other. Headless without API-first leads to bad APIs that fail their consumers. API-first without headless leaves the original UI tangled with internals.

What headless costs

• No "out-of-the-box" UI. Adopters have to build (or buy) the frontend. WordPress wins on "deploy and use immediately"; Contentful loses on this.
• Tooling fragmentation. No single editor, no single visual experience. Each consumer has its own.
• More architectural work. Splitting clean APIs from logic is more upfront design than building integrated.
• Slower for simple cases. A landing page on WordPress is faster to build than the same page through Contentful + Next.js.

The trade-off is the same as API-First Design: pays off when you have or expect multiple consumers; overhead otherwise.

What "headless" specifically gives you

Three properties:

1. Substitutable consumers. Replace the React frontend with Vue, with vanilla HTML, with a mobile app. Backend untouched.
2. Programmatic access. APIs make automation possible. CMS data feeds analytics, AI training, search engines, custom workflows.
3. Vendor lock-in is reduced. You can theoretically swap Contentful for Strapi if both expose similar APIs. (In practice, schemas migrate awkwardly, but the architectural option is there.)

Headless and AI agents

A 2024–2026 development: AI agents naturally consume headless systems. An agent can call a headless CMS's API to fetch content; it can't navigate WordPress's admin UI.

Tools that ship with rich UIs but no usable API are increasingly invisible to agents. Headless architectures are agent-friendly by default. See Agent-Native Interfaces.

Local-tool variant

Mxr and Lazydap are headless in spirit:

• The daemon has no built-in UI.
• The TUI is one client; the CLI is another; the agent skill is a third.
• All consumers go through the same IPC protocol.
• Adding an Electron app or web bridge is a client project, not a backend change.

The macroscale (cloud-based headless CMSes serving N consumers) and the local scale (a daemon serving N clients on one machine) share the architecture even though the deployment is wildly different.

Common pitfalls

• Half-headless. "We have an API but the main app uses internal-only methods." Defeats the point.
• Anaemic API. Headless is only as good as the API. A bad API + headless = same problem as a bad UI + integrated.
• Authentication as afterthought. Headless systems need to handle auth via the API. OAuth, API keys, session tokens — all become first-class concerns.
• Documentation debt. When the API IS the product, undocumented APIs are unshipped products.

See also

• Client-Agnostic Cores — the synthesis
• API-First Design — the methodology that produces headless architectures
• Headless Core + Multiple Clients — the local-tool variant
• The Bezos API Mandate — the org-scale forcing function
• Agent-Native Interfaces — why headless wins in the agent era
• Contentful (canonical headless CMS): https://www.contentful.com/headless-cms/
• Wikipedia: https://en.wikipedia.org/wiki/Headless_content_management_system