# hyva-themes/magento2-theme-module architecture

> Architecture diagram of the GitHub repository hyva-themes/magento2-theme-module, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyva-themes/magento2-theme-module
- Repository: https://github.com/hyva-themes/magento2-theme-module

## Overview

Hyvä’s Magento theme module supplies shared storefront infrastructure rather than a complete theme. Its runtime spans theme detection and layout integration, template-facing view models, asset and interaction helpers, and cache/dependency handling; it also provides sample-data commands. The README describes the module’s role but not detailed runtime wiring, so the graph uses only relationships shown in sampled source or SOURCE INDEX references; unsampled capabilities are represented without inferred call edges.

Main entry points: [`src/Observer/RegisterPageJsDependencies.php`](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Observer/RegisterPageJsDependencies.php) (JS dependency observer), [`src/Service/CurrentTheme.php`](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/CurrentTheme.php) (Current theme), [`src/Console/SampleDataCommandList.php`](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/SampleDataCommandList.php) (Sample-data commands), [`src/Service/HyvaThemes.php`](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/HyvaThemes.php) (Hyvä themes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_theme["Theme integration"]
  node_current_theme["Current theme<br/>[CurrentTheme.php]"]
  node_hyva_themes["Hyvä themes<br/>[HyvaThemes.php]"]
  node_di_reader["DI theme reader"]
  node_layout_handles["Layout handles"]
  node_catalog_breadcrumbs["Catalog breadcrumbs<br/>[Breadcrumbs.php]"]
end

subgraph group_storefront["Storefront APIs"]
  node_store_viewmodel["Store view model<br/>[Store.php]"]
  node_customer_reviews["Customer reviews<br/>[ReviewList.php]"]
  node_product_page["Product page APIs<br/>[ProductPage.php]"]
  node_cart_apis["Cart APIs<br/>[Items.php]"]
end

subgraph group_assets["Assets and UI"]
  node_media_viewmodel["Media view model<br/>[Media.php]"]
  node_media_provider["Media HTML provider"]
  node_modal_viewmodel["Modal view model<br/>[Modal.php]"]
  node_modal_builder["Modal builder<br/>[ModalBuilder.php]"]
  node_svg_icons["SVG icons<br/>[SvgIcons.php]"]
  node_lucide_icons["Lucide icons<br/>[LucideIcons.php]"]
  node_alpine["Alpine runtime<br/>[alpine3.js]"]
end

subgraph group_runtime["Rendering runtime"]
  node_js_observer["JS dependency observer"]
  node_js_registry["Page JS registry"]
  node_block_js["Block JS dependencies"]
  node_block_cache["Block cache view model<br/>[BlockCache.php]"]
  node_cache_tags[("HTML cache-tag storage")]
end

subgraph group_admincli["Admin and commands"]
  node_sample_commands["Sample-data commands"]
  node_sample_deploy["Sample-data deploy<br/>[DeployCommand.php]"]
  node_sample_remove["Sample-data remove<br/>[RemoveCommand.php]"]
end

node_magento(("Magento storefront"))

node_magento -.->|"dispatches event"| node_layout_handles
node_layout_handles -->|"checks theme"| node_current_theme
node_current_theme -->|"checks theme"| node_hyva_themes
node_hyva_themes -->|"reads fallback"| node_di_reader
node_media_viewmodel -->|"uses provider"| node_media_provider
node_media_provider -->|"uses store data"| node_store_viewmodel
node_modal_viewmodel -->|"uses builder"| node_modal_builder
node_lucide_icons -->|"extends icons"| node_svg_icons
node_js_observer -->|"checks theme"| node_current_theme
node_js_observer -->|"registers dependencies"| node_js_registry
node_js_observer -->|"collects dependencies"| node_block_js
node_js_observer -->|"reads cache tags"| node_block_cache
node_block_cache -->|"stores cache tags"| node_cache_tags
node_sample_commands -->|"registers command"| node_sample_deploy
node_sample_commands -->|"registers command"| node_sample_remove

click node_current_theme "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/CurrentTheme.php"
click node_hyva_themes "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/HyvaThemes.php"
click node_di_reader "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/HyvaBaseThemesDiXmlReader.php"
click node_layout_handles "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Observer/AddLayoutHandles.php"
click node_catalog_breadcrumbs "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Block/Catalog/Breadcrumbs.php"
click node_store_viewmodel "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Store.php"
click node_customer_reviews "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Customer/ReviewList.php"
click node_product_page "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/ProductPage.php"
click node_cart_apis "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Cart/Items.php"
click node_media_viewmodel "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Media.php"
click node_media_provider "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/Media/MediaHtmlProvider.php"
click node_modal_viewmodel "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Modal.php"
click node_modal_builder "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/Modal/ModalBuilder.php"
click node_svg_icons "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/SvgIcons.php"
click node_lucide_icons "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/LucideIcons.php"
click node_alpine "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/view/base/web/js/alpine3.js"
click node_js_observer "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Observer/RegisterPageJsDependencies.php"
click node_js_registry "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/PageJsDependencyRegistry.php"
click node_block_js "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/BlockJsDependencies.php"
click node_block_cache "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/BlockCache.php"
click node_cache_tags "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/HtmlBlockCacheTagsStorage.php"
click node_sample_commands "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/SampleDataCommandList.php"
click node_sample_deploy "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/Command/SampleData/DeployCommand.php"
click node_sample_remove "https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/Command/SampleData/RemoveCommand.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_current_theme,node_hyva_themes,node_di_reader,node_layout_handles,node_catalog_breadcrumbs toneBlue
class node_store_viewmodel,node_customer_reviews,node_product_page,node_cart_apis toneAmber
class node_media_viewmodel,node_media_provider,node_modal_viewmodel,node_modal_builder,node_svg_icons,node_lucide_icons,node_alpine toneMint
class node_js_observer,node_js_registry,node_block_js,node_block_cache,node_cache_tags toneRose
class node_sample_commands,node_sample_deploy,node_sample_remove,node_magento toneIndigo
```

## Components

### Theme integration

- [Current theme](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/CurrentTheme.php): `src/Service/CurrentTheme.php`
- [Hyvä themes](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/HyvaThemes.php): `src/Service/HyvaThemes.php`
- [DI theme reader](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Service/HyvaBaseThemesDiXmlReader.php): `src/Service/HyvaBaseThemesDiXmlReader.php`
- [Layout handles](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Observer/AddLayoutHandles.php): `src/Observer/AddLayoutHandles.php`
- [Catalog breadcrumbs](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Block/Catalog/Breadcrumbs.php): `src/Block/Catalog/Breadcrumbs.php`

### Storefront APIs

- [Store view model](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Store.php): `src/ViewModel/Store.php`
- [Customer reviews](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Customer/ReviewList.php): `src/ViewModel/Customer/ReviewList.php`
- [Product page APIs](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/ProductPage.php): `src/ViewModel/ProductPage.php`
- [Cart APIs](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Cart/Items.php): `src/ViewModel/Cart/Items.php`

### Assets and UI

- [Media view model](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Media.php): `src/ViewModel/Media.php`
- [Media HTML provider](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/Media/MediaHtmlProvider.php): `src/Model/Media/MediaHtmlProvider.php`
- [Modal view model](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/Modal.php): `src/ViewModel/Modal.php`
- [Modal builder](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/Modal/ModalBuilder.php): `src/Model/Modal/ModalBuilder.php`
- [SVG icons](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/SvgIcons.php): `src/ViewModel/SvgIcons.php`
- [Lucide icons](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/LucideIcons.php): `src/ViewModel/LucideIcons.php`
- [Alpine runtime](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/view/base/web/js/alpine3.js): `src/view/base/web/js/alpine3.js`

### Rendering runtime

- [JS dependency observer](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Observer/RegisterPageJsDependencies.php): `src/Observer/RegisterPageJsDependencies.php`
- [Page JS registry](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/PageJsDependencyRegistry.php): `src/Model/PageJsDependencyRegistry.php`
- [Block JS dependencies](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/BlockJsDependencies.php): `src/ViewModel/BlockJsDependencies.php`
- [Block cache view model](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/ViewModel/BlockCache.php): `src/ViewModel/BlockCache.php`
- [HTML cache-tag storage](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Model/HtmlBlockCacheTagsStorage.php): `src/Model/HtmlBlockCacheTagsStorage.php`

### Admin and commands

- [Sample-data commands](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/SampleDataCommandList.php): `src/Console/SampleDataCommandList.php`
- [Sample-data deploy](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/Command/SampleData/DeployCommand.php): `src/Console/Command/SampleData/DeployCommand.php`
- [Sample-data remove](https://github.com/hyva-themes/magento2-theme-module/blob/main/src/Console/Command/SampleData/RemoveCommand.php): `src/Console/Command/SampleData/RemoveCommand.php`

### Other components

- **Magento storefront**

## Connections

- Magento storefront → Layout handles: dispatches event
- Layout handles → Current theme: checks theme (evidence: `src/Observer/AddLayoutHandles.php`)
- Current theme → Hyvä themes: checks theme (evidence: `src/Service/CurrentTheme.php`)
- Hyvä themes → DI theme reader: reads fallback (evidence: `src/Service/HyvaThemes.php`)
- Media view model → Media HTML provider: uses provider (evidence: `src/ViewModel/Media.php`)
- Media HTML provider → Store view model: uses store data (evidence: `src/Model/Media/MediaHtmlProvider.php`)
- Modal view model → Modal builder: uses builder (evidence: `src/Model/Modal/ModalBuilder.php`)
- Lucide icons → SVG icons: extends icons (evidence: `src/ViewModel/LucideIcons.php`)
- JS dependency observer → Current theme: checks theme (evidence: `src/Observer/RegisterPageJsDependencies.php`)
- JS dependency observer → Page JS registry: registers dependencies (evidence: `src/Observer/RegisterPageJsDependencies.php`)
- JS dependency observer → Block JS dependencies: collects dependencies (evidence: `src/Observer/RegisterPageJsDependencies.php`)
- JS dependency observer → Block cache view model: reads cache tags (evidence: `src/Observer/RegisterPageJsDependencies.php`)
- Block cache view model → HTML cache-tag storage: stores cache tags (evidence: `src/Model/HtmlBlockCacheTagsStorage.php`)
- Sample-data commands → Sample-data deploy: registers command (evidence: `src/Console/SampleDataCommandList.php`)
- Sample-data commands → Sample-data remove: registers command (evidence: `src/Console/SampleDataCommandList.php`)