Designs Adobe Experience Manager solution architecture and writes the decision record — Cloud Service vs 6.5, delivery model (HTL Sites, headless Content Fragments + GraphQL, Universal Editor hybrid, Edge Delivery Services), repository and package structure, MSM and translation, integrations, caching and personalization, identity, environments and NFRs.
When agents use itUse this whenever the user asks how to structure an AEM project, whether to go headless or use Edge Delivery Services, compares AEMaaCS with AMS or on-prem, plans a multi-site or multi-language estate with blueprints, live copies or language copies, asks where code or content should live (/apps, /conf, /content, /content/dam, /var), about ui.apps vs ui.content or mutable vs immutable packages, about Adobe IMS product profiles or App Builder as an extension point, or needs an ADR or solution outline for AEM. Also apply it when a component or integration question hides a platform decision such as caching or authentication.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-architecture -a github-copilot
# or with the org installer (adds .github/skills/aem-architecture):
npx -y github:AGCO-Global/org-skills add skill aem-architecture
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-architecture-skills plugin, which bundles all AEM / Architecture skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-architecture-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-architecture -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-architecture -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-architecture -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-architecture -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-architecture folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
AEM architecture is mostly a caching and content-modelling problem wearing a CMS costume. Decide first how every page and API response gets cached at the CDN, how authors reuse content across sites and languages, and which platform limits are non-negotiable — components come last. Every decision belongs in a written record with its consequence, because the next team will otherwise re-derive it wrongly.
1. Decide first
Question
Default
Change when
Platform
AEM as a Cloud Service
Regulatory hosting, an unsupported native dependency, or a migration that is not funded → 6.5 LTS, with the constraint written into the ADR
Delivery model
Per experience, from references/delivery-models.md
Never by company-wide decree; mixing EDS + headless on one content model is normal
Visual editing on a decoupled front end
Universal Editor
Form-based editing is enough → Content Fragment editor, no instrumentation
New SPA Editor project
Not an option — deprecated with AEMaaCS 2025.01 and 6.5.23
Only to maintain an existing SPA Editor site (P1/P2 and security fixes only)
Repository split
/apps immutable, /conf + /content mutable, separate packages
Never mixed — Cloud Service rejects mixed packages
Per-site variation
MSM live copies from a blueprint
Sites share only brand assets, not structure → independent trees
Personalization
Client-side (Web SDK / a small JSON fetch)
Edge or Sling Dynamic Include when the fragment must be server-rendered; uncached personalised HTML last
Custom platform extension
Sling/OSGi in core
Long-running, spiky, or third-party-facing work → Adobe Developer App Builder, off the publish tier
Identity for authors
Adobe IMS with Admin Console product profiles mapped to AEM groups
6.5: SAML/LDAP; permissions always to groups, never to users
Cloud Service limits that shape designs: no custom run modes; no ESI at the Adobe CDN (server-side includes via mod_include do work); publish repository writes are lost when a pod recycles; no reverse replication; no custom replication agents; /apps and /libs read-only at runtime; config-pipeline files (including cdn.yaml) capped at 100 KB total.
2. Delivery model and content model
Pick the delivery model per experience using the table in references/delivery-models.md; record the choice, the date and the reason. Do not restate the table in the ADR — link it.
Content Fragments are structured, channel-neutral data (model-driven, queried by GraphQL or the Content Fragment Delivery OpenAPI). Experience Fragments are presentational and reusable layout. A CF used for layout, or an XF used as a data store, becomes unmaintainable within a release or two.
Model fragments for the data, not for the first channel that consumes them: fragment references over deep nesting, one model per real-world entity, and no presentation fields (cssClass, columnWidth).
Editable templates + policies in /conf decide allowed components, styles and image widths. Changing a policy changes every page using it, so name an owner in the ADR.
3. Repository, packages and environments
Module layout, filter.xml merge modes, the path table and the Cloud Service limits are in references/repository-layout.md. Two rules never move: mutable and immutable content ship in separate packages, and any filter root authors touch carries mode="merge".
Per-environment values come from $[env:NAME] / $[secret:NAME] in ui.config, never from a hostname in Git. Per-site values come from Context-Aware Configuration under /conf.
Custom Oak indexes follow one naming rule, owned by aem-backend-development: oak-index-naming.md in ../../development/aem-backend-development/references/. Do not invent a second convention in the ADR.
Environments: dev → stage → prod through Cloud Manager, plus RDEs for fast iteration. Stage mirrors prod and is the only place load tests mean anything.
4. Multi-site, translation and assets
Blueprint → live copies (MSM) for shared structure across markets; language masters → language copies for translation. A typical tree is /content/acme/language-masters/en → /content/acme/de/de.
Decide inheritance granularity up front: which components may break inheritance and who re-enables it. Uncontrolled cancel-inheritance is the main MSM failure mode, and it is invisible until a rollout silently skips markets.
Translate Content Fragments and Experience Fragments in the same translation project as the pages that use them; UI strings stay in i18n dictionaries in /apps.
Assets: metadata schemas and folder-level processing profiles; Dynamic Media with OpenAPI or web-optimized image delivery instead of dozens of static renditions. AEM Assets can also be the headless DAM for non-AEM channels — see aem-assets.
5. Integrations, identity and caching
Adobe Analytics and Target through Tags and the Web SDK with a documented data-layer contract; never a hardcoded vendor script in HTL. Commerce through CIF, with product data cached at the edge, not copied into the JCR.
External APIs through an OSGi service with connect and read timeouts, a fallback and a short cache (aem-backend-development). Per-user data is fetched client-side or at the edge so the page stays cacheable.
Authors: Adobe IMS, product profiles in the Admin Console mapped to AEM groups, permissions granted to groups and managed as repoinit where possible. Site visitors behind a login: see aem-security for CUGs and permission-sensitive caching.
Caching layers are CDN → Dispatcher → Publish, with an anonymous CDN hit ratio target above 90 %. Design URLs for caching: selectors and suffixes over query strings, one canonical URL per representation, no per-user data in HTML. Invalidation is by path and, on the Adobe CDN, by Surrogate-Key through the self-serve purge API. Rules and syntax belong to aem-dispatcher.
6. Deliverable format
## Context — goals, channels, sites × languages, traffic and NFR numbers
## Decisions — one row each: decision · options · choice · rationale · consequences
## Logical architecture — CDN / dispatcher / author / publish / integrations (text or Mermaid)
## Content model — templates, CF models, XF usage, /content and /content/dam trees
## Caching plan — per URL pattern: TTL · cacheable? · invalidation trigger · surrogate key
## Identity and access — IMS profiles → AEM groups; visitor auth; service users
## NFRs — peak req/s, hit-ratio target, TTFB/LCP budget, author concurrency, asset volume, RPO/RTO
## Risks and open questions — owner and due date each
Contract with sibling skills so the ADR does not re-derive them: caching rules → aem-dispatcher; queries and indexes → aem-backend-development; pipelines, env vars and RDE → aem-cloud-manager; GraphQL contract → aem-headless.
Checklist
Platform choice stated with the constraint that drove it, not a preference
Delivery model recorded per experience, linking references/delivery-models.md
No new SPA Editor work proposed
Mutable and immutable content are separate packages; author-owned filter roots use mode="merge"
Every URL pattern has a cacheability verdict, a TTL and an invalidation trigger
Personalization plan keeps anonymous HTML cacheable
MSM and translation model named, with an inheritance-breaking policy and an owner
Secrets and hostnames come from $[secret:] / $[env:]
NFRs are numbers, not adjectives
Cloud Service limits checked against the design (run modes, publish writes, ESI, 100 KB config)
Anti-patterns
"Headless because modern" while authors need page editing and MSM → pick per experience; a brief naming rollouts and workflows is a Sites brief.
Starting a new SPA Editor project → Universal Editor; SPA Editor is deprecated (2025.01).
One package containing /apps and /content → split into ui.apps and ui.content; Cloud Service rejects mixed packages.
<filter root="/content/acme"/> with no mode → mode="merge"; replace mode deletes authored content on deploy.
Per-user or cookie-dependent HTML on cacheable pages → move the personalised part to a client-side fetch.
Flat /content/dam folders with 100k+ assets → date- or product-based folder hierarchy in the thousands, set before ingestion starts.
Experience Fragments used as a data store → Content Fragments with a model.
Assuming 6.5 customisations lift and shift (custom replication agents, run modes, long publish jobs) → run the Best Practices Analyzer first (aem-cloud-migration).
NFRs written as "must be fast" → a TTFB and LCP budget plus a peak uncached request rate; autoscaling cannot rescue a low hit ratio.
Go deeper
references/delivery-models.md — the delivery-model comparison table and the deciding questions, shared by every AEM skill.
references/repository-layout.md — archetype modules, filter.xml merge modes, path-by-path rules and Cloud Service hard limits.
oak-index-naming.md in ../../development/aem-backend-development/references/ — the one index naming rule.
Sibling skills: aem-dispatcher for cache and CDN rules, aem-security for access design, aem-cloud-manager for pipelines and environments, aem-cloud-migration for 6.5 → Cloud, aem-headless and aem-edge-delivery-services for the two non-HTL models, aem-code-review for reviews.
---
name: aem-architecture
description: >
Designs Adobe Experience Manager solution architecture and writes the decision record — Cloud Service vs 6.5, delivery model (HTL Sites, headless Content Fragments + GraphQL, Universal Editor hybrid, Edge Delivery Services), repository and package structure, MSM and translation, integrations, caching and personalization, identity, environments and NFRs. Use this whenever the user asks how to structure an AEM project, whether to go headless or use Edge Delivery Services, compares AEMaaCS with AMS or on-prem, plans a multi-site or multi-language estate with blueprints, live copies or language copies, asks where code or content should live (/apps, /conf, /content, /content/dam, /var), about ui.apps vs ui.content or mutable vs immutable packages, about Adobe IMS product profiles or App Builder as an extension point, or needs an ADR or solution outline for AEM. Also apply it when a component or integration question hides a platform decision such as caching or authentication.
metadata:
technology: AEM
type: architecture
---
# AEM Architecture
> **Targets:** AEM as a Cloud Service 2026.x, AEM 6.5 / 6.5 LTS noted where different · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/overview/architecture
AEM architecture is mostly a caching and content-modelling problem wearing a CMS costume. Decide first how every page and API response gets cached at the CDN, how authors reuse content across sites and languages, and which platform limits are non-negotiable — components come last. Every decision belongs in a written record with its consequence, because the next team will otherwise re-derive it wrongly.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Platform | AEM as a Cloud Service | Regulatory hosting, an unsupported native dependency, or a migration that is not funded → 6.5 LTS, with the constraint written into the ADR |
| Delivery model | Per experience, from `references/delivery-models.md` | Never by company-wide decree; mixing EDS + headless on one content model is normal |
| Visual editing on a decoupled front end | Universal Editor | Form-based editing is enough → Content Fragment editor, no instrumentation |
| New SPA Editor project | Not an option — deprecated with AEMaaCS 2025.01 and 6.5.23 | Only to maintain an existing SPA Editor site (P1/P2 and security fixes only) |
| Repository split | `/apps` immutable, `/conf` + `/content` mutable, separate packages | Never mixed — Cloud Service rejects mixed packages |
| Per-site variation | MSM live copies from a blueprint | Sites share only brand assets, not structure → independent trees |
| Personalization | Client-side (Web SDK / a small JSON fetch) | Edge or Sling Dynamic Include when the fragment must be server-rendered; uncached personalised HTML last |
| Custom platform extension | Sling/OSGi in `core` | Long-running, spiky, or third-party-facing work → Adobe Developer App Builder, off the publish tier |
| Identity for authors | Adobe IMS with Admin Console product profiles mapped to AEM groups | 6.5: SAML/LDAP; permissions always to groups, never to users |
**Cloud Service limits that shape designs:** no custom run modes; no ESI at the Adobe CDN (server-side includes via `mod_include` do work); publish repository writes are lost when a pod recycles; no reverse replication; no custom replication agents; `/apps` and `/libs` read-only at runtime; config-pipeline files (including `cdn.yaml`) capped at 100 KB total.
## 2. Delivery model and content model
- Pick the delivery model per experience using the table in `references/delivery-models.md`; record the choice, the date and the reason. Do not restate the table in the ADR — link it.
- **Content Fragments** are structured, channel-neutral data (model-driven, queried by GraphQL or the Content Fragment Delivery OpenAPI). **Experience Fragments** are presentational and reusable layout. A CF used for layout, or an XF used as a data store, becomes unmaintainable within a release or two.
- Model fragments for the data, not for the first channel that consumes them: fragment references over deep nesting, one model per real-world entity, and no presentation fields (`cssClass`, `columnWidth`).
- **Editable templates + policies** in `/conf` decide allowed components, styles and image widths. Changing a policy changes every page using it, so name an owner in the ADR.
## 3. Repository, packages and environments
- Module layout, `filter.xml` merge modes, the path table and the Cloud Service limits are in `references/repository-layout.md`. Two rules never move: mutable and immutable content ship in separate packages, and any filter root authors touch carries `mode="merge"`.
- Per-environment values come from `$[env:NAME]` / `$[secret:NAME]` in `ui.config`, never from a hostname in Git. Per-site values come from Context-Aware Configuration under `/conf`.
- Custom Oak indexes follow one naming rule, owned by `aem-backend-development`: `oak-index-naming.md` in `../../development/aem-backend-development/references/`. Do not invent a second convention in the ADR.
- Environments: dev → stage → prod through Cloud Manager, plus RDEs for fast iteration. Stage mirrors prod and is the only place load tests mean anything.
## 4. Multi-site, translation and assets
- **Blueprint → live copies (MSM)** for shared structure across markets; **language masters → language copies** for translation. A typical tree is `/content/acme/language-masters/en` → `/content/acme/de/de`.
- Decide inheritance granularity up front: which components may break inheritance and who re-enables it. Uncontrolled cancel-inheritance is the main MSM failure mode, and it is invisible until a rollout silently skips markets.
- Translate Content Fragments and Experience Fragments in the same translation project as the pages that use them; UI strings stay in i18n dictionaries in `/apps`.
- Assets: metadata schemas and folder-level processing profiles; Dynamic Media with OpenAPI or web-optimized image delivery instead of dozens of static renditions. AEM Assets can also be the headless DAM for non-AEM channels — see `aem-assets`.
## 5. Integrations, identity and caching
- Adobe Analytics and Target through **Tags** and the Web SDK with a documented data-layer contract; never a hardcoded vendor script in HTL. Commerce through **CIF**, with product data cached at the edge, not copied into the JCR.
- External APIs through an OSGi service with connect and read timeouts, a fallback and a short cache (`aem-backend-development`). Per-user data is fetched client-side or at the edge so the page stays cacheable.
- Authors: Adobe IMS, product profiles in the Admin Console mapped to AEM groups, permissions granted to groups and managed as repoinit where possible. Site visitors behind a login: see `aem-security` for CUGs and permission-sensitive caching.
- Caching layers are **CDN → Dispatcher → Publish**, with an anonymous CDN hit ratio target above 90 %. Design URLs for caching: selectors and suffixes over query strings, one canonical URL per representation, no per-user data in HTML. Invalidation is by path *and*, on the Adobe CDN, by `Surrogate-Key` through the self-serve purge API. Rules and syntax belong to `aem-dispatcher`.
## 6. Deliverable format
```
## Context — goals, channels, sites × languages, traffic and NFR numbers
## Decisions — one row each: decision · options · choice · rationale · consequences
## Logical architecture — CDN / dispatcher / author / publish / integrations (text or Mermaid)
## Content model — templates, CF models, XF usage, /content and /content/dam trees
## Caching plan — per URL pattern: TTL · cacheable? · invalidation trigger · surrogate key
## Identity and access — IMS profiles → AEM groups; visitor auth; service users
## NFRs — peak req/s, hit-ratio target, TTFB/LCP budget, author concurrency, asset volume, RPO/RTO
## Risks and open questions — owner and due date each
```
Contract with sibling skills so the ADR does not re-derive them: caching rules → `aem-dispatcher`; queries and indexes → `aem-backend-development`; pipelines, env vars and RDE → `aem-cloud-manager`; GraphQL contract → `aem-headless`.
## Checklist
- [ ] Platform choice stated with the constraint that drove it, not a preference
- [ ] Delivery model recorded per experience, linking `references/delivery-models.md`
- [ ] No new SPA Editor work proposed
- [ ] Mutable and immutable content are separate packages; author-owned filter roots use `mode="merge"`
- [ ] Every URL pattern has a cacheability verdict, a TTL and an invalidation trigger
- [ ] Personalization plan keeps anonymous HTML cacheable
- [ ] MSM and translation model named, with an inheritance-breaking policy and an owner
- [ ] Secrets and hostnames come from `$[secret:]` / `$[env:]`
- [ ] NFRs are numbers, not adjectives
- [ ] Cloud Service limits checked against the design (run modes, publish writes, ESI, 100 KB config)
## Anti-patterns
- **"Headless because modern"** while authors need page editing and MSM → pick per experience; a brief naming rollouts and workflows is a Sites brief.
- **Starting a new SPA Editor project** → Universal Editor; SPA Editor is deprecated (2025.01).
- **One package containing `/apps` and `/content`** → split into `ui.apps` and `ui.content`; Cloud Service rejects mixed packages.
- **`<filter root="/content/acme"/>` with no mode** → `mode="merge"`; replace mode deletes authored content on deploy.
- **Per-user or cookie-dependent HTML on cacheable pages** → move the personalised part to a client-side fetch.
- **Flat `/content/dam` folders with 100k+ assets** → date- or product-based folder hierarchy in the thousands, set before ingestion starts.
- **Experience Fragments used as a data store** → Content Fragments with a model.
- **Assuming 6.5 customisations lift and shift** (custom replication agents, run modes, long publish jobs) → run the Best Practices Analyzer first (`aem-cloud-migration`).
- **NFRs written as "must be fast"** → a TTFB and LCP budget plus a peak uncached request rate; autoscaling cannot rescue a low hit ratio.
## Go deeper
- `references/delivery-models.md` — the delivery-model comparison table and the deciding questions, shared by every AEM skill.
- `references/repository-layout.md` — archetype modules, `filter.xml` merge modes, path-by-path rules and Cloud Service hard limits.
- `oak-index-naming.md` in `../../development/aem-backend-development/references/` — the one index naming rule.
- Sibling skills: `aem-dispatcher` for cache and CDN rules, `aem-security` for access design, `aem-cloud-manager` for pipelines and environments, `aem-cloud-migration` for 6.5 → Cloud, `aem-headless` and `aem-edge-delivery-services` for the two non-HTL models, `aem-code-review` for reviews.