AEM Sites Architect Master cheat sheet

Non-functional requirements (concurrency, p95 latency, content volume, locales) drive architecture decisions more than feature lists; capture them before template design.

Sling resource resolution order: resource resolver search paths, then sling:resourceSuperType chains; component inheritance depth affects upgrade and override risk.

Author vs. publish separation is mandatory in AEM as a Cloud Service; any requirement implying direct publish writes must be redesigned through replication or the content distribution pipeline.

For headless requirements, choose between Content Services (JSON via model/schema) and GraphQL persisted queries based on caching needs and client query flexibility.

Multi-site requirements map to MSM live copies when content is inherited/rolled out, and to separate site roots when content is independently authored.

Estimate repository growth per locale and per workflow step; TarMK segment growth and online compaction limits constrain very large single-repository designs.

Integration requirements should specify direction (push/pull), payload size, retry semantics, and idempotency before selecting Sling Servlets, Jobs, or external middleware.

Prefer HTL with Sightly-style data-sly-use; JSP is legacy and not supported for new components in Cloud Service archetypes.

Use Sling Models with @Model(adaptables = Resource.class) and inject via @ValueMapValue/@ChildResource; OSGi services hold business logic, models stay thin.

Client-side libraries: the newer clientlib pipeline via aem-clientlib-as-a-service or the ui.frontend webpack build; avoid inline JS in HTL for CSP compatibility.

Component dialog fields should map cleanly to Granite/Coral widgets; use the Component Console for policy-aware authoring constraints.

Expose component data through a JSON exporter (ExporterConstants.SLING_MODEL_EXPORTER) rather than bespoke servlets for headless reuse.

Use the WCM Core Components as a baseline; extend via proxy components with sling:resourceSuperType to inherit behavior and policy support.

Decouple presentation from content: component models should not read request parameters directly; use request-scoped models or selectors.

Editable templates store structure in /conf//settings/wcm/templates//structure and content policies in .../policies; static templates live under /apps and are legacy.

Template types: page templates (with initial content), and experience fragment templates; each has allowed components defined by policies on the template's policy mapping.

Policy mapping precedence: explicit policy on the component node wins over the template-level policy mapping, which wins over the global policy.

Layout Container policies control allowed components; the responsive grid is configured per breakpoint in the template's structure.

Template and policy changes are content changes, not code deploys; they replicate like pages and must be included in content packages for promotion.

Locked structure components (locked=true) cannot be edited by authors; use them to protect header/footer containers.

The template editor requires the template-authors group; policy editing requires the template-authors or specific policy permissions.

Content Fragment Models are defined under /conf//settings/dam/cfm/models and are versioned; model changes affect existing fragments and may require migration.

Content Fragments are assets (dam:Asset) with structured data; delivery via GraphQL or Content Services JSON, not via component rendering by default.

Experience Fragments are page-like (cq:Page) and are rendered as HTML; they are reusable across channels and can be exported to Adobe Target.

Use CF for structured, channel-agnostic content (products, articles); use XF for layout-bearing reusable experiences (headers, promos).

GraphQL persisted queries are required in Cloud Service for production; ad-hoc queries are disabled or restricted by default.

Fragment variations allow locale or channel variants within one fragment; the master variation is the fallback.

Multifield and fragment references in CF models create nested structures; depth affects GraphQL query complexity and caching.

Content Services exposes JSON via Sling Model Exporter with a .model.json selector; GraphQL exposes a schema derived from CF models.

GraphQL endpoint: /content/cq:graphql//endpoint.json; POST with query, variables, and operationName; persisted queries referenced by hash.

Use the Asset Compute Service or custom workers for asset processing; avoid heavy processing on publish.

For push integrations, use Sling Jobs with retry and dead-letter handling; avoid synchronous servlet calls to external systems in authoring flows.

Authentication for integrations: service users with least privilege, OAuth server-to-server for Adobe I/O, and IMS for Cloud Service admin APIs.

Webhooks and Adobe I/O Events provide event-driven integration; AEM as a Cloud Service supports events for asset and content changes.

Rate limiting and timeouts must be explicit; the AEM HTTP client (Apache HttpClient via OSGi factory) should be used instead of raw URL connections.

AEM as a Cloud Service environments: dev, stage, prod; code deploys via Cloud Manager pipelines (full-stack or frontend).

Cloud Service enforces immutable, containerized author/publish; no direct access to the underlying OS or CRXDE for production changes.

Cloud Manager uses git-based pipelines; config in /conf and /apps must be deployed via code or content packages, not manual replication.

On-premise/AMS uses package manager and replication agents; Cloud Service replaces replication agents with the content distribution pipeline.

Environment variables and OSGi configs are managed via Cloud Manager config pipelines (YAML) in Cloud Service.

The dispatcher configuration is validated by the Cloud Manager dispatcher validator; invalid configs fail the pipeline.

Blue/green deployment and content copy between environments use Cloud Manager's copy content feature; large copies have time limits.

Dispatcher caches based on /cache rules; default ignores query strings unless explicitly allowed, and honors Cache-Control and TTL.

Use /statfileslevel and /ignoreUrlParams to control cache invalidation granularity; higher statfiles levels reduce invalidation scope.

Author and publish dispatchers have different configs; never cache authenticated or personalized responses.

Client-side caching: set Cache-Control and Surrogate-Control headers in the component or via the dispatcher; use ETags for conditional requests.

Query parameter-based personalization breaks dispatcher caching; move to client-side personalization or edge-side includes.

AEM's built-in dispatcher flush agents invalidate cache on activation; configure flush rules to match statfiles levels.

Measure with the request log and dispatcher hit ratio; a low hit ratio often indicates uncacheable headers or cookie-based variance.

ACLs are stored in rep:policy nodes; permissions are allow/deny per principal; deny takes precedence over allow at the same path.

Use closed user groups (CUG) for protected content; CUG requires authentication and is enforced by the authentication handler.

Service users (rep:serviceUser) replace admin sessions; map service users to least-privilege groups and disable login for them.

The AEM security checklist covers dispatcher filters, CSRF protection, and the removal of default users; CSRF tokens are required for POST.

Granite authentication handlers and SAML/OAuth integrations are configured via OSGi; IMS is the identity provider for Cloud Service.

Permissions on /apps and /libs should be read-only for authors; template and policy editing requires specific groups.

Sling servlet registration should restrict by resource type and method; open servlets are a common vulnerability.

AEM 6.x to Cloud Service migration uses the Content Transfer Tool (CTT) and the Best Practices Analyzer (BPA) to identify incompatibilities.

Pattern Detector and BPA reports flag deprecated APIs, static templates, and unsupported features before migration.

MSM live copies use roll-out configs; inheritance is broken by editing inherited properties, and the rollout config controls which properties sync.

Blueprints and live copies support multiple locales; language copies use the translation workflow or MSM depending on inheritance needs.

Package migration must respect immutable paths; /libs and /apps changes go through code deploys, not packages.

Upgrade compatibility: check the API deprecation list and the compatibility package; remove deprecated APIs before major upgrades.

Multi-site content sharing via live copies reduces authoring duplication but increases rollout complexity; document rollout triggers.

Common publish issues: missing service user permissions, dispatcher cache serving stale content, and replication queue blockage.

Use the error log, request log, and thread dumps; the AEM Health Check and the system console show OSGi bundle states.

Governance: code reviews, component library standards, naming conventions, and content package structure must be enforced in pipelines.

Avoid storing secrets in code or content; use Cloud Manager environment variables and secret references.

Performance regressions often trace to uncached queries, large result sets, or missing indexes; use the query performance tool.

Keep custom code minimal and prefer core components and out-of-the-box features; every custom OSGi bundle is a maintenance cost.

Document runbooks for cache flush, replication, and rollback; test rollback in stage before production changes.