# adobe/aem-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/adobe/aem-boilerplate
- Repository: https://github.com/adobe/aem-boilerplate

## Overview

##### Project Summary and Core Purpose
- This project is an AEM (Adobe Experience Manager) boilerplate designed to help developers rapidly create and integrate front-end components (or “blocks”) into an AEM environment. The project is structured to support local development with AEM proxying (using the AEM CLI and Code Sync GitHub App) and eventual deployment to both Preview and Live AEM environments.

##### Analyzing the File Structure
- The “blocks” directory encapsulates modular UI parts with both CSS and JavaScript, suggesting a component-based architecture.
- Configuration files like “.eslintrc.js”, “.stylelintrc.json”, and “fstab.yaml” denote quality assurance, linting practices, and AEM mount configuration that influence how the code is integrated with the AEM backend.
- The “scripts” folder includes integrations (e.g., aem.js) and utility scripts that tie the local development environment to AEM.

##### Reading the README for Architectural Insights
- The README confirms the AEM integration, outlining local development steps (setting up a mountpoint via fstab.yaml, using AEM CLI to start a proxy at localhost:3000, and integrating with the AEM Code Sync GitHub App).
- It directs developers to deeper documentation around project anatomy, markup organization, sections, blocks, and auto blocking — reinforcing the fact that the project’s core design relies on modular blocks that are eventually consumed by an AEM instance.

##### Main Components
- Frontend Components (Blocks):
- UI element – cards, columns, footer, header, hero, fragment – as individual modules.
- Grouped under “Blocks” to reflect their component-based structure.
- Assets/Static Files:
- Integration & Utility Scripts:
- “Scripts” directory (aem.js, delayed.js, scripts.js) to be shown as utility modules managing client-side behaviors and AEM synchronization.
- Configuration & Environment:
- fstab.yaml represents the integration configuration mapping your local project to the AEM instance.
- Configuration files related to linting and formatting which, while not directly affecting runtime, enforce code quality and consistency.
- External AEM Environment:
- Components representing the “Author”, “Preview”, and “Live” AEM environments as external systems.
- AEM Proxy (started using “aem up”) that synchronizes changes between the local development environment and the AEM instance.

##### Relationships and Data Flow
- Front-end blocks (UI components) and styles/scripts are deployed/synchronized to the AEM environment via the mount configuration (fstab.yaml) and the AEM Code Sync process.
- The AEM CLI acts as the communication bridge between the local development tooling and the AEM server.
- User/browser requests hit the deployed AEM environment, which dynamically fetches and renders the front-end resources.
- That while development is done locally, real-time synchronization keeps the AEM server updated.

##### Important Architectural Patterns & Design Principles
- Modular & Component-Based Design: The separation into blocks supports reusability and independent updates.
- Configuration-Driven Integration: The use of fstab.yaml and AEM Code Sync allows for mapping local changes into AEM’s repository structure.
- Separation of Concerns: Clear demarcation between content (HTML/blocks), style (CSS), behavior (JavaScript), and configuration (YAML, JSON).
- DevOps-Friendly: Integration with GitHub workflows and CI/CD configurations (e.g., .github folder) prepares the project for continuous integration and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Development Environment
    subgraph "Local Development Environment"
        %% Frontend Components (Blocks)
        subgraph "Frontend Components (Blocks)"
            Blocks["Blocks (All UI Components)"]:::frontend
            HeaderBlock["Header Block"]:::frontend
            HeroBlock["Hero Block"]:::frontend
            FooterBlock["Footer Block"]:::frontend
            CardsBlock["Cards Block"]:::frontend
            ColumnsBlock["Columns Block"]:::frontend
            FragmentBlock["Fragment Block"]:::frontend
            Blocks --> HeaderBlock
            Blocks --> HeroBlock
            Blocks --> FooterBlock
            Blocks --> CardsBlock
            Blocks --> ColumnsBlock
            Blocks --> FragmentBlock
        end

        %% Assets/Static Files
        subgraph "Assets/Static Files"
            Styles["Styles"]:::asset
            Fonts["Fonts"]:::asset
            Icons["Icons"]:::asset
        end

        %% Integration & Utility Scripts
        subgraph "Integration & Utility Scripts"
            Scripts["Scripts"]:::script
        end

        %% Configurations & Code Quality
        subgraph "Configurations & Code Quality"
            Fstab["fstab.yaml"]:::config
            ESL[".eslintrc.js"]:::config
            Stylelint[".stylelintrc.json"]:::config
        end
    end

    %% AEM Environment
    subgraph "AEM Environment"
        AEMProxy["AEM Proxy (CLI)"]:::external
        AEMAuthor["AEM Author"]:::external
        AEMPreview["AEM Preview"]:::external
        AEMLive["AEM Live (Production)"]:::external
    end

    %% Connections: Local Development to AEM Proxy via Code Sync & Mount Configuration
    Blocks -->|"CodeSync"| AEMProxy
    Styles -->|"CodeSync"| AEMProxy
    Scripts -->|"CodeSync"| AEMProxy
    Fstab -->|"MountConfig"| AEMProxy

    %% AEM Proxy distributes to other AEM environments
    AEMProxy -->|"Sync"| AEMAuthor
    AEMProxy -->|"Sync"| AEMPreview
    AEMProxy -->|"Sync"| AEMLive

    %% Additional connection from Assets to Scripts can denote integrated static resources
    Fonts --- Icons

    %% Click Events for Components
    click Blocks "https://github.com/adobe/aem-boilerplate/tree/main/blocks/"
    click HeaderBlock "https://github.com/adobe/aem-boilerplate/blob/main/blocks/header/header.js"
    click HeroBlock "https://github.com/adobe/aem-boilerplate/blob/main/blocks/hero/hero.js"
    click FooterBlock "https://github.com/adobe/aem-boilerplate/blob/main/blocks/footer/footer.js"
    click CardsBlock "https://github.com/adobe/aem-boilerplate/blob/main/blocks/cards/cards.js"
    click ColumnsBlock "https://github.com/adobe/aem-boilerplate/blob/main/blocks/columns/columns.js"
    click FragmentBlock "https://github.com/adobe/aem-boilerplate/blob/main/blocks/fragment/fragment.js"
    click Styles "https://github.com/adobe/aem-boilerplate/tree/main/styles/"
    click Fonts "https://github.com/adobe/aem-boilerplate/tree/main/fonts/"
    click Icons "https://github.com/adobe/aem-boilerplate/tree/main/icons/"
    click Scripts "https://github.com/adobe/aem-boilerplate/tree/main/scripts/"
    click Fstab "https://github.com/adobe/aem-boilerplate/blob/main/fstab.yaml"
    click ESL "https://github.com/adobe/aem-boilerplate/blob/main/.eslintrc.js"
    click Stylelint "https://github.com/adobe/aem-boilerplate/blob/main/.stylelintrc.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2;
    classDef asset fill:#d4edda,stroke:#333,stroke-width:2;
    classDef script fill:#fff3cd,stroke:#333,stroke-width:2;
    classDef config fill:#f8d7da,stroke:#333,stroke-width:2;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2;
```
