Architecture Decisions
Executive Summary
This document records the key architecture decisions made for the RHEA project, including the rationale, tradeoffs, and current status of each decision. Decisions follow a lightweight ADR (Architecture Decision Record) format.
Decision Log
All 15 records are approved and current; none has been superseded, so there is no status column — a column reading Approved fifteen times carries no information. Where a record has been amended since it was written, that is noted against it.
| # | Decision | Notes |
|---|---|---|
| 1 | Repoless architecture for block sharing | — |
| 2 | AEM Edge Delivery Services as delivery platform | — |
| 3 | SCSS with committed compiled output | — |
| 4 | Style Dictionary for design token pipeline | — |
| 5 | Two sanitizers, used at different points | Reworded 2026-09 — the original text named DOMPurify as the only sanitizer, which was inaccurate |
| 6 | mitt for inter-component event bus | Amended — mitt is now vendored, not loaded from a CDN |
| 7 | Three-phase page loading strategy | — |
| 8 | Husky pre-commit hooks for build artifacts | — |
| 9 | ISI as a first-class block | — |
| 10 | Self-hosted fonts | — |
| 11 | Never add require-trusted-types-for without a policy | Added and reverted once before being recorded |
| 12 | Resolve DOM XSS by removing the sink, not suppressing the finding | — |
| 13 | One shared sanitizer, with two deliberate exceptions | — |
| 14 | Downstream projects pull releases; nothing is pushed | — |
| 15 | Configuration lives in the Config Service API, not fstab.yaml | — |
ADR-001 to ADR-010 use Rationale — the reasoning as it stood when the choice was made. ADR-011 onward replace it with What was measured, and carry the numbers. The newer format is the standard for new records: an ADR that cannot state what was measured is usually not yet a decision. The earlier ten are not being retrofitted, because inventing measurements after the fact would be worse than the gap.
Design principles are not ADRs and live on their own page — see Design Principles.
ADR-001: Repoless Architecture for Block Sharing
Context
Multiple AEM EDS sites within the AbbVie portfolio need to share a common set of blocks, styles, and scripts. Options considered:
- Copy blocks between site repositories
- npm package distributed as a dependency
- Repoless architecture with a single block library repository
Decision
Adopt repoless architecture. RHEA serves as a centralized block library that consuming sites reference via EDS block resolution.
Rationale
- Bug fixes propagate to all sites without per-site updates
- Consistent design language enforced at the source
- No dependency version management overhead
- EDS natively supports this pattern via block resolution fallback
- Sites can still override individual blocks when needed
Tradeoffs
- All consuming sites share the same block versions (no pinning)
- Breaking changes affect all sites simultaneously
- Requires careful backwards-compatible development
ADR-002: AEM Edge Delivery Services as Delivery Platform
Context
The organization needs a web delivery platform for content-driven sites with strict performance requirements (Lighthouse 100) and WYSIWYG authoring.
Decision
Use AEM Edge Delivery Services as the primary delivery platform for content-driven websites.
Rationale
- Native Lighthouse 100 performance architecture
- WYSIWYG authoring via Universal Editor
- Global CDN with instant preview environments per branch
- Minimal infrastructure management (serverless edge delivery)
- Integration with existing AEM Cloud Service investment
Tradeoffs
- Block-based content model requires authors to think in blocks, not freeform layout
- Limited server-side logic (edge-only, no application server)
- Dependency on Adobe's EDS platform and its evolution
ADR-003: SCSS with Committed Compiled Output
Context
EDS serves files directly from the GitHub repository. There is no server-side build step at deployment time. CSS must be present in the repository as ready-to-serve files.
Decision
Use SCSS for authoring styles, compile to .min.css, and commit compiled output to the repository.
Rationale
- SCSS provides variables, mixins, nesting, and imports for maintainable stylesheets
- Compiled output is required because EDS has no build step
- Pre-commit hooks automate compilation and staging
- Autoprefixer ensures cross-browser compatibility
Tradeoffs
- Compiled files in the repository increase diff noise
- Merge conflicts possible in .min.css files (mitigated by pre-commit rebuild)
- Two sources of truth for styles (SCSS source and CSS output)
ADR-004: Style Dictionary for Design Token Pipeline
Context
Design tokens from Figma need to be transformed into CSS custom properties and SCSS variables, with support for light/dark themes and per-block overrides.
Decision
Use Style Dictionary with custom transforms to convert Figma tokens into consumable style variables.
Rationale
- Industry-standard tool for design token transformation
- Extensible transform pipeline supports custom naming, units, and theme splitting
- Generates both SCSS variables and CSS custom properties
- Supports the three-tier token hierarchy (common > semantic > block-specific)
Tradeoffs
- Custom transforms add complexity to the build pipeline
- Token updates require running the full pipeline (automated via pre-commit)
- Style Dictionary v5 API has a learning curve
ADR-005: Two Sanitizers, Used at Different Points
Superseded the original wording (2026-09). This record previously said "use DOMPurify for all dynamic HTML insertion in ISI, footer, and editor support". That is no longer accurate: footer does not use DOMPurify, and a shared in-repo sanitizer now covers most blocks. Anyone following the old text would reach for the wrong tool.
Context
Blocks insert content that originates outside the code: authored richtext from AEM fragments, the fetched query index, editor events, and arbitrary API responses. All of it can carry markup.
Two problems needed solving, and they are not the same problem:
- Is this string safe? — strip dangerous markup from untrusted input.
- Is this assignment safe? — an element.innerHTML = string is a sink a scanner will flag and a future edit can reintroduce, even when the string is clean.
Decision
Use both, at different points. They are complementary, not alternatives.
| Tool | Where | Purpose |
|---|---|---|
| DOMPurify (scripts/dompurify.min.js) | blocks/isi, blocks/embed, scripts/editor-support.js | Sanitize a string at the boundary, where content arrives |
| scripts/utilities/sanitize.js | footer, header, search, cookie-consent-banner, api-widget, isi | Remove the sink: insert DOM nodes instead of assigning a string |
isi uses both, and that is correct rather than accidental: DOMPurify cleans the fragment content as it is read, then setSanitizedHTML inserts it without an innerHTML assignment.
Rationale
- DOMPurify stays for boundary sanitization where it was already load-bearing. It is the most widely tested library for the job, and is bundled locally so security-critical code has no CDN dependency.
- sanitize.js exists because sanitizing into a sink still leaves the sink. Snyk's taint analysis cannot follow a value through a sanitizer helper, so it reports the assignment regardless — and more importantly, a later edit can drop the sanitizer while the assignment survives. Removing the assignment removes that whole failure mode.
- It also consolidated three near-identical private sanitizers in footer, header and api-widget. That duplication caused a real defect: footer sanitized its navigation richtext but silently missed its copyright richtext.
Which to reach for
- Inserting authored or fetched content into the DOM → setSanitizedHTML / sanitizeToFragment from scripts/utilities/sanitize.js.
- Cleaning a string at the point it arrives, in a block that already uses DOMPurify → keep DOMPurify.
- Do not write a third sanitizer. Two documented ones is the intended state.
api-widget deliberately keeps a local allow-list sanitizer and a quote-preserving escapeText — see ADR-013.
Tradeoffs
- Two mechanisms is more to explain than one, which is why this record exists.
- DOMPurify adds ~15KB minified, and is only loaded by the blocks that use it.
- sanitize.js is a deny-list, correct for authored richtext where unknown-but-harmless tags should survive. It is the wrong shape for arbitrary API responses, hence the api-widget exception.
ADR-006: mitt for Inter-Component Event Bus
Context
Blocks need to communicate without direct coupling (e.g., CTA opening a modal, ISI state changes, cookie consent events).
Decision
Use mitt as a global event bus (window.Bus), vendored locally at scripts/vendor/mitt.min.js and imported same-origin.
Rationale
- Tiny library (~200 bytes gzipped)
- Simple pub/sub API (emit, on, off)
- Decouples block implementations
- Vendored locally -- no third-party CDN runtime dependency, served same-origin under the existing CSP
Tradeoffs
- The vendored bundle must be updated manually (or via Renovate against the source package) rather than tracking a CDN version
- Global singleton pattern (window.Bus) -- no scoping or namespacing beyond event names
- No type safety on event payloads
ADR-007: Three-Phase Page Loading Strategy
Context
EDS targets Lighthouse 100 performance scores. Loading all blocks, scripts, and styles eagerly would degrade LCP and TTI metrics.
Decision
Implement a three-phase loading strategy: Eager (LCP-critical), Lazy (below-the-fold), and Delayed (3-second deferred).
Rationale
- First section loads immediately for optimal LCP
- Below-the-fold content loads progressively
- Third-party scripts deferred 3 seconds to avoid blocking interactivity
- Font preloading strategy differs by viewport (desktop vs. mobile)
Tradeoffs
- Content below the fold may flash briefly as sections load
- 3-second delay on third-party scripts may affect early analytics capture
- Complexity in managing load order dependencies
ADR-008: Husky Pre-Commit Hooks for Build Artifacts
Context
Compiled CSS, merged JSON, and generated token files must be committed to the repository. Developers may forget to run build commands before committing.
Decision
Use Husky pre-commit hooks to automatically detect source changes, run the appropriate build, and stage compiled artifacts.
Rationale
- Prevents commits with out-of-sync source and compiled files
- Developers don't need to remember build commands
- Conditional execution (only runs relevant builds based on changed files)
- Lint auto-fix included to enforce code quality
Tradeoffs
- Pre-commit hooks add time to every commit
- Can be bypassed with --no-verify (should be discouraged)
- Complex hook logic (.husky/pre-commit.mjs) requires maintenance
ADR-009: ISI as a First-Class Block
Context
As a pharma company, AbbVie requires Important Safety Information (ISI) on product pages. ISI has specific UX requirements: sticky banner, expand/collapse, per-page variants, and auto-hide when the full ISI scrolls into view.
Decision
Implement ISI as a dedicated first-class block in the RHEA library with full fragment support, per-page configuration, and event bus integration.
Rationale
- Consistent ISI behavior across all pharma sites
- Per-page variant support via metadata (different products, different ISI content)
- Sticky banner with auto-hide is a non-trivial interaction that benefits from centralized implementation
- DOMPurify sanitization for legal content safety
- Event bus integration enables other blocks to react to ISI state changes
Tradeoffs
- ISI is pharma-specific; non-pharma sites must disable it via metadata
- Complex interaction pattern (sticky + expand + auto-hide + per-page fragments)
ADR-010: Self-Hosted Fonts
Context
The project uses the Roboto font family. Options: Google Fonts CDN, Adobe Fonts, or self-hosted.
Decision
Self-host Roboto font files in woff2 format in the repository's fonts/ directory.
Rationale
- No external dependency on font CDNs (Google, Adobe)
- No GDPR/privacy concerns from third-party font services
- Full control over font loading strategy (preload on desktop, lazy on mobile)
- Consistent availability regardless of third-party service status
Tradeoffs
- Font files committed to repository increase repo size
- Must manually update font files if the font is updated
- Only woff2 format (no fallback to woff/ttf for very old browsers)
ADR-011: Never Add require-trusted-types-for Without a Policy
Context
Upstream aem-boilerplate carries require-trusted-types-for 'script' in its CSP, so its absence in RHEA looks like an oversight and invites a "hardening" change. One was opened and merged before being reverted.
Decision
The directive is deliberately absent from head.html and 404.html. Do not add it unless a Trusted Types default policy ships and is verified in the same change.
What was measured
| Elements rendered | CSP violations | |
|---|---|---|
| Without the directive | 993 | 0 |
| With the directive, no policy | 557 | 15 |
The header, footer, ISI and cookie banner were all stripped from the page. The directive makes the browser reject assignments to the sinks Trusted Types covers — innerHTML and outerHTML, script.src, eval/new Function — unless the value is a Trusted* object, which only a policy can mint. Uncovered operations are unaffected: textContent, setAttribute on non-URL attributes, and createElement/append node building all keep working. That is precisely why 557 of 993 elements still rendered rather than none.
The breakage is severe here regardless, because this codebase reaches those covered sinks throughout — which is also why the ADR-012 sink-removal work is what makes a future Trusted Types adoption realistic.
Measured separately on a consuming site, the failure is worse: 42 violations, GTM dead, jQuery undefined, OneTrust banner absent. Its inline GTM bootstrap assigns j.src -- a TrustedScriptURL sink -- before page scripts run, so no policy defined in page code can cover it.
Tradeoffs
- Forgoes a defence-in-depth layer that would be useful in a codebase built for it. The shared sanitizer is the mitigation instead.
- A warning is recorded inline in head.html. Removing that comment is how this decision gets silently reversed.
- Reversing it breaks the page immediately and visibly, which is the one mercy.
ADR-012: Resolve DOM XSS by Removing the Sink, Not Suppressing the Finding
Context
Snyk Code reported 14 javascript/DOMXSS findings across six blocks. Nine were already sanitized on the way in, so an earlier plan classified those as false positives to suppress with Snyk UI ignores -- Snyk's taint analysis cannot follow a value through a sanitizer helper, so it reports the sink regardless.
Decision
Do not suppress. Remove the sink: replace element.innerHTML = string with setSanitizedHTML(element, string) or sanitizeToFragment(string), which insert DOM nodes and never assign a string.
What was measured
snyk code test went 14 to 0 on shipped code, with no UI ignores and nothing added to the ignore: section of .snyk (which covers Open Source scanning only, so could not have recorded them anyway).
Four of the five findings that were not sanitizer false-positives proved genuinely exploitable, confirmed by authoring a payload into every input and driving each block through its real decorate() entry point. The "these are all false positives" framing was wrong on its own terms.
Tradeoffs
- No standing ignore to audit, and no list of "accepted" findings to re-review.
- A regression appears as a new finding rather than passing silently -- the point of the decision. A suppressed rule stays suppressed after the code changes underneath it.
- Slightly more code at each call site than a bare assignment.
ADR-013: One Shared Sanitizer, With Two Deliberate Exceptions
Context
footer.js, header.js and api-widget.js each carried a near-identical private sanitizer.
Decision
One implementation in scripts/utilities/sanitize.js, imported everywhere. Two exceptions in api-widget are deliberate and must not be consolidated away.
What was measured
The duplication was not merely untidy -- it caused the defect. footer.js sanitized its navigation richtext and silently missed its copyright richtext: two sanitizers in one file, one of them not applied.
The two exceptions, both pinned by test:
- A local allow-list sanitizer. The shared helper is a deny-list, correct for authored richtext where unknown-but-harmless tags should survive. api-widget renders an arbitrary API response, where anything not explicitly known-safe should be unwrapped instead.
- A quote-preserving escapeText. syntaxHighlight tokenizes JSON by matching literal " characters. Using the shared escapeHTML there escapes quotes to ", every key stops matching, and syntax highlighting silently disappears -- no error, just a feature quietly gone.
The title="..." attribute in the same file does use the shared escapeHTML, because attribute context requires quote escaping.
Tradeoffs
- A single place to fix a sanitizer bug, and a single place to review.
- api-widget looks inconsistent on a skim. It is not; comments sit beside both functions, and this record exists so they are not "cleaned up".
- A detached element is not inert. document.createElement('div') + innerHTML still belongs to the live document, so <img src=x onerror=...> fires even though the node is never appended. Use DOMParser when you only need text.
ADR-014: Downstream Projects Pull Releases; Nothing Is Pushed
Context
RHEA is a template. Projects created from it inherit blocks, core scripts and tooling, then diverge. When a fix lands in core, something has to get it to them. The first approach was to open a PR in each project centrally.
Decision
Core publishes releases; each project decides when to adopt. Adoption means taking the specific paths a release names (git checkout <tag> -- <paths>), not merging a core branch.
What was measured
Dry-run merging core's develop into one consuming project:
| Files | Conflicts | |
|---|---|---|
| The actual fix | 3 | -- |
| Merging to deliver it | 197 | 29 |
The conflicts were overwhelmingly paths that are supposed to differ: brand design tokens, head.html (per-project GTM and OneTrust), compiled styles/*.min.css, project-specific auto-blocks. A merge treats correct brand divergence as conflict to resolve.
The same dry-run against a project synced days earlier merged with 0 conflicts -- so the cost tracks drift age, not merge mechanics.
A merge is also silently destructive in the other direction: one project carried a more precise analytics comment than core, and taking "theirs" on conflicts would have discarded it.
Tradeoffs
- A project can decline a change, and that is valid -- but a decline must be recorded, or it is indistinguishable from nobody noticing.
- Security fixes do not self-adopt. Visibility is kept centrally; the decision to act stays with the project. Visibility is not coercion.
- Each port is real engineering, not a copy: one project needed 14 sinks hand-fixed across 6 blocks because its blocks had diverged.
- The honest end state, if this becomes routine, is a versioned package for core rather than a template -- then adoption is npm update and none of the above applies.
ADR-015: Configuration Lives in the Config Service API, Not fstab.yaml
Context
Most EDS projects define their content mountpoint in a committed fstab.yaml. RHEA does not have one, which looks like a missing file -- and CLAUDE.md described it as if the file existed, which actively misled readers.
Decision
RHEA is repoless: the content mountpoint and other site configuration live in the AEM Configuration Service API. There is no fstab.yaml at the repo root, and adding one would not be read.
What was measured
file-based-starter/fstab.yaml exists and is easily mistaken for live config. It is a template for converting to file-based (document mode), not the current configuration.
The practical consequence of the confusion: CLAUDE.md stated "Mountpoint defined in fstab.yaml" while no such file existed, so any reader would look for a file that is not there -- or worse, create one.
Tradeoffs
- Configuration is not visible in the repo; reading eds-site-config or the Admin API is required to know where content comes from.
- Multiple sites can consume the same code without duplicating it, which is the point.
- Do not add a root fstab.yaml to "fix" its absence.
Related Documents
- EDS Architecture Overview -- Architecture context
- Security Model -- Security-related decisions
- DevOps Overview -- DevOps decisions in practice