# AEM project and repository layout

> **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

```xml
<!-- 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.
