# adobe-consulting-services/acs-aem-samples architecture

> Architecture diagram of the GitHub repository adobe-consulting-services/acs-aem-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adobe-consulting-services/acs-aem-samples
- Repository: https://github.com/adobe-consulting-services/acs-aem-samples

## Overview

##### Project type and purpose
- This is an Adobe Experience Manager (AEM) “reference‐implementation” multi-module Maven project that ships:
- An OSGi bundle of Java samples (core)
- A content package with repository structure (repository-structure)
- A content package of UI components, clientlibs and OSGi configs (ui.apps)
- An “all” aggregator package that pulls them together
- Its sole purpose is to demonstrate common AEM building blocks (Sling servlets, OSGi services, filters, workflows, resource providers, etc.) for educational/reference use.

##### File structure
- Top-level parent POM manages four submodules: all, core, repository-structure, ui.apps
- core/src/main/java/... contains dozens of sample OSGi components (services, servlets, filters, event emitters, jobs, authentication handlers, adapter factories, Sling Models, etc.)
- ui.apps/src/main/content/jcr_root/apps/acs-aem-samples houses:
- HTL components (structure, content, utilities)
- Client libraries (authoring, base, common, vendor)
- Touch-UI datasource JSPs
- OSGi configuration under /apps/.../config and config.author
- repository-structure defines initial JCR paths/content for certain samples
- all assembles all content under one package for easy deployment

##### README
- Confirms this is a collection of sample implementations for common AEM building blocks
- Not meant for production—only reference

##### Main components and their relationships
A. Build & Deployment (Maven multi-module)
- Parent POM orchestrates compilation of:
– core → OSGi bundle (jar)
– ui.apps → content package (zip)
– repository-structure → content package (zip)
– all → aggregator package containing the above
- CI/CD (e.g., Jenkins or Cloud Manager) triggers `mvn clean install -PautoInstallPackage` against an AEM instance
B. AEM Instance (Author/Publish)
1. OSGi Container (Apache Felix)
– Deploy core bundle → SampleExecutor, SampleServices, SampleServlets, Filters, Event Emitters, Job Consumers, Workflow Processors, etc.
– OSGi Config factory → OSGI configs under ui.apps
2. JCR Repository (Apache Jackrabbit Oak)
– /apps/acs-aem-samples → HTL component definitions, clientlibs, touch-UI definitions
– /etc/workflow/models or /var/workflow within repository-structure
3. Sling Request Processing
– HTTP request → Sling Filters (SampleSlingRequestFilter, SampleServletFilter) → Sling Resource resolution → Sling Servlet
– Servlets return HTML/JSON (SampleAllMethodsServlet, SampleOptingServlet) or workflow/process results
4. Auxiliary Frameworks
– Sling Models (SampleSlingModel, exporters) for MVC
– QueryBuilder sample predicates & JSON hit writers
– OAuth scope/sample authentication handler
– Resource Providers & Decorators
– OSGi Job Handling (Sling Job)
– OSGi Event service

##### Architectural patterns & design principles
- Modular OSGi bundles, strict separation of concerns
- MVC via Sling Models + HTL components
- Content Repository as configuration + UI store
- Use of OSGi Declarative Services for dynamic service wiring
- Sling Filters/Servlets as request pipeline
- CQ/Granite workflow process implementations to illustrate JCR-backed workflow steps

- Related components under “OSGi,” “JCR,” and “Build” layers

By breaking this ACS AEM Samples project into:
1) Maven modules → build artifacts
2) AEM runtime layers (OSGi, Sling, JCR)
3) Sample‐specific subcomponents (filters, servlets, services, workflows, clientlibs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build (Maven)"
        parent["Parent POM"]:::build
        core["Core OSGi Bundle"]:::build
        uiapps["UI.apps Package"]:::build
        repo["Repository-structure Package"]:::build
        all["All Aggregator Package"]:::build
    end

    parent --> core
    parent --> uiapps
    parent --> repo
    parent --> all

    core -->|"OSGi bundle"| services
    uiapps -->|"Content package"| components
    uiapps -->|"Content package"| clientlibs
    uiapps -->|"Content package"| datasources
    uiapps -->|"Content package"| configs
    repo -->|"Content package"| repoContent
    all -->|"Aggregator package"| services
    all -->|"Aggregator package"| components

    subgraph "AEM Instance"
        subgraph "OSGi Container"
            services["Services & DS Components"]:::osgi
            filters["Filters & Servlets"]:::osgi
            events["Event Emitters & Job Consumers"]:::osgi
            workflows["Workflow Processors"]:::osgi
            models["Sling Models & Exporters"]:::osgi
            adapters["Adapter Factory"]:::osgi
            auth["Authentication Handler & OAuth"]:::osgi
            resources["Resource Providers & Decorators"]:::osgi
            queries["QueryBuilder Predicates & JSON Writers"]:::osgi
        end
        subgraph "JCR Repository"
            components["HTL & Utility Components"]:::jcr
            clientlibs["Client Libraries"]:::jcr
            datasources["Touch-UI Datasources"]:::jcr
            configs["OSGi Configurations"]:::jcr
            repoContent["Repository-structure Content"]:::jcr
        end
    end

    %% Click Events
    click parent "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/pom.xml"
    click all "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/all/pom.xml"
    click all "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/all/src/main/content/META-INF/vault/definition/.content.xml"
    click all "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/all/src/main/content/META-INF/vault/filter.xml"
    click core "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/core/pom.xml"
    click services "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/core/src/main/java/com/adobe/acs/samples/services"
    click filters "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/core/src/main/java/com/adobe/acs/samples/filters/impl"
    click events "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/core/src/main/java/com/adobe/acs/samples/events/impl/SampleOsgiEventEmitter.java"
    click workflows "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/core/src/main/java/com/adobe/acs/samples/workflow/impl"
    click models "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/core/src/main/java/com/adobe/acs/samples/models"
    click adapters "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/core/src/main/java/com/adobe/acs/samples/adapterfactories/impl/SampleAdapterFactory.java"
    click auth "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/core/src/main/java/com/adobe/acs/samples/authentication/impl/SampleLoginHookAuthenticationHandler.java"
    click resources "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/core/src/main/java/com/adobe/acs/samples/resourceproviders/impl/SampleResourceProvider.java"
    click queries "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/core/src/main/java/com/adobe/acs/samples/search/querybuilder/impl"
    click repo "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/repository-structure/pom.xml"
    click repoContent "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/repository-structure/src/main/content/META-INF/vault/definition/.content.xml"
    click components "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/ui.apps/src/main/content/jcr_root/apps/acs-aem-samples/components/structure"
    click clientlibs "https://github.com/adobe-consulting-services/acs-aem-samples/tree/master/ui.apps/src/main/content/jcr_root/apps/acs-aem-samples/clientlibs"
    click datasources "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/ui.apps/src/main/content/jcr_root/apps/acs-aem-samples/touch-ui/datasources/sample-datasource/sample-datasource.jsp"
    click configs "https://github.com/adobe-consulting-services/acs-aem-samples/blob/master/ui.apps/src/main/content/jcr_root/apps/acs-aem-samples/config/org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.xml"

    classDef build fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef osgi fill:#d4edda,stroke:#333,stroke-width:1px
    classDef jcr fill:#fff3cd,stroke:#333,stroke-width:1px
```
