# hiro-dev-aem/wknd architecture

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

- Interactive diagram: https://gitdiagram.com/hiro-dev-aem/wknd
- Repository: https://github.com/hiro-dev-aem/wknd

## Overview

##### Project Type and Purpose
- This is a static site/web-app built on Adobe Helix (Edge Delivery Services).
- It uses a Git-based CMS approach: documents live in AEM/SharePoint/Google Drive, are pulled through a Helix pipeline, transformed with “blocks” and “plugins,” then published as static HTML/CSS/JS to hlx.live pages.
- Features: document-based authoring, A/B experimentation, real-user monitoring (RUM) & conversion tracking, Slack Bot integration, CI/CD via GitHub Actions.

##### High-Level File-Structure Analysis
- Root config & infra:
- fstab.yaml – defines content sources (AEM, SharePoint).
- head.html – HTML head template.
- .github/workflows/run-tests.yaml – CI workflow.
- “blocks/” – modular UI components (each with .js and .css).
- “plugins/” – Helix pipeline plugins (experimentation, rum-conversion).
- “scripts/” – client-side libraries (Franklin runtime, analytics, cookie consent).
- “styles/” – global & cookie-consent CSS.
- “test/” – unit & Puppeteer tests.
- “tools/sidekick” – utilities for AEM Sidekick integration.

##### Key README Insights
- The pipeline is powered by the Helix CLI (`hlx up`) and GitHub Actions (tests, build, publish).
- Authoring is document-driven; content is fetched at build-time or on-demand.
- Experiments & RUM data feed into a Slack Bot via GitHub App (helix-bot).
- Puppeteer script generates synthetic traffic for conversion demos.

##### Main Components & Their Interactions
a. Content Sources
- AEM / SharePoint / Google Drive (configured in fstab.yaml).
b. Developer Workflow & CI/CD
- Local: Helix CLI (`hlx up`) → proxies content + runs pipeline → localhost:3000.
- CI: Git push → GitHub Actions → Run tests → Build & deploy to Preview / Live via Helix.
c. Helix Pipeline
- Input: raw HTML/Markdown from content sources.
- Processors:
- Block Runner – loads each block’s JS/CSS, renders component markup.
- Plugins – e.g., experimentation plugin injects experiment metadata; RUM plugin instruments pages.
- Output: static HTML, bundled CSS/JS assets.
d. Static Hosting & CDN
- hlx.live / hlx.page endpoints serve pre-rendered pages & assets at the edge.
e. Client Browser
- Fetches HTML + global scripts (lib-franklin.js, analytics, cookie consent).
- Block scripts hydrate interactive components.
- Sends telemetry to RUM endpoints.
- Interacts with Experimentation UI via Sidekick extension.
f. External Services
- Adobe Experience Cloud (Alloy.js) for analytics.
- Slack (helix-bot) for experiment & conversion reports.
- Puppeteer for test traffic generation.

##### Architectural Patterns & Principles
- Pipeline-based rendering: build-time SSR with pluggable transforms.
- Modular components (“blocks”) encapsulate UI + logic.
- Convention-over-configuration (fstab, head.html, block folder naming).
- GitOps: content and code in Git; deployments triggered by commits.
- Separation of concerns: data sources → pipeline → hosting → client runtime.

##### Capturing Detail
- Config files (fstab.yaml → drives the content layer; .github/workflows → CI trigger).
- Both build-time and run-time flows.
- How the Puppeteer script plugs into tests, funnels data into RUM, and surfaces in Slack.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    subgraph "Content Layer"
        direction TB
        FSTAB["fstab.yaml"]:::content
        AEM["AEM / SharePoint / Google Drive"]:::content
    end

    %% Build Layer
    subgraph "Build Layer"
        direction TB
        HelixCLI["Helix CLI (hlx up)"]:::build
        CI["GitHub Actions"]:::build
        Head["head.html"]:::build
        BlocksRunner["Blocks Runner"]:::build
        Experimentation["Experimentation Plugin"]:::build
        RUMPlugin["RUM & Conversion Plugin"]:::build
        Package["package.json"]:::build
        BlockTests["Block Tests"]:::build
        ScriptTests["Script Tests"]:::build
    end

    %% Hosting Layer
    subgraph "Hosting Layer"
        direction TB
        CDN["hlx.live / hlx.page"]:::hosting
    end

    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Client Browser"]:::client
        Franklin["Franklin Runtime"]:::client
        Alloy["Adobe Alloy.js"]:::client
        LibAnalytics["Custom Analytics"]:::client
        CookieScript["Cookie Consent JS"]:::client
        CookieStyles["Cookie Consent CSS"]:::client
        ScriptsJS["scripts.js"]:::client
        Delayed["delayed.js"]:::client
        StylesCSS["styles.css"]:::client
        LazyStyles["lazy-styles.css"]:::client
        Sidekick["AEM Sidekick Utilities"]:::client
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        Adobe["Adobe Experience Cloud"]:::integration
        Slack["Slack Bot (helix-bot)"]:::integration
        Puppeteer["Puppeteer Traffic Generator"]:::integration
    end

    %% Connections
    FSTAB -->|"defines content"| AEM
    AEM -->|"provides content"| HelixCLI
    FSTAB -->|"used by"| HelixCLI
    Head -->|"template for"| HelixCLI
    HelixCLI -->|"runs pipeline"| BlocksRunner
    HelixCLI --> BlocksRunner
    HelixCLI --> Experimentation
    HelixCLI --> RUMPlugin
    CI -->|"runs tests & build"| BlocksRunner
    CI --> Experimentation
    CI --> RUMPlugin
    CI --> Package
    BlockTests --> CI
    ScriptTests --> CI
    BlocksRunner --> Pipeline["Helix Pipeline"]:::build
    Experimentation --> Pipeline
    RUMPlugin --> Pipeline
    Pipeline -->|"outputs static assets"| CDN
    CI -->|"deploy to"| CDN
    Browser -->|"requests page"| CDN
    CDN -->|"serves HTML/CSS/JS"| Browser
    Browser -->|"loads"| Franklin
    Browser -->|"loads"| Alloy
    Browser -->|"loads"| LibAnalytics
    Browser -->|"loads"| CookieScript
    Browser -->|"loads"| CookieStyles
    Browser -->|"loads"| ScriptsJS
    Browser -->|"loads"| Delayed
    Browser -->|"loads"| StylesCSS
    Browser -->|"loads"| LazyStyles
    Browser -->|"uses"| Sidekick
    Browser -->|"sends telemetry"| Adobe
    Adobe -->|"data to"| Slack
    Puppeteer -->|"generates traffic"| CDN
    Puppeteer -->|"funnels data"| Slack

    %% Click Events
    click FSTAB "https://github.com/hiro-dev-aem/wknd/blob/main/fstab.yaml"
    click Head "https://github.com/hiro-dev-aem/wknd/blob/main/head.html"
    click CI "https://github.com/hiro-dev-aem/wknd/blob/main/.github/workflows/run-tests.yaml"
    click BlocksRunner "https://github.com/hiro-dev-aem/wknd/tree/main/blocks/"
    click Experimentation "https://github.com/hiro-dev-aem/wknd/blob/main/plugins/experimentation/src/index.js"
    click RUMPlugin "https://github.com/hiro-dev-aem/wknd/blob/main/plugins/rum-conversion/src/index.js"
    click Franklin "https://github.com/hiro-dev-aem/wknd/blob/main/scripts/lib-franklin.js"
    click Alloy "https://github.com/hiro-dev-aem/wknd/blob/main/scripts/analytics/alloy.js"
    click LibAnalytics "https://github.com/hiro-dev-aem/wknd/blob/main/scripts/analytics/lib-analytics.js"
    click CookieScript "https://github.com/hiro-dev-aem/wknd/blob/main/scripts/cookie-consent/lib-cookie-consent.js"
    click CookieStyles "https://github.com/hiro-dev-aem/wknd/tree/main/styles/cookie-consent/"
    click ScriptsJS "https://github.com/hiro-dev-aem/wknd/blob/main/scripts/scripts.js"
    click Delayed "https://github.com/hiro-dev-aem/wknd/blob/main/scripts/delayed.js"
    click StylesCSS "https://github.com/hiro-dev-aem/wknd/blob/main/styles/styles.css"
    click LazyStyles "https://github.com/hiro-dev-aem/wknd/blob/main/styles/lazy-styles.css"
    click Sidekick "https://github.com/hiro-dev-aem/wknd/tree/main/tools/sidekick/"
    click BlockTests "https://github.com/hiro-dev-aem/wknd/tree/main/test/blocks/"
    click ScriptTests "https://github.com/hiro-dev-aem/wknd/tree/main/test/scripts/"
    click Puppeteer "https://github.com/hiro-dev-aem/wknd/blob/main/test/puppeteer/generate-traffic.mjs"
    click Package "https://github.com/hiro-dev-aem/wknd/blob/main/package.json"

    %% Styles
    classDef content fill:#ccffcc,color:#000;
    classDef build fill:#cce5ff,color:#000;
    classDef client fill:#ffe0b3,color:#000;
    classDef hosting fill:#e0e0e0,color:#000;
    classDef integration fill:#e5ccff,color:#000;
```
