# anandkilli/aem-spa-react architecture

> Architecture diagram of the GitHub repository anandkilli/aem-spa-react, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anandkilli/aem-spa-react
- Repository: https://github.com/anandkilli/aem-spa-react

## Overview

##### Project type and purpose
- This is a full-stack, multi-module Maven project integrating an existing React SPA with Adobe Experience Manager (AEM) 6.4 as an SPA editor.
- Key indicators:
- “react-app” directory is a standard Node/React application
- “ui.apps” and “ui.content” contain AEM client libraries and JCR content definitions
- “core” is an OSGi bundle implementing Sling filters, servlets, models, schedulers
- Integration tests under “it.launcher” and “it.tests”

##### File structure
- Top-level modules (all under com.techmystyle.spa.react-demo):
- core – Java OSGi bundle: logging filter, resource listener, Sling model (HelloWorldModel), scheduled tasks, servlets
- it.launcher – launches an AEM instance for integration tests (uses Sling testing harness)
- it.tests – server-side integration tests against Sling model JSON endpoints
- react-app – Node/React SPA with webpack, builds App.js and clientlib.config.js for AEM SPA editor
- ui.apps – AEM clientlibs (CSS/JS under /apps/react-demo/clientlibs), component definitions, templates, Sling servlets for error handling
- ui.content – JCR content: /apps configurations under /conf/react-demo, editable templates and policies, sample content under /content/react-demo, DAM assets
- Root pom.xml orchestrates module builds and packaging (`mvn clean install -PautoInstallPackage,buildDev -Padobe-public`).

##### README for additional insights
- Project purpose: step-by-step integration of an existing React SPA into AEM SPA editor
- Build steps: npm install, then Maven build with AEM packaging
- Dependency on AEM 6.4, Node 8, Java 8, Maven 3.5.2

a. Main components
1. Developer Workstation
- Node toolchain: npm, webpack dev server
- Maven CLI
2. React SPA (react-app)
- Source: App.js + components
- Build: webpack → dist/App.js
3. AEM Author/Publish Instance
- Sling OSGi container
- core bundle (filters, models, servlets, schedulers)
- it.launcher for test harness
- CRX JCR repository
- ui.apps clientlibs and component definitions under /apps/react-demo
- ui.content templates, policies, sample content under /conf/react-demo and /content/react-demo
4. Browser / SPA Editor UI
5. Integration Tests (it.tests)

b. Relationships and interactions
- Developer runs `npm build` → generates client-side JS assets
- Maven packages assets and OSGi bundle → installs to AEM
- Browser requests page → AEM Sling resolves templates, includes clientlibs (/etc/clientlibs/react-demo)
- React SPA boots in the browser; client-side routing fetches JSON models via Sling Model Exporter servlet endpoints (e.g., /content/react-demo.model.json)
- OSGi bundle (core) exports RESTful JSON for Sling models (HelloWorldModel)
- Scheduled tasks and filters in core handle server-side events and logging
- Integration tests launch an in-JVM AEM server (it.launcher) and run server-side tests (it.tests) against Sling servlets and model endpoints

c. Architectural patterns and design principles
- Multi-module Maven for clear separation of concerns
- OSGi modularity: core business logic in bundles
- SPA editor pattern in AEM: React components mapped to AEM components and Sling models
- Client-side build pipeline (webpack) decoupled from server packaging (Maven)
- Test harness using Sling Testing Tools for automated integration tests

d. Relevant technologies, frameworks, libraries
- React, Babel, Webpack (react-app)
- Node.js, npm
- Maven multi-module
- AEM 6.4 (Sling, OSGi container, JCR)
- Sling Model Exporter
- Sling Testing Tools (it.launcher, it.tests)

##### Elements
- Rectangles for each component/module (e.g., React Build, core OSGi bundle, ui.apps, ui.content, Browser, Integration Test Harness)
- Green for frontend (react-app, browser)
- Blue for backend/AEM (core bundle, ui.apps, ui.content, Sling container)
- Gray for build/deploy pipeline (npm, Maven)
- Orange for tests (it.launcher, it.tests)

##### Detail
- Important endpoints (e.g., /apps/react-demo/clientlibs/clientlib-react-demo/js/App.js, /content/react-demo.model.json)
- How templates, policies (ui.content) configure the SPA editor and how clientlibs (ui.apps) serve the React assets
- OSGi bundle lifecycle (install, activate) and Sling Model Exporter interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        direction TB
        Node["Node.js & npm"]:::build
        Webpack["Webpack Dev Server"]:::build
        MavenCLI["Maven CLI"]:::build
    end

    %% Frontend Build
    subgraph "Frontend Build & Assets"
        direction TB
        ReactApp["React SPA (react-app)"]:::frontend
        ClientConfig["clientlib.config.js"]:::frontend
        WebpackBuild["dist/App.js"]:::frontend
    end

    %% AEM Server
    subgraph "AEM Author/Publish Instance" 
        direction TB
        subgraph "OSGi Container & Core"
            direction TB
            CoreBundle["core OSGi Bundle"]:::backend
            Filter["LoggingFilter"]:::backend
            Listener["SimpleResourceListener"]:::backend
            Model["HelloWorldModel"]:::backend
            Scheduler["SimpleScheduledTask"]:::backend
            Servlet["SimpleServlet"]:::backend
        end
        subgraph "CRX JCR Repository"
            direction TB
            UIApps["ui.apps"]:::backend
            UICL["clientlib-react-demo"]:::backend
            BaseCL["clientlib-base"]:::backend
            Components["helloworld Component"]:::backend
            ErrorHandler["404 Error Handler"]:::backend
            UIContent["ui.content"]:::backend
            Templates["Editable Templates"]:::backend
            Policies["Policies & Structure"]:::backend
            SampleContent["Sample Content"]:::backend
        end
    end

    %% Browser & SPA Editor
    Browser["Browser / SPA Editor UI"]:::frontend

    %% Integration Tests
    subgraph "Integration Test Harness"
        direction TB
        ITLauncher["it.launcher"]:::test
        TestBase["SlingServerSideTestsBase"]:::test
    end
    ITTests["it.tests"]:::test
    HelloTest["HelloWorldModelServerSideTest"]:::test

    %% Build & Deployment Flow
    Node -->|npm build| ReactApp
    ReactApp -->|reads| ClientConfig
    ReactApp -->|webpack build| WebpackBuild
    WebpackBuild -->|packaged by| MavenCLI

    %% Deployment to AEM
    MavenCLI -->|deploys| CoreBundle
    MavenCLI -->|deploys| UIApps
    MavenCLI -->|deploys| UIContent

    %% Runtime Interactions
    Browser -->|HTTP GET page| UIApps
    UIApps -->|serves clientlibs| WebpackBuild
    Browser -->|boots SPA| WebpackBuild
    Browser -->|fetch JSON /content/react-demo.model.json| Servlet
    Servlet -->|uses Sling Model Exporter| Model
    Servlet -->|registered in| CoreBundle

    %% OSGi internal
    CoreBundle -->|schedules| Scheduler
    CoreBundle -->|logs via| Filter
    CoreBundle -->|listens| Listener

    %% Integration Tests Flow
    ITLauncher -->|starts in-JVM AEM| CoreBundle
    ITTests -->|runs| HelloTest
    HelloTest -->|calls| Servlet
    HelloTest -->|validates| Model

    %% Click Events
    click ReactApp "https://github.com/anandkilli/aem-spa-react/tree/master/com.techmystyle.spa.react-demo/react-app"
    click ClientConfig "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/react-app/clientlib.config.js"
    click WebpackBuild "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/react-app/dist/App.js"
    click CoreBundle "https://github.com/anandkilli/aem-spa-react/tree/master/com.techmystyle.spa.react-demo/core"
    click Filter "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/core/src/main/java/com/techmystyle/spa/core/filters/LoggingFilter.java"
    click Listener "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/core/src/main/java/com/techmystyle/spa/core/listeners/SimpleResourceListener.java"
    click Model "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/core/src/main/java/com/techmystyle/spa/core/models/HelloWorldModel.java"
    click Scheduler "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/core/src/main/java/com/techmystyle/spa/core/schedulers/SimpleScheduledTask.java"
    click Servlet "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/core/src/main/java/com/techmystyle/spa/core/servlets/SimpleServlet.java"
    click UIApps "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/ui.apps"
    click UICL "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/ui.apps/src/main/content/jcr_root/apps/react-demo/clientlibs/clientlib-react-demo/js/App.js"
    click BaseCL "https://github.com/anandkilli/aem-spa-react/tree/master/com.techmystyle.spa.react-demo/ui.apps/src/main/content/jcr_root/apps/react-demo/clientlibs/clientlib-base"
    click Components "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/ui.apps/src/main/content/jcr_root/apps/react-demo/components/content/helloworld/.content.xml"
    click ErrorHandler "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/ui.apps/src/main/content/jcr_root/apps/sling/servlet/errorhandler/404.html"
    click UIContent "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/ui.content"
    click Templates "https://github.com/anandkilli/aem-spa-react/tree/master/com.techmystyle.spa.react-demo/ui.content/src/main/content/jcr_root/conf/react-demo/settings/wcm/templates"
    click Policies "https://github.com/anandkilli/aem-spa-react/tree/master/com.techmystyle.spa.react-demo/ui.content/src/main/content/jcr_root/conf/react-demo/settings/wcm/policies"
    click SampleContent "https://github.com/anandkilli/aem-spa-react/tree/master/com.techmystyle.spa.react-demo/ui.content/src/main/content/jcr_root/content/react-demo"
    click ITLauncher "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/it.launcher"
    click TestBase "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/it.launcher/src/test/java/com/techmystyle/spa/it/launcher/SlingServerSideTestsBase.java"
    click ITTests "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/it.tests"
    click HelloTest "https://github.com/anandkilli/aem-spa-react/blob/master/com.techmystyle.spa.react-demo/it.tests/src/main/java/com/techmystyle/spa/it/tests/HelloWorldModelServerSideTest.java"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef build fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef test fill:#ffe5cc,stroke:#333,stroke-width:1px
```
