Back to Code Reference
Architecture Documentation
Complete data flow and implementation architecture
GA4 + UCP Data Flow
This diagram illustrates the complete data flow from user interaction through Universal Commerce Protocol to Google Analytics 4, showing how BEM naming conventions enable stable tracking.
┌─────────────────────────────────────────────────────────────────┐
│ Universal Commerce Protocol (UCP) │
│ │
│ • User Authentication (JWE/JWT Token) │
│ • Session Management │
│ • Consent State Tracking │
│ • User Context & History │
└────────────────────────┬────────────────────────────────────────┘
│
│ Token & User Context
▼
┌─────────────────────────────────────────────────────────────────┐
│ Middleware Layer (Xano / n8n) │
│ │
│ • Validate UCP Token │
│ • Transform User Data │
│ • Enrich Event Context │
│ • Route to Analytics Endpoints │
└────────────────────────┬────────────────────────────────────────┘
│
│ Processed Event Data
▼
┌─────────────────────────────────────────────────────────────────┐
│ Frontend Application │
│ │
│ HTML with BEM Classes: │
│ <button class="product-card__button" │
│ data-action="add-to-cart" │
│ data-item-id="prod-12345" │
│ data-item-name="Product Name" │
│ data-item-price="24.99"> │
│ Add to Cart │
│ </button> │
└────────────────────────┬────────────────────────────────────────┘
│
│ User Interaction (Click Event)
▼
┌─────────────────────────────────────────────────────────────────┐
│ JavaScript Event Handler │
│ │
│ document.addEventListener('click', (e) => { │
│ const btn = e.target.closest( │
│ '.product-card__button[data-action="add-to-cart"]' │
│ ); │
│ if (btn) { │
│ ga4Tracker.trackAddToCart(btn); │
│ } │
│ }); │
└────────────────────────┬────────────────────────────────────────┘
│
│ Extract Data from BEM Attributes
▼
┌─────────────────────────────────────────────────────────────────┐
│ GTM Data Layer Push │
│ │
│ window.dataLayer.push({ │
│ event: 'add_to_cart', │
│ user_id: ucp.userId, │
│ ucp_token_hash: ucp.getHashedToken(), │
│ ucp_session_id: ucp.sessionId, │
│ element_class: 'product-card__button', │
│ element_action: 'add-to-cart', │
│ ecommerce: { │
│ currency: 'USD', │
│ value: 24.99, │
│ items: [{ │
│ item_id: 'prod-12345', │
│ item_name: 'Product Name', │
│ price: 24.99, │
│ quantity: 1 │
│ }] │
│ } │
│ }); │
└────────────────────────┬────────────────────────────────────────┘
│
│ Trigger GTM Tags
▼
┌─────────────────────────────────────────────────────────────────┐
│ Google Tag Manager (GTM) │
│ │
│ Tag: GA4 - Add to Cart Event │
│ Trigger: Custom Event = 'add_to_cart' │
│ │
│ Event Parameters: │
│ • user_id: {{DLV - user_id}} │
│ • ucp_token_hash: {{DLV - ucp_token_hash}} │
│ • ucp_session_id: {{DLV - ucp_session_id}} │
│ • element_class: {{Click Classes}} │
│ • ecommerce.items: {{DLV - ecommerce.items}} │
└────────────────────────┬────────────────────────────────────────┘
│
│ Send Event to GA4
▼
┌─────────────────────────────────────────────────────────────────┐
│ Google Analytics 4 (GA4) │
│ │
│ Event: add_to_cart │
│ Parameters: │
│ • user_id: "user_12345" │
│ • ucp_token_hash: "abc123..." │
│ • ucp_session_id: "sess_67890" │
│ • element_class: "product-card__button" │
│ • items: [{ item_id, item_name, price, quantity }] │
│ │
│ ✓ Event recorded in GA4 property │
│ ✓ Available in reports and explorations │
│ ✓ Can be used for audiences and conversions │
└─────────────────────────────────────────────────────────────────┘
Key Benefits of This Architecture:
1. Stable Tracking: BEM class selectors never break with design changes
2. UCP Integration: Secure user context flows through entire pipeline
3. Semantic Structure: AI agents can parse and understand user actions
4. Privacy-First: Token is hashed before sending to analytics
5. Maintainable: Clear separation of concerns at each layerImplementation Checklist
Analysis and Summary
Live performance comparison between React + Tailwind CSS and 11ty + UIKit implementations, demonstrating real-world performance differences.
React + Tailwind CSS
- Load Time: 1.22 seconds
- Bundle Size: 630 KB
- Resources: 15 HTTP requests
11ty + UIKit
- Load Time: 0.67 seconds
- Bundle Size: 49 KB
- Resources: 5 HTTP requests
Performance Improvements
45%
Faster Load Time
92%
Smaller Bundle
67%
Fewer Resources
10x
Lighter Payload
Measurement Methodology
The comparison uses vanilla JavaScript with the Performance API to measure load times accurately. Each version loads in an isolated iframe to ensure fair comparison. Metrics tracked include:
- Load Time: Total time from iframe initialization to complete page load (green < 1s, yellow 1-3s, red > 3s)
- Bundle Size: Total transferred data including HTML, CSS, JavaScript, and assets (green < 100KB, yellow 100-500KB, red > 500KB)
- Resources: Number of HTTP requests during page load (green < 10, yellow 10-20, red > 20)
Key Findings
The 11ty + UIKit implementation demonstrates significant performance advantages:
- Static Generation: Pre-rendered HTML eliminates client-side rendering overhead
- Minimal JavaScript: UIKit's modular approach loads only required components
- No Framework Runtime: No React or virtual DOM overhead in production
- Optimized Assets: CDN-delivered UIKit assets are highly cached
- Semantic HTML: BEM class selectors enable stable tracking without breaking with design changes
The live comparison effectively demonstrates the 45% load time improvement and 92% bundle size reduction, validating the revenue analysis findings for 11ty + UIKit over React + Tailwind CSS.
Tag Event Label & Class ID Criteria
Standardized naming conventions for GTM tags and BEM class selectors to ensure consistent, maintainable tracking across the application.
Event Label Naming Convention
Format: [action]_[element]_[location]
Examples:
├── click_add-to-cart_product-card
├── click_checkout_cart-summary
├── submit_newsletter_footer
├── view_product_collection-grid
└── scroll_section_homepage-heroBEM Class Selectors
| Pattern | Usage |
|---|---|
.block__element |
Primary trackable elements |
.block__element--modifier |
State-specific tracking |
[data-action="value"] |
Action identification |
[data-item-id="value"] |
Product/item tracking |
GTM Trigger Selectors
| Selector | Event |
|---|---|
.product-card__button |
add_to_cart |
.cart__checkout-btn |
begin_checkout |
.checkout__submit |
purchase |
.product-grid__item |
view_item_list |
Required Data Attributes by Event Type
<!-- E-commerce Product Element -->
<div class="product-card"
data-item-id="SKU-12345"
data-item-name="Product Name"
data-item-brand="Brand"
data-item-category="Category"
data-item-price="99.99"
data-item-currency="USD">
<button class="product-card__button"
data-action="add-to-cart"
data-quantity="1">
Add to Cart
</button>
</div>
<!-- Purchase/Checkout Element -->
<button class="checkout__submit"
data-action="purchase"
data-transaction-id="TXN-67890"
data-value="149.99"
data-tax="12.50"
data-shipping="5.99"
data-coupon="SAVE10">
Complete Purchase
</button>Financial Conversion Tracking Matrix
| Event | Class Selector | Data Attributes | GA4 Parameter | Revenue Impact |
|---|---|---|---|---|
| view_item | .product-card |
item_id, item_name, price | items[] | Awareness |
| add_to_cart | .product-card__button |
item_id, quantity, price | items[], value | Intent |
| begin_checkout | .cart__checkout-btn |
items[], coupon | items[], value, coupon | Commitment |
| add_payment_info | .checkout__payment |
payment_type | payment_type, value | High Intent |
| purchase | .checkout__submit |
transaction_id, value, tax, shipping | transaction_id, value, items[] | Conversion |
All selectors use BEM methodology for stability. Data attributes provide semantic context for AI agent parsing and UCP integration.