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)
allis the only artifact the pipeline deploys. It embeds the others withembeddedsinfilevault-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/appsand/oak:index;ui.content(packageType=content) covers/conf,/content,/home. A mixed package fails the Cloud Manager "Customer Package Quality" check. ui.apps.structureexists 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"/>withoutmode="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
/appsand/libsare 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.yamland the other config-pipeline files have a combined 100 KB limit.- There is no
/system/consoleon 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.