Org Skills

AEM project and repository layout

Supporting material for aem-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://github.com/adobe/aem-project-archetype and https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/aem-project-content-package-structure

Open this when laying out a new project, splitting an inherited one, or deciding which module a file belongs in.

Maven AEM Project Archetype modules

core                ← OSGi bundle: Sling Models, services, servlets, filters
ui.apps             ← /apps: components, HTL, dialogs, clientlib output, _oak_index (immutable)
ui.apps.structure   ← empty repository roots (/apps/<proj>, /content/<proj>) so packages validate
ui.config           ← OSGi configs: /apps/<proj>/osgiconfig/config[.<runmode>]/*.cfg.json
ui.content          ← mutable content: /conf templates & policies, /content seed pages, CF models
ui.frontend         ← webpack/Vite build, output copied into ui.apps as a clientlib
dispatcher          ← Apache httpd + dispatcher config (flexible mode on Cloud Service)
all                 ← container package embedding every other package; the only deployable
it.tests            ← HTTP integration tests against a running instance
ui.tests            ← UI tests (Cypress by default; Playwright, WebdriverIO, Selenium supported)
  • all is the only artifact the pipeline deploys. It embeds the others with embeddeds in filevault-package-maven-plugin, each into /apps/<proj>-packages/{application|content}/install.
  • Never mix mutable and immutable content in one package. ui.apps (packageType=application) covers /apps and /oak:index; ui.content (packageType=content) covers /conf, /content, /home. A mixed package fails the Cloud Manager "Customer Package Quality" check.
  • ui.apps.structure exists so the other packages can declare <dependency> on repository roots they do not own; without it, FileVault validation complains about undeclared roots.

filter.xml and merge modes

<!-- ui.apps: owns /apps entirely, replace is correct -->
<filter root="/apps/acme"/>
<filter root="/oak:index/acme.article-1-custom-1"/>

<!-- ui.content: authors own this content after the first deploy -->
<filter root="/conf/acme" mode="merge"/>
<filter root="/content/acme" mode="merge"/>
  • Default mode is replace: everything under the root that is not in the package is deleted. A <filter root="/content/acme"/> without mode="merge" wipes authored content on every deploy — the single most damaging mistake in an AEM package.
  • Use mode="merge" for anything authors touch, and narrow the root (/conf/acme/settings/wcm/templates/article) rather than shipping a whole tree.
  • Index definitions get one filter entry per version; see ../../../development/aem-backend-development/references/oak-index-naming.md.

Where content lives

Path Holds Rule
/apps/<proj> Components, clientlibs, dialogs, OSGi config Code only, immutable at runtime; never written to by code
/libs Product code Never overlay; extend with sling:resourceSuperType instead
/conf/<proj> Editable templates, policies, CF models, cloud configs, Context-Aware Configuration Seeded by ui.content, then owned by template authors
/content/<site> Pages, organised /<brand>/<country>/<language> Tree shape drives MSM, URLs and cache invalidation blast radius
/content/dam/<proj> Assets and Content Fragments Metadata schemas and processing profiles per folder; keep folders in the thousands, not the hundred-thousands
/content/experience-fragments/<proj> Headers, footers, promos Mirror the site tree so MSM and language copies work
/var Workflow instances, audit, statistics Runtime data with purge policies; never content of record
/etc Legacy Nothing new goes here; on Cloud Service most of it is gone

Cloud Service hard limits worth designing around

  • /apps and /libs are read-only at runtime. Anything that needs to change without a deployment lives in /conf (Context-Aware Configuration) or in an OSGi value from $[env:…].
  • Run modes are fixed (author, publish, dev, stage, prod, rde); there are no custom run modes.
  • Publish pods are disposable: repository writes on publish are lost on recycle, reverse replication is unsupported, and there is no usable local file system.
  • The Adobe-managed CDN does not support ESI. Server-side includes (mod_include) work on the dispatcher; otherwise fetch client-side.
  • cdn.yaml and the other config-pipeline files have a combined 100 KB limit.
  • There is no /system/console on production and no Package Manager deployment path — everything ships through Cloud Manager.

Git layout

One repository per AEM project is the default: the archetype modules, the dispatcher config and the front-end sources together, so a single pipeline run deploys a consistent set. Split only when a front-end team needs its own release cadence — and then use the front-end pipeline, not a second full-stack repository. Edge Delivery Services sites are the exception: their block code lives in its own repository and deploys through Code Sync, not Cloud Manager.