---
title: How It Works
description: The build pipeline, runtime data flow, and what happens under the hood.
canonical_url: https://next-ai-ready.vercel.app/en/docs/concepts/how-it-works
url: https://next-ai-ready.vercel.app/en/docs/concepts/how-it-works
last_updated: 2026-06-02
updated: 2026-06-02
author: next-ai-ready team
summary: The build pipeline, runtime data flow, and what happens under the hood.
topics: [architecture, knowledge-plane, capability-plane]
---

# How It Works

This page walks through what happens from `next-ai-ready build` to a live AI-ready endpoint.

## Build pipeline

When you run `npx next-ai-ready build`:

1. **Load config** — reads `ai-ready.config.mjs` for site metadata, content globs, and action paths.
2. **Scan content** — uses `fast-glob` to find all MDX/MD files matching your `content` globs.
3. **Compile** — each file passes through the unified pipeline: parse MDX, extract headings/FAQ/entities/summary, strip JSX to clean Markdown, chunk by token budget.
4. **Build graph** — assembles all compiled pages into a `SemanticGraph` with stable node IDs and route mappings.
5. **Emit Knowledge artifacts** — writes `graph.json`, `llms.txt`, `llms-full.txt`, and `robots.txt`.
6. **Emit Capability artifacts** — loads your actions, builds the manifest, writes `actions.manifest.json`, `openapi.json`, `tools.json`, and `ai-plugin.json`.

All JSON output is deterministic: stable key order, no timestamps in payload (except `generatedAt` in a header field), stable node IDs.

## Runtime data flow

At runtime, each AI endpoint reads a cached JSON file:

| Endpoint                  | Reads                               | Response           |
| ------------------------- | ----------------------------------- | ------------------ |
| `/llms.txt`               | static file from `public/`          | `text/plain`       |
| `/<route>.md`             | `graph.json` → node body            | `text/markdown`    |
| `/<route>.ai.json`        | `graph.json` → node tree            | `application/json` |
| `/openapi.json`           | `actions.manifest.json`             | `application/json` |
| `POST /api/actions/:name` | imports handler, validates with Zod | result JSON        |
| `/api/mcp`                | `vercel/mcp-handler` + registry     | MCP stream         |

Each handler reads its JSON source once per process and holds it in memory. Invalidation happens on the next deploy (production) or on file change via `next-ai-ready dev` (development).

## Why a separate build step?

The build CLI runs **outside** the bundler. This is deliberate ([ADR-006](/docs/decisions/adr-006)):

- Turbopack does not accept custom plugins. A webpack-only plugin would break Next 15+ defaults.
- Decoupling from the bundler makes the pipeline portable — it can run in CI before `next build`.
- Same pattern used by Contentlayer, Velite, and fumadocs-mdx.

The cost is one extra line in your build script: `next-ai-ready build && next build`. The benefit is that your AI layer works identically under Webpack and Turbopack.

## What `withAiReady()` does

The `withAiReady()` wrapper in `next.config.mjs` does two things:

1. **Adds rewrites** — maps clean URLs (`/llms.txt`, `/<route>.md`, `/openapi.json`) to internal handler routes.
2. **Enables file tracing** — ensures `.next-ai-ready/*.json` ships with serverless function bundles.

It does **not** register bundler plugins, inject routes, or use virtual modules. This keeps it Turbopack-safe.