# How it works

> Mental model: sites, headlines, drafts, posts, runs, taxonomy. The pull-based delivery model. Why Mentionwell is headless, not a CMS.

Mentionwell is a **headless content engine** with a public read-only API. Your destination site **pulls** content; Mentionwell never writes to your codebase.

## The data model

Five top-level objects live in Mentionwell's database. Most operations move data from one to the next.

- **Site** — one destination domain. Has a brand profile, taxonomy, delivery config, and an automation policy.
- **Taxonomy** — a tree of content clusters. Headlines get attached to nodes for topical authority + internal linking.
- **Headline** — a planned article. Has a target keyword, search intent, schedule, and lifecycle status (`proposed → approved → queued → generating → drafted → scheduled → published`).
- **Draft** — a generated article waiting on review. Includes HTML, Markdown, FAQs, JSON-LD, sources, and a measured cost.
- **Post** — a published article. Same shape as a draft plus `published: true` + `publishedAt`.

Plus **Run** (one execution of the planner / writer / critic / publish flow, with cost + duration) and **Job** (one worker run on the queue: onboarding, draft, publish, autopilot, refresh).

## The pipeline

```text
Site profile + taxonomy
        │
        ▼
   Headline ─────► Draft ─────► Post ─────► /api/public/.../posts
   (planner)      (writer +     (publish     (your site fetches)
                   critic)       flow)
```

Every step writes to the database; the API serves directly off the latest published row.

## Two halves: push and pull

Mentionwell supports both delivery directions, and most sites use one or both:

- **Pull (the default):** your destination reads the Reader API on its own schedule — every request (SSR), every revalidation (ISR / SWR), or every rebuild (static). Mentionwell doesn't have to do anything on publish — your site fetches when it next needs to render.
- **Push (optional):** Mentionwell calls a webhook on your destination the moment a post publishes, so the destination can revalidate cached paths or kick off a rebuild. This is what makes static sites publish in under a minute instead of waiting for the next cron rebuild.

The two halves are independent. A static site usually needs **both** (push to trigger a rebuild + pull during the rebuild to fetch new posts). An SSR site usually needs only **pull**. The [Connect wizard](/docs/connect-wizard) picks the right combination for your stack and saves it as the site's delivery mode.

| Wizard architecture | Push half | Pull half | When articles appear |
|---|---|---|---|
| **Static + deploy hook** | Webhook → deploy hook → rebuild | Build-time fetch | ~30–90s (rebuild time) |
| **Next.js ISR** | Webhook → `revalidatePath()` | Request-time fetch with `next: { tags }` | Seconds |
| **Dynamic / api_reader** | none (intentionally) | Request-time or short-TTL fetch | Next visit picks it up |
| **GitHub MDX** | MentionWell commits an MDX file to your repo | Your CI/CD picks up the commit | 1–3 min (commit + their CI build) |
| **CMS adapter** | Webhook → adapter → create-draft in your CMS | The CMS renders the post itself | Depends on CMS |

Three reasons the design leans into pull rather than push-only:

1. **No deploy on every post** (for SSR sites). You publish in Mentionwell and the next request picks it up. No CI run, no minutes burned.
2. **No coupling.** Your destination doesn't need a CMS adapter, plugin, or per-publish webhook unless you choose one — pull works with any framework.
3. **Caching is honest.** The Reader API returns ETag + Cache-Control headers tuned for SWR. Your CDN takes care of the rest.

## What lives where

| Concern | Where it lives |
|---|---|
| Article body (HTML, Markdown, JSON-LD, FAQ, TOC) | Mentionwell database, served via `/api/public` |
| Site chrome (header, footer, layout) | Your destination repo |
| URL structure (`/blog`, `/blog/[slug]`) | Your destination repo (typically) |
| SEO metadata for the article | Mentionwell returns it; your destination renders it into `<head>` |
| RSS / JSON Feed / sitemap | Mentionwell serves them; you link to them from your destination |
| Auth + roles | Mentionwell handles internal auth; your destination only needs the read API key |

## What Mentionwell is *not*

- Not a CMS. There's no rich-text editor for non-technical users; it's an AI editorial pipeline.
- Not a static site generator. Posts aren't built into your site at deploy time.
- Not a CDN. The reader API has caching headers; your destination's CDN does the actual edge serving.

> Once this model clicks, every weird symptom ("post isn't showing", "it's stale", "preview is fine but prod isn't") collapses to either: env var wrong, cache stale, or post not published yet. Treat those three as your first checks every time.


---

Canonical URL: https://mentionwell.com/docs/concepts
Live HTML version: https://mentionwell.com/docs/concepts
Section: Get started
Site index for AI ingestion: https://mentionwell.com/llms.txt
Full reference: https://mentionwell.com/llms-full.txt