# How Agility Works: A 10-Minute Architecture Tour

> Source: https://agilitycms.com/docs/overview/how-agility-works

This page gives you the mental model for the rest of the documentation. It covers the building blocks, how content is read and how it is written, how pages differ from content, and what Agility deliberately leaves to other tools. For the full training version, see [Core CMS Concepts](/docs/training-guide/concepts#2-headless-architecture) in the Training Guide.

## The one-paragraph version

Agility is a hosted, headless CMS. Editors create content and pages in the Agility Content Manager. When they publish, that content becomes available through Agility's content APIs and asset CDN. Your website or app, which you build and host yourself, reads it from there. Writes come in through the editors' UI, or through the Management API for scripts, migrations and AI agents. Webhooks tell your systems when something changed.

![How content flows through Agility CMS. Agility CMS holds content, pages and media. Publishing makes content available through the Content Fetch API and images through the Asset CDN, which your website and other apps read. A publish webhook tells your site to revalidate. Writes go the other way: AI agents connect through the MCP server, and scripts and CI use the SDKs and CLI, all through the Management API.](https://cdn.aglty.io/agility-cms-docs/images/training-guide/docs-diagram-headless-architecture.svg)

## The building blocks

| Block | What it is |
| --- | --- |
| **Organization** | Groups your instances, plans and billing, and controls how users sign in (single sign-on, MFA). |
| **Instance** | A dedicated area where editors create, manage and publish content. One instance can power one site or app, or several. Users, locales and API keys belong to an instance. |
| **Models** | The schemas. **Content models** define structured content, **component models** define the building blocks editors place on pages, and **page models** define page layouts with zones where components go. Each component model and page model corresponds to code in your front end. |
| **Content** | Items and lists based on content models. Content isn't tied to a page, so the same item can appear on many pages and in other channels through the API. |
| **Pages and sitemaps** | A sitemap is a page tree for one destination, such as a website, an app or digital signage. An instance can have several. Pages hold page-level SEO and the components editors arrange in each zone. |
| **Assets** | Images and files in the media library, served from a global CDN. |

The [Concepts](/docs/overview/concepts) page lists the full hierarchy.

## Content vs pages and sitemaps

This is the distinction that most shapes an Agility project.

- **Content** is structured and reusable. A blog post, a product, a team member or a footer is content. Your code can request it from anywhere: a website, an app, a search index.
- **Pages** are how editors control a website. They add and remove pages in the sitemap, choose a page model, place components in its zones and set SEO properties, without a developer. A component can show its own fields or pull in content from a list.
- **Dynamic pages** connect the two: one page in the sitemap generates a page per item in a content list, such as one page per blog post. See [Generating Dynamic Pages From Content](/docs/editors/generating-dynamic-pages-from-content).

You can use content alone, with your code deciding what pages exist, or use page management as well. [Headless, Hybrid or Traditional: Choose Your Delivery Model](/docs/overview/choose-your-delivery-model) compares the options, and [Pages vs Content](/docs/editors/pages-vs-content) explains the difference for editors.

## The read path

How content gets from Agility to the people using your site:

1. **An editor publishes.** Content and pages have states. Saved changes stay in Staging until they are published, either directly, on a schedule, or together in a batch. Approval workflows can sit in between.
2. **The content APIs serve it.** The [Content Fetch API](/docs/developers/content-fetch-api) (REST) and the [GraphQL API](/docs/developers/graphql-api) return published content with a fetch API key, or the latest saved content with a preview key. Responses are served through a global CDN, and Agility invalidates the cached content at the edge when you publish ([Content Delivery & CDN Architecture](/docs/developers/content-delivery-and-cdn-architecture)).
3. **Assets come from the asset CDN.** Images can be resized and converted on the fly with query strings.
4. **Your front end renders and caches.** Your site fetches content at build time or on request, renders it, and serves it from its own hosting and CDN.
5. **A webhook tells your site to refresh.** Agility calls your [webhook](/docs/developers/webhooks) endpoint when content is published, so your site can revalidate just what changed.

If your app needs its own copy of the content, for offline use, a search index or very high read volume, the [Content Sync API](/docs/developers/content-sync-api) returns everything that changed since your last sync.

## The write path

How content gets into Agility:

- **Editors** work in the Content Manager and in [Web Studio](/docs/overview/web-studio), which shows your real site inside Agility for preview, commenting and in-context editing.
- **Scripts, migrations and CI** use the [Management API](/docs/developers/content-management-api), through the JavaScript and .NET Management SDKs or the [Agility CLI](/docs/developers/cli).
- **AI agents** use the [Agility CMS MCP Server](/docs/developers/agility-cms-mcp-server), which calls the Management API on the user's behalf.

All three act with a user's own permissions. Content saved through the Management API or the MCP server lands in Staging, the same as an editor's save, and goes live only when it is published. That keeps workflow and approvals in force no matter who, or what, made the change ([Governing AI Access to Agility CMS](/docs/owners-admins/governing-ai-access)).

## Where things run

- **Agility hosts the CMS** on Microsoft Azure. There is nothing to install or patch.
- **Agility's APIs and assets** are served through a global CDN in front of the platform.
- **Your front end runs wherever you host it.** Agility has built-in integrations with Vercel and Netlify, but you can deploy anywhere.
- **Each instance lives in a data region.** See [Data Residency & Data Regions](/docs/owners-admins/data-residency-and-data-regions).

## What Agility is not

Knowing the edges makes the rest easier to plan:

- **Not your website host.** You build and deploy the site or app. Agility provides the content and the editing experience.
- **Not a self-hosted CMS.** Agility is a cloud service. You don't install it on your own servers.
- **Not a search engine.** Agility feeds the search provider you choose. See [Searching Content at Scale](/docs/overview/searching-content-at-scale).
- **Not a forms, analytics or experimentation tool.** Apps connect those tools to the CMS, and editors can manage A/B test variants as content, but the tools themselves are separate.
- **Not a commerce engine.** For a store, Agility manages the content and a commerce platform manages products, carts and checkout. See [Building a Headless Ecommerce Website](/docs/overview/build-a-headless-ecommerce-website).

[What Your Team Builds vs What Agility Provides](/docs/overview/what-your-team-builds-vs-what-agility-provides) turns this into a full responsibility map.

## Go deeper

- [Core CMS Concepts](/docs/training-guide/concepts): the data model and headless architecture in detail
- [Architecture Deep Dive](/docs/training-guide/developer-architecture) in the Developer Training Guide
- [Content Architecture](/docs/overview/content-architecture)
- [Content Sync Explained](/docs/developers/content-sync-explained): Sync vs Fetch vs GraphQL

---

## Related pages

- [Evaluating Agility](https://agilitycms.com/docs/overview/evaluating-agility.md)
- [What Your Team Builds vs What Agility Provides](https://agilitycms.com/docs/overview/what-your-team-builds-vs-what-agility-provides.md)
- [Is Agility Right for Your Project? When It Fits and When It Doesn't](https://agilitycms.com/docs/overview/is-agility-right-for-your-project.md)
- [Choosing a Headless CMS: A Capability Checklist and Questions to Ask Any Vendor](https://agilitycms.com/docs/overview/choosing-a-headless-cms.md)
- [Run a Two-Week Proof of Concept](https://agilitycms.com/docs/overview/run-a-two-week-proof-of-concept.md)
- [Headless, Hybrid or Traditional: Choose Your Delivery Model](https://agilitycms.com/docs/overview/choose-your-delivery-model.md)
- [Getting Your Content Out: Data Portability and Exit](https://agilitycms.com/docs/overview/data-portability-and-exit.md)
- [Building the Replatforming Business Case](https://agilitycms.com/docs/overview/replatforming-business-case.md)
- [Evaluate Agility with an AI Agent in 30 Minutes](https://agilitycms.com/docs/overview/evaluate-agility-with-an-ai-agent.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt