# Reference Architectures

> Source: https://agilitycms.com/docs/developers/reference-architectures

A reference architecture shows one proven shape for a whole solution built on Agility: which parts you build, which parts Agility runs, how content moves between them, where it is cached, how editors preview it, and what breaks first. Use these pages to choose a starting shape and to explain it to your team. The implementation guides they link to cover how to build each part.

## The building blocks

Every architecture on these pages is put together from the same Agility pieces.

| Building block | What it does | Learn more |
| --- | --- | --- |
| **Instance** | One Agility project: its own content, assets, users, roles, API keys, webhooks and data region | [Choose Your Tenancy Model](/docs/developers/choose-your-tenancy-model) |
| **Sitemaps and channels** | Page trees. An instance can have several, each with its own pages, domains and preview URL | [Sitemaps](/docs/developers/sitemaps) |
| **Content Fetch API and GraphQL API** | Read published content (fetch key) or the latest saved content (preview key) | [Content Fetch API](/docs/developers/content-fetch-api), [GraphQL API](/docs/developers/graphql-api) |
| **Content Sync** | Copy content into a store you own and keep it up to date with a sync token | [Content Sync Explained](/docs/developers/content-sync-explained) |
| **Webhooks** | Tell your systems that content was saved, published, unpublished or moved through workflow | [Webhook Events and Payload Reference](/docs/developers/webhook-events-and-payloads) |
| **Preview and Web Studio** | Show editors saved, unpublished changes on your own site, inside Agility | [Setting Up Preview](/docs/developers/setting-up-preview), [Set Up Web Studio with Any Framework](/docs/developers/web-studio-setup-any-framework) |
| **Asset CDN** | Serves images and files from `cdn.aglty.io`, with image transformations by query string | [Image Transformation Reference](/docs/developers/image-transformation-reference) |
| **Management API, SDKs, CLI and MCP server** | Write content, models and settings from code, pipelines and AI tools | [Content Management API](/docs/developers/content-management-api) |

## The shape they all share

Agility is the content system. Your team builds and hosts the front end. Between the two sit two CDN layers: Agility's, in front of the content APIs and assets, and your own, in front of your rendered pages. See [Content Delivery & CDN Architecture](/docs/developers/content-delivery-and-cdn-architecture).

| Step | From | To | What happens |
| --- | --- | --- | --- |
| 1 | Visitor's browser | Your CDN or host | Most requests are answered with a page that is already rendered and cached |
| 2 | Your host | Your app | A cache miss, or a page that must be rendered per request |
| 3 | Your app | Your data cache | Content the app has already fetched is reused |
| 4 | Your app | Agility Content Fetch or GraphQL API | A response cached on Agility's CDN is returned without reaching the API |
| 5 | Agility | Your webhook endpoint | On publish, your app learns what changed and clears the matching cache entries |
| 6 | Visitor's browser | `cdn.aglty.io` | Images and files load straight from Agility's asset CDN |

Two rules follow from this shape and apply to every page below:

- **Read from a cache first, and invalidate on publish.** Agility clears its own CDN when content is published, but not yours. Wire a webhook to your cache. The API's rate limit only counts requests that miss Agility's CDN.
- **Keep the write path and the preview path separate from the read path.** Preview keys, Management API tokens and webhook secrets belong on servers, never in a browser or an app binary.

## The architectures

| Architecture | Choose it when | Key decision |
| --- | --- | --- |
| [Marketing website](/docs/developers/reference-architecture-marketing-site) | One brand's public website, managed page by page by marketers | How you cache and how publishing clears the cache |
| [Multi-brand and multi-site](/docs/developers/reference-architecture-multi-brand) | Several brands, regions or microsites share a team, a model or content | One instance with several sitemaps, or several instances |
| [Headless commerce](/docs/developers/reference-architecture-headless-commerce) | A commerce platform owns products, prices and checkout; marketers own the story around them | Which system owns each piece of data |
| Member portal and intranet | Some content is only for signed-in people | Where access is enforced, and what is public by design |
| [Multi-channel delivery](/docs/developers/reference-architecture-multi-channel) | The same content reaches a website, an app, email, kiosks or screens | Pull, push or local copy for each channel |

Most real solutions combine two or more of these. A retailer might run a multi-brand setup in which each brand site is also a commerce site, with an app reading the same content.

## Decisions every architecture makes

- **Tenancy:** one instance or several. See [Choose Your Tenancy Model](/docs/developers/choose-your-tenancy-model).
- **Locales:** field level, page level or instance level. See [Choosing a Localization Strategy](/docs/developers/choosing-a-localization-strategy).
- **Resilience:** what your site does when an API call is slow, limited or failing. See [Handle Rate Limits and Outages Gracefully](/docs/developers/handle-rate-limits-and-outages).
- **Security headers and network rules:** which Agility hosts your site, your servers and your editors need. See Content Security Policy and Network Allowlist.
- **Front-end framework:** see [Why We Recommend Next.js and .NET](/docs/developers/why-we-recommend-nextjs-and-dotnet).

## Related

- [Content Delivery & CDN Architecture](/docs/developers/content-delivery-and-cdn-architecture)
- [Using Agility for Multiple Sites](/docs/overview/using-agility-cms-for-multiple-sites)
- [Publishing to Multiple Destinations](/docs/overview/publishing-to-multiple-destinations)
- [Building a Content Hub](/docs/overview/building-a-content-hub)