When you generated a project from Adobe's Maven archetype earlier in this series, it created several modules with cryptic-looking names — core, ui.apps, ui.content, ui.config, and more. This post breaks down what each module is for and why AEM projects are structured this way.

Why AEM Projects Are Multi-Module

Unlike a typical web app where everything might live in one deployable unit, AEM separates code, content, and configuration into distinct Maven modules. This separation exists because these three things have very different lifecycles:

• Code changes with every feature or bug fix

• Content (sample pages, component defaults) is set up once and rarely redeployed

• Configuration (OSGi settings) often differs between environments (dev, stage, prod)

Keeping them separate means you can deploy code changes without accidentally overwriting content, and manage environment-specific configuration independently.

The Core Modules

core

This is where your Java code lives — Sling Models, Servlets, OSGi services, schedulers, and any custom business logic. If you're writing Java for AEM, this is almost always where it goes. It compiles into an OSGi bundle that gets deployed into AEM's runtime.

ui.apps

This holds everything that goes under /apps in the JCR repository:

• Component definitions (dialogs, HTL scripts, .content.xml files)

• Client libraries (CSS/JS, bundled as clientlibs)

• Templates and template policies

• Any other application-level structure

Recall from the previous post in this series: /apps is where you place your customizations, which Sling looks up before falling back to Adobe's defaults under /libs. This module is effectively "your app's definition" in the repository.

ui.content

This contains sample or default content — example pages, folder structures under /content, and sometimes reference content used for demos or initial setup. In many real projects, this module is either minimal or excluded from production deployments entirely, since live content is authored directly in the Author environment rather than deployed via code.

ui.config

This holds OSGi configuration — settings for things like PDF processing, workflow launchers, or any configurable service, often split by run mode (author vs. publish, dev vs. prod) so the same codebase behaves correctly across environments.

ui.frontend (in newer archetype versions)

Newer AEM projects often include a dedicated frontend module using modern tooling (webpack, npm) to build client-side assets, which then get packaged into ui.apps clientlibs during the build. This lets front-end developers work with familiar JS/CSS tooling rather than hand-writing clientlib folder structures.

it.tests (optional)

Some projects include an integration test module here, used for automated tests that run against a deployed AEM instance as part of CI/CD pipelines.

all

This is a "wrapper" package that bundles core, ui.apps, ui.content, and ui.config together into a single deployable content package. When you ran mvn clean install -PautoInstallSinglePackage in the previous post, this is typically the package that actually got installed onto your local instance.

A Simplified Visual

my-project/
├── core/            → Java code (Sling Models, Servlets, OSGi services)
├── ui.apps/         → /apps content: components, clientlibs, templates
├── ui.content/      → /content sample or reference content
├── ui.config/       → OSGi configurations per run mode
├── ui.frontend/     → Modern frontend build tooling (if present)
├── it.tests/        → Integration tests (optional)
└── all/             → Combined deployable package

Why This Structure Pays Off Long-Term

This separation might feel like overhead on a small project, but it becomes essential as a project grows:

• Multiple developers can work on core (Java logic) and ui.apps (components/front-end) simultaneously with minimal conflict

• Environment-specific behavior lives cleanly in ui.config, instead of scattered if (environment == "prod") checks in code

• CI/CD pipelines can build and deploy the all package as a single unit, while still keeping the underlying modules independently testable

Series Wrap-Up

That completes the AEM Foundations series. At this point you should understand:

• What AEM actually is, and how Sites, Assets, and Forms differ

• The Author/Publish/Dispatcher architecture and how requests flow through it

• How to set up a local AEM SDK environment

• How Sling resolves resources and processes requests

• How a real AEM project is organized on disk

From here, the AEM Core Development series picks up with hands-on component building — starting with your first HTL component and Sling Model.

AEM is built on top of Apache Sling, a web framework that takes a fundamentally different approach to handling requests than typical Java web frameworks. If you've worked with Spring MVC or a similar framework, Sling's model will initially feel unusual — there's no central routing table mapping URLs to controllers. Instead, everything revolves around resources.

Everything Is a Resource

In Sling, a "resource" is any node in the JCR repository — a page, a component instance, an asset, a piece of content. Every resource has a path and a resource type, and this pairing is the foundation of how Sling decides what to render.

For example, a page might live at:

/content/mysite/en/home

And a component instance on that page might be:

/content/mysite/en/home/jcr:content/root/container/text

That text component's sling:resourceType property might point to something like mysite/components/text, which tells Sling exactly which script or Java class should render it.

Resource Resolution: How a URL Becomes Content

When a request comes in, Sling doesn't look up a controller — it resolves the resource at that URL path first, then figures out how to render it. The core steps are:

1. Strip the request URL down to a repository path (handling extensions and selectors along the way)

2. Resolve the resource at that path in the JCR

3. Determine the resource's sling:resourceType

4. Locate a matching script or Servlet/Sling Model for that resource type, searching in the /apps overlay area first, then falling back to /libs

5. Render using that script

This /apps overlay-first, /libs fallback pattern is core to how AEM customization works — Adobe ships default implementations under /libs, and you customize behavior by placing your own resource type definitions under /apps without ever touching Adobe's shipped code.

Selectors and Extensions

Sling URLs can carry extra information beyond just the path, using selectors and extensions. A URL like:

/content/mysite/en/home.json

requests the JSON rendering of that resource, while:

/content/mysite/en/home.print.html

uses the print selector to request an alternate HTML rendering — useful for rendering the same content differently depending on context (a print-friendly layout, a mobile-specific variant, an API-style JSON output) without duplicating content.

The Sling Request Lifecycle, Step by Step

Putting it together, here's roughly what happens when a browser requests an AEM page:

1. The request hits the Dispatcher (if it's a live/Publish request) — see the Architecture post in this series

2. If not cached, it reaches the Sling engine inside AEM

3. Sling's Resource Resolver maps the URL to a JCR resource path

4. Sling determines the resource's type, selectors, and extension

5. It locates the appropriate rendering script (HTL/JSP) or Servlet

6. If the component uses a Sling Model, Sling instantiates it and injects data from the resource (we'll cover this in detail in the next series)

7. The script renders using that data, producing the final HTML/JSON/etc. response

8. The response is sent back — and cached by Dispatcher if applicable

Why This Model Matters

Once resource resolution clicks, a lot of AEM customization patterns make immediate sense:

• Overlaying Adobe's default components just means creating a matching path under /apps — no core code modification needed

• Multi-site, multi-language setups work because the same resource type can be reused across different content paths

• Debugging "why isn't my component rendering the way I expect" almost always comes down to checking the resource's actual sling:resourceType and where the resolver is finding (or failing to find) a matching script

What's Next

With resource resolution and the request lifecycle covered, the final post in this series looks at how a real AEM project is organized on disk — the core, ui.apps, ui.content, and other modules you saw generated by the archetype in the previous post.

Next in this series: [AEM Project Structure Explained]

Before you can build components, write Sling Models, or test anything discussed in this series, you need a working local AEM environment. This post walks through getting AEM as a Cloud Service SDK running on your machine.

Prerequisites

Make sure you have these installed before starting:

• Java Development Kit (JDK) — AEM as a Cloud Service SDK currently requires a specific supported JDK version (check Adobe's release notes for the exact version, as this changes between SDK releases)

• Apache Maven — for building and deploying your project code

• An IDE — IntelliJ IDEA or Eclipse (with AEM-specific plugins) are both common choices

• Adobe I/O access — you'll need an Adobe account with access to the Software Distribution portal to download the SDK

Step 1: Download the AEM SDK

1. Log in to the Adobe Software Distribution portal

2. Locate AEM as a Cloud Service SDK

3. Download the latest QuickStart JAR

Adobe ships new SDK versions frequently, so it's worth checking for the latest release rather than reusing an old download, especially if you're following along with current documentation.

Step 2: Run the Author Instance

Create a dedicated folder for your local setup, place the SDK jar inside it, then run:

java -jar aem-sdk-quickstart-*.jar

By default, this starts an Author instance on port 4502. The first run will take a few minutes as AEM unpacks and initializes its repository. Once it's up, you can log in at:

http://localhost:4502

Default credentials are admin / admin — change this immediately in any environment beyond your personal sandbox.

Step 3: Run the Publish Instance

To run a Publish instance alongside Author, start the jar with the publish run mode and a different port:

java -jar aem-sdk-quickstart-*.jar -r publish -p 4503

This lets you test the full Author → Publish flow locally, including replication, without needing a second machine.

Step 4: Set Up Your Project Structure

Rather than building a project from scratch, Adobe provides an archetype — a Maven template that scaffolds a standard AEM project structure for you:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \
  -D archetypeGroupId=com.adobe.aem \
  -D archetypeArtifactId=aem-project-archetype \
  -D archetypeVersion=<latest-version> \
  -D appTitle="My AEM Project" \
  -D appId="myproject" \
  -D groupId="com.mycompany.myproject"

This generates a multi-module Maven project (core, ui.apps, ui.content, ui.config, and more) that follows Adobe's recommended conventions — we'll break this structure down in detail in the next post.

Step 5: Build and Deploy Your Project

From your generated project's root directory, deploy everything to your local Author instance with:

mvn clean install -PautoInstallSinglePackage

If this completes without errors, your custom project code (even if it's just the archetype's sample content at this point) is now live on your local AEM instance.

Common First-Time Issues

A few things that trip up almost everyone on their first setup:

• Port conflicts — if 4502 or 4503 are already in use, specify a different port with -p <port> when starting the jar

• Insufficient memory — AEM is resource-hungry; make sure your machine has enough RAM allocated, and consider increasing JVM heap size if you see out-of-memory errors during startup

• JDK version mismatches — using an unsupported JDK version is one of the most common causes of startup failures; always check the SDK release notes for the required version

• Maven build failures — usually caused by an outdated archetype version or a misconfigured settings.xml for Maven repositories

What's Next

With a working local environment, you're ready to understand what's actually happening under the hood when AEM processes a request. The next post covers Apache Sling — the framework AEM is built on — and how resource resolution and the request lifecycle work.

Next in this series: [Understanding Sling: Resource Resolution & Request Lifecycle]

If there's one concept every AEM developer needs to internalize before writing code, it's the three-tier architecture: Author, Publish, and Dispatcher. Misunderstanding this leads to some of the most common (and confusing) bugs new AEM developers hit — content that "works on author but not on publish," caching issues, or components that behave inconsistently.

The Author Instance

The Author instance is where content authors and developers work. Think of it as the "backstage" environment:

• Authors log in, create pages, drag components onto templates, and configure content

• Developers deploy code here first to test

• It has the full authoring UI: the page editor, component dialogs, the DAM console, workflow tools

• It is never exposed directly to end users — it should sit behind your organization's firewall or VPN

Because Author holds the editing tools and unpublished drafts, it's also where content review and approval workflows typically run before anything goes live.

The Publish Instance

The Publish instance is what actually serves content to real visitors. Key differences from Author:

• It's a read-optimized copy of content, replicated from Author

• It has no authoring UI — it just renders pages

• In production, you'll usually run multiple Publish instances behind a load balancer for scalability and redundancy

• Content reaches Publish through a process called replication — when an author clicks "Publish" on a page, that content is pushed from Author to one or more Publish instances

This separation exists for a good reason: it keeps your live site fast and stable, since Publish doesn't carry the overhead of the authoring tools, and it means authors can safely draft and preview content without it being visible to the public.

The Dispatcher

The Dispatcher is often the most misunderstood piece for newcomers. It's not a full AEM instance — it's a caching and load-balancing module (technically an Apache HTTP Server module) that sits in front of Publish.

Its main jobs:

• Caching rendered HTML pages so Publish doesn't have to regenerate them on every request

• Security filtering — blocking requests to sensitive paths, restricting what URL patterns are servable

• Load balancing across multiple Publish instances

When someone visits your live AEM site, their request usually hits the Dispatcher first. If a cached version of that page exists and is still valid, Dispatcher serves it directly — Publish never even sees the request. If there's no valid cache, Dispatcher forwards the request to Publish, caches the response, and serves it.

This is why cache invalidation is such a recurring topic in AEM — if Dispatcher is serving a stale cached page after a content update, visitors won't see the change until the cache is cleared or refreshed (we'll cover this in depth in the Architecture & Operations series).

Putting It Together: A Request's Journey

Here's the typical flow when a page is published and then visited:

1. An author edits a page on Author and clicks Publish

2. Replication pushes that content to the Publish instance(s)

3. A visitor requests the page URL

4. The request hits Dispatcher first

5. Dispatcher checks its cache — serves the cached file if valid, or forwards to Publish if not

6. Publish renders the page (using your Java/HTL components) and returns it

7. Dispatcher caches the response for future requests and serves it to the visitor

Why This Matters Day-to-Day

Once this model clicks, a lot of AEM "mysteries" stop being mysterious:

• A page looking wrong on the live site but fine in Author almost always points to a replication or caching issue, not a code bug

• Performance problems on a live site are often a Dispatcher caching configuration issue, not a Java/HTL problem

• Security reviews frequently focus on Dispatcher rules, since it's your first line of defense against unwanted requests reaching Publish

What's Next

Now that you know how requests flow through AEM's architecture, the next post sets up your actual local development environment using the AEM SDK, so you can start building and testing components on your own machine.

Next in this series: [Setting Up a Local AEM SDK Dev Environment]

If you're new to Adobe Experience Manager (AEM), the first hurdle isn't the code — it's understanding what AEM actually is. The name gets used loosely to mean several different products bundled under one platform, and that ambiguity trips up a lot of newcomers. Let's clear it up.

AEM Is a Suite, Not a Single Product

Adobe Experience Manager is part of the Adobe Experience Cloud, and it's really an umbrella term for three major capabilities:

• AEM Sites — a content management system (CMS) for building, managing, and personalizing websites

• AEM Assets — a digital asset management (DAM) system for storing, organizing, and delivering media at scale

• AEM Forms — a tool for building and managing digital forms and documents, often used in regulated industries (insurance, banking, healthcare)

You can license and use these independently, or together, depending on what your organization needs. Most AEM developers start with Sites, since it's the most commonly implemented piece, but larger enterprises often run Sites and Assets together — a marketing team publishing pages while a separate creative team manages a shared media library feeding those pages.

AEM Sites: The CMS Layer

AEM Sites lets content authors build and edit web pages using a component-based system, without needing to touch code. As a developer, your job is to build the components (things like banners, carousels, text blocks, forms) that authors can drag onto a page and configure through dialogs.

Key things that make AEM Sites distinct from a typical CMS like WordPress:

• It's built on Apache Sling and the Java Content Repository (JCR), not a relational database

• Content is structured as a tree of nodes, which gives it enormous flexibility for multi-site, multi-language setups

• It supports component-driven authoring — every visible piece of a page is a reusable, configurable component

• Publishing is separated from authoring through distinct Author and Publish environments (more on this in the next post)

AEM Assets: The DAM Layer

AEM Assets is where images, videos, PDFs, and other media live. It's far more than a file storage system — it includes:

• Automated rendition generation (resizing, format conversion, cropping)

• Metadata management and tagging, increasingly automated with AI-based Smart Tags

• Workflow automation for asset approval, review, and processing pipelines

• Integration points so Sites components can pull assets directly from the DAM rather than duplicating files

If you're coming from a pure web development background, Assets can feel like a different discipline entirely — it's as much about digital operations and metadata governance as it is about code.

AEM Forms: The Overlooked Third Pillar

AEM Forms doesn't get as much attention in tutorials, but it's a serious product used heavily in industries with complex document workflows. It handles:

• Adaptive forms that render responsively across devices

• Document generation (e.g., auto-filled PDF contracts)

• Digital signature integrations

• Complex multi-step form logic for things like insurance claims or loan applications

If your career path is heading toward enterprise or regulated-industry AEM work, it's worth knowing Forms exists even if your first project doesn't touch it.

Why This Matters for Your Learning Path

Understanding this split early saves you from a common beginner mistake: assuming every AEM tutorial applies to your situation. A Sling Model tutorial for a Sites component won't help you configure an Assets workflow, and an Adaptive Forms rule editor has almost nothing in common with either.

For this blog, we'll mostly focus on AEM Sites and AEM Assets, since that combination covers the vast majority of real-world AEM development work.

What's Next

In the next post, we'll break down how AEM Sites actually runs under the hood — the Author instance, Publish instance, and Dispatcher — and why understanding this separation is critical before you write a single line of component code.

Next in this series: [AEM Architecture Explained: Author, Publish, and Dispatcher]

This guide walks through setting up the AEM Dispatcher module with Apache HTTP Server 2.2 on your local machine.

Note: Apache 2.2 reached end-of-life a while back, and most current AEM Dispatcher releases (5.x) are built and tested against Apache 2.4. If you have a choice, prefer Apache 2.4 for new setups. This guide is for cases where you specifically need to replicate an existing 2.2-based environment (e.g., matching a legacy production stack).

Prerequisites

Before you start, make sure you have:

• A running local AEM instance (author and/or publish) — typically on port 4502 (author) and 4503 (publish)

• Apache HTTP Server 2.2 installed

• The AEM Dispatcher module package for Apache 2.2 (downloaded from Adobe Software Distribution — you'll need a valid Adobe account with AEM entitlements)

• Basic familiarity with editing httpd.conf

Step 1: Verify Your Apache Installation

Confirm Apache 2.2 is installed and check whether it's 32-bit or 64-bit, since the Dispatcher module must match:

httpd -v
httpd -V | grep -i "architecture"

You'll need this info to pick the correct Dispatcher binary in the next step.

Step 2: Download and Place the Dispatcher Module

From the Dispatcher package you downloaded, locate the module file matching your OS and Apache version:

• Windows: dispatcher-apache2.2-x86_64-<version>.so (or 32-bit equivalent ex: disp_apache2.2.dll)

• Linux: dispatcher-apache2.2-x86_64-<version>.so

• macOS: dispatcher-apache2.2-x86_64-<version>.so

Copy this file into your Apache modules directory and rename it for clarity:

cp dispatcher-apache2.2-x86_64-<version>.so /path/to/apache2.2/modules/mod_dispatcher.so

Step 3: Load the Module in httpd.conf

Open your Apache configuration file (conf/httpd.conf) and add the following line, ideally near the other LoadModule directives:

LoadModule dispatcher_module modules/mod_dispatcher.so

Step 4: Create the Dispatcher Configuration Directory

Create a folder to hold your Dispatcher configuration files, e.g.:

mkdir /path/to/apache2.2/conf/dispatcher

Inside this folder, you'll typically create:

• dispatcher.any — main dispatcher config

• available_farms/ — folder holding one .any file per "farm" (site)

• cache/ — local disk cache directory used by Dispatcher

Step 5: Configure the Dispatcher Module in httpd.conf

Add the following block to httpd.conf to point Apache at your Dispatcher config and enable the handler:

<IfModule disp_apache2.c>
    DispatcherConfig conf/dispatcher/dispatcher.any
    DispatcherLog logs/dispatcher.log
    DispatcherLogLevel 3
    DispatcherNoServerHeader Off
    DispatcherDeclineRoot Off
    DispatcherUseProcessedURL Off
    DispatcherPassError 0
</IfModule>

<LocationMatch "^/(.*)">
    SetHandler dispatcher-handler
</LocationMatch>

Step 6: Create the Main dispatcher.any File

Inside conf/dispatcher/dispatcher.any, reference your farm file(s):

/farms
{
  $include "available_farms/*.any"
}

Step 7: Create a Farm Configuration

Create available_farms/localhost.any with a basic farm definition pointing to your local AEM publish instance:

/localhost
{
  /clientheaders
  {
    "*"
  }

  /virtualhosts
  {
    "localhost"
  }

  /renders
  {
    /rend01
    {
      /hostname "localhost"
      /port "4503"
    }
  }

  /filter
  {
    /0001 { /type "allow" /glob "*" }
  }

  /cache
  {
    /docroot "/path/to/apache2.2/htdocs"
    /rules
    {
      /0000 { /glob "*" /type "allow" }
    }
    /statfileslevel "3"
    /allowAuthorized "0"
  }

  /statfile "/tmp/dispatcher-localhost.stat"
}

The /filter section above is intentionally permissive ("allow" "*") for local testing only. Never use an open filter like this in a staging or production environment — always define explicit allow/deny rules based on Adobe's recommended Dispatcher security checklist.

Step 8: Set Up the Document Root

Make sure the docroot path in your farm config exists and matches Apache's DocumentRoot directive in httpd.conf:

DocumentRoot "/path/to/apache2.2/htdocs"
<Directory "/path/to/apache2.2/htdocs">
    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

Step 9: Set Apache to Listen on the Right Port

By default, Apache listens on port 80. For local testing, this is usually fine, but if port 80 is taken, change it:

Listen 8080

Step 10: Restart Apache and Test

Restart Apache:

# Linux/macOS
sudo apachectl restart

# Windows (from Apache bin directory)
httpd.exe -k restart

Then hit your site through Apache (not directly through AEM's port):

http://localhost:8080/

If everything's wired correctly, you should see your AEM publish instance's content served through Apache/Dispatcher.

Step 11: Verify Caching Is Working

Check the docroot folder you configured — after a successful request, Dispatcher should write a static cached copy of the page (e.g., .html file) into that directory. You can also tail the Dispatcher log to confirm requests are being processed:

tail -f /path/to/apache2.2/logs/dispatcher.log

Common Issues & Fixes

• Apache fails to start after adding the module — Usually an architecture mismatch (32-bit module on a 64-bit Apache, or vice versa). Re-check httpd -V.

• Blank page / 404 through Apache — Double-check the /renders hostname and port match your actual AEM publish instance, and that AEM is running.

• Nothing gets cached — Verify the docroot path is writable by the user running Apache, and that your /cache/rules aren't blocking the request path.

• Changes to dispatcher.any not taking effect — Dispatcher config is only re-read on Apache restart, not on every request. Always restart Apache after editing .any files.

Wrapping Up

This setup mirrors (at a smaller scale) how AEM Dispatcher works in real deployments — caching pages, applying security filters, and routing requests to the right render instance. Getting comfortable with this locally makes it much easier to debug dispatcher-related issues later in staging or production, where you often don't have direct server access.

In a future post, we'll look at moving this same setup to Apache 2.4 and comparing the syntax differences in httpd.conf, along with a deeper dive into Dispatcher security rules (the /filter section) that you should never skip in production.