# maetzi87/lovelace-mushroom-50px architecture

> Architecture diagram of the GitHub repository maetzi87/lovelace-mushroom-50px, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maetzi87/lovelace-mushroom-50px
- Repository: https://github.com/maetzi87/lovelace-mushroom-50px

## Overview

1. **What this repo is**
   - Mushroom is a **Home Assistant Lovelace custom card library** packaged as a single browser-side JavaScript module.
   - It is not a backend service; it runs inside the **Home Assistant frontend** and plugs into the dashboard editor/runtime.

2. **Top-level packaging boundary**
   - The deliverable is the compiled asset in **`dist/mushroomic.js`**.
   - Source is TypeScript under **`src/`**, bundled via **Rollup** and validated/released by GitHub Actions.
   - **`hacs.json`** and the README installation flow show that distribution is centered on **HACS** and manual `local` resource loading.

3. **Core product shape: cards and badges**
   - The main features are Lovelace **cards** in `src/cards/` and a Lovelace **badge** in `src/badges/`.
   - Each feature follows the same split: a runtime component, an editor component, and a config type.
   - This makes the repo an extensible UI component system rather than a single monolithic dashboard widget.

4. **Card subsystem**
   - `src/cards/*` contains the user-facing UI blocks, with domain-oriented cards for entities like **alarm control panel, climate, cover, light, lock, media player, update, vacuum, etc.**
   - There is also a more generic **template** family and an `empty`/`title`/`chips` style of structural cards.
   - The card layer is where entity state is turned into visual controls and actions.

5. **Badge subsystem**
   - `src/badges/template/*` provides the badge implementation.
   - The README notes this badge is intended for newer Home Assistant versions, so the badge boundary is version-sensitive and tied to the Lovelace badge API.

6. **Home Assistant adapter layer**
   - `src/ha/` is the main integration boundary with Home Assistant frontend internals.
   - It contains wrappers for **entity metadata/state**, **domain-specific data**, **translations**, **themes**, **main window access**, and Lovelace panel utilities.
   - This layer isolates Mushroom from direct coupling to raw Home Assistant APIs and centralizes compatibility logic.

7. **How data flows through the system**
   - Home Assistant provides entity state, registries, translations, themes, and Lovelace config.
   - Mushroom’s HA layer computes derived values such as display names, domain/object IDs, color/state representations, and feature support.
   - Those computed values flow into card and badge renderers, which then emit user interactions back to Lovelace/HA services.

8. **Editor and form pipeline**
   - `src/utils/lovelace/` and `src/ha/panels/lovelace/` hold the editor plumbing for configuring cards from the UI.
   - `src/utils/form/` and shared config models define reusable form fields, selectors, and config schemas.
   - The architecture is strongly editor-driven: the same component family supports both **rendering** and **configuration**.

9. **Shared visual primitives**
   - `src/shared/` contains reusable building blocks such as buttons, chips, sliders, state labels, badge icons, avatars, and config fragments.
   - These are the design system layer used across many cards to keep styling and behavior consistent.
   - This reduces duplication and keeps entity cards visually uniform.

10. **Cross-cutting utilities**
   - `src/utils/` handles the non-domain infrastructure: appearance, colors, layout, caching, loading, theming, keyframes, icons, weather helpers, and custom element registration helpers.
   - It also includes generic Lovelace helpers and error handling around sub-editors and GUI support.
   - These utilities sit underneath both the card runtime and the editor runtime.

11. **Localization and theming**
   - `src/translations/` plus `src/localize.ts` provide internationalization across many languages.
   - `src/utils/theme.ts`, `src/utils/colors.ts`, and related helpers define the theme-aware styling model, with explicit support for light/dark modes and Material-style colors.
   - The README’s theme notes and the file layout show theming is a first-class architectural concern, not an afterthought.

12. **Development and demo environment**
   - `.hass_dev/` is a self-contained **Home Assistant demo configuration** used to exercise cards, views, and packages during development.
   - This repo therefore has a two-part workflow: build the library, then test it inside a real Home Assistant instance.
   - That makes the browser/HA integration boundary the main integration test surface.

13. **Documentation and release boundary**
   - `docs/cards/*` and `docs/badges/*` document each user-facing component separately, matching the architecture of individual card modules.
   - GitHub Actions (`build`, `validate`, `release`) and the HACS metadata support the operational lifecycle: verify, bundle, publish, and distribute.
   - The repo is thus structured around a **frontend component library + Home Assistant compatibility layer + packaging/release pipeline**.

Main entry points: [`src/cards`](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/cards) (Cards), [`src/badges/template`](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/badges/template) (Badge), [`src/mushroomic.ts`](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/mushroomic.ts) (Entrypoint), [`src/shared`](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/shared) (Primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_packaging["Packaging"]
  node_dist_bundle["Bundle<br/>built asset<br/>[mushroomic.js]"]
  node_rollup["Rollup<br/>build config<br/>[rollup.config.mjs]"]
  node_github_actions["CI/CD<br/>workflow<br/>[workflows]"]
  node_hacs_meta["HACS<br/>distribution config<br/>[hacs.json]"]
end

subgraph group_core["Core UI"]
  node_cards["Cards<br/>UI card set"]
  node_badge["Badge"]
  node_entrypoint["Entrypoint<br/>module entry<br/>[mushroomic.ts]"]
end

subgraph group_ha["Home Assistant"]
  node_ha_index["HA Bridge<br/>adapter entry<br/>[index.ts]"]
  node_entity_data["Entity Data<br/>state model"]
  node_lovelace_panel["Lovelace Panel<br/>editor/runtime bridge"]
  node_ha_common["HA Common<br/>compat helpers"]
end

subgraph group_shared["Shared UI"]
  node_shared_primitives["Primitives<br/>ui building blocks"]
  node_shared_config["Config Models<br/>config schema"]
end

subgraph group_utils["Utilities"]
  node_appearance["Appearance<br/>style system"]
  node_form_editor["Forms"]
  node_lovelace_utils["Lovelace Utils<br/>editor utilities"]
  node_localize["Localization<br/>i18n layer<br/>[localize.ts]"]
end

subgraph group_content["Docs & Demo"]
  node_demo["Demo HA<br/>demo config<br/>[.hass_dev]"]
  node_docs["Docs<br/>documentation"]
end

node_rollup -->|"builds"| node_dist_bundle
node_entrypoint -->|"registers"| node_cards
node_entrypoint -->|"registers"| node_badge
node_entrypoint -->|"uses"| node_ha_index
node_entrypoint -->|"composes"| node_shared_primitives
node_entrypoint -->|"styles"| node_appearance
node_cards -->|"reads"| node_entity_data
node_cards -->|"composes"| node_shared_primitives
node_cards -->|"typed by"| node_shared_config
node_badge -->|"reads"| node_entity_data
node_badge -->|"composes"| node_shared_primitives
node_badge -->|"typed by"| node_shared_config
node_ha_index -->|"wraps"| node_ha_common
node_ha_index -->|"provides"| node_entity_data
node_ha_index -->|"supports"| node_lovelace_panel
node_entity_data -->|"localizes"| node_localize
node_ha_common -->|"localizes"| node_localize
node_lovelace_panel -->|"configures"| node_form_editor
node_lovelace_panel -->|"orchestrates"| node_lovelace_utils
node_shared_primitives -->|"follows"| node_shared_config
node_appearance -->|"styles"| node_shared_primitives
node_form_editor -->|"binds"| node_shared_config
node_lovelace_utils -->|"supports"| node_form_editor
node_docs -.->|"documents"| node_cards
node_docs -.->|"documents"| node_badge
node_demo -.->|"exercises"| node_cards
node_demo -.->|"exercises"| node_badge
node_github_actions -->|"runs"| node_rollup
node_github_actions -->|"publishes"| node_dist_bundle
node_hacs_meta -->|"references"| node_dist_bundle

click node_dist_bundle "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/dist/mushroomic.js"
click node_rollup "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/rollup.config.mjs"
click node_github_actions "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/.github/workflows"
click node_hacs_meta "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/hacs.json"
click node_cards "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/cards"
click node_badge "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/badges/template"
click node_entrypoint "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/mushroomic.ts"
click node_ha_index "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/ha/index.ts"
click node_entity_data "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/ha/data"
click node_lovelace_panel "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/ha/panels/lovelace"
click node_ha_common "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/ha/common"
click node_shared_primitives "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/shared"
click node_shared_config "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/shared/config"
click node_appearance "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/utils"
click node_form_editor "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/utils/form"
click node_lovelace_utils "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/utils/lovelace"
click node_localize "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/localize.ts"
click node_demo "https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/.hass_dev"
click node_docs "https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/docs"

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_dist_bundle,node_rollup,node_github_actions,node_hacs_meta toneBlue
class node_cards,node_badge,node_entrypoint toneAmber
class node_ha_index,node_entity_data,node_lovelace_panel,node_ha_common toneMint
class node_shared_primitives,node_shared_config toneRose
class node_appearance,node_form_editor,node_lovelace_utils,node_localize toneIndigo
class node_demo,node_docs toneTeal
```

## Components

### Packaging

Build, bundle, distribution, and release boundary.

- [Bundle](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/dist/mushroomic.js): built asset · Compiled browser module distributed to Home Assistant. · `dist/mushroomic.js`
- [Rollup](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/rollup.config.mjs): build config · Bundles the TypeScript sources into the distributable asset. · `rollup.config.mjs`
- [CI/CD](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/.github/workflows): workflow · Build, validate, and release automation. · `.github/workflows`
- [HACS](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/hacs.json): distribution config · Marketplace metadata for Home Assistant community install flow. · `hacs.json`

### Core UI

Runtime custom card and badge entrypoints.

- [Cards](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/cards): UI card set · Main Lovelace card family for entity control and display. · `src/cards`
- [Badge](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/badges/template): UI badge · Template badge implementation for Lovelace badge API. · `src/badges/template`
- [Entrypoint](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/mushroomic.ts): module entry · Top-level Mushroom registration and export surface. · `src/mushroomic.ts`

### Home Assistant

Integration layer for HA frontend APIs, entity data, and Lovelace panel/editor support.

- [HA Bridge](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/ha/index.ts): adapter entry · Main Home Assistant integration surface and compatibility layer. · `src/ha/index.ts`
- [Entity Data](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/ha/data): state model · Entity, registry, domain, and support-feature computation. · `src/ha/data`
- [Lovelace Panel](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/ha/panels/lovelace): editor/runtime bridge · Lovelace-specific panel utilities, action handling, and editor plumbing. · `src/ha/panels/lovelace`
- [HA Common](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/ha/common): compat helpers · Low-level Home Assistant helpers for colors, strings, numbers, DOM, and translations. · `src/ha/common`

### Shared UI

Reusable visual primitives and config fragments.

- [Primitives](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/shared): ui building blocks · Reusable buttons, chips, state visuals, icons, and config fragments. · `src/shared`
- [Config Models](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/shared/config): config schema · Shared Lovelace card and badge config types and fragments. · `src/shared/config`

### Utilities

Cross-cutting helpers for styling, forms, Lovelace editing, and generic runtime behavior.

- [Appearance](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/utils): style system · Theme-aware styling, colors, layout, and card/entity presentation helpers. · `src/utils`
- [Forms](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/utils/form): editor forms · Reusable HA form and selector helpers for card configuration. · `src/utils/form`
- [Lovelace Utils](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/src/utils/lovelace): editor utilities · Generic Lovelace editor and chip-element helpers. · `src/utils/lovelace`
- [Localization](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/src/localize.ts): i18n layer · Translation loading and localized label resolution. · `src/localize.ts`

### Docs & Demo

User documentation and Home Assistant demo environment.

- [Demo HA](https://github.com/maetzi87/lovelace-mushroom-50px/blob/main/.hass_dev): demo config · Home Assistant development configuration and showcase views. · `.hass_dev`
- [Docs](https://github.com/maetzi87/lovelace-mushroom-50px/tree/main/docs): documentation · Per-card and badge documentation matching the component structure. · `docs`

## Connections

- Rollup → Bundle: builds · Bundles source into the published browser asset.
- Entrypoint → Cards: registers · Wires card modules into the custom element surface.
- Entrypoint → Badge: registers · Exposes the badge implementation for Lovelace usage.
- Entrypoint → HA Bridge: uses · Initializes the Home Assistant integration layer.
- Entrypoint → Primitives: composes · Builds the UI from reusable shared components.
- Entrypoint → Appearance: styles · Applies theming and layout helpers across components.
- Cards → Entity Data: reads · Consumes derived entity state and feature data.
- Cards → Primitives: composes · Uses shared buttons, chips, sliders, and state elements.
- Cards → Config Models: typed by · Uses shared card config models and fragments.
- Badge → Entity Data: reads · Consumes entity state and display metadata.
- Badge → Primitives: composes · Uses the shared badge icon and state display primitives.
- Badge → Config Models: typed by · Uses shared badge config models.
- HA Bridge → HA Common: wraps · Centralizes compatibility helpers around Home Assistant internals.
- HA Bridge → Entity Data: provides · Supplies entity/domain/state derivations to the UI layer.
- HA Bridge → Lovelace Panel: supports · Connects Lovelace editor/runtime utilities to HA panel APIs.
- Entity Data → Localization: localizes · Resolves translated names and state text.
- HA Common → Localization: localizes · Shared translation helpers used across HA-facing code.
- Lovelace Panel → Forms: configures · Feeds configuration forms and selectors for editors.
- Lovelace Panel → Lovelace Utils: orchestrates · Coordinates editor plumbing and custom sub-editors.
- Primitives → Config Models: follows · Implements the shared config-driven UI model.
- Appearance → Primitives: styles · Provides theme-aware visual tokens and layout helpers.
- Forms → Config Models: binds · Maps config models into editable form fields.
- Lovelace Utils → Forms: supports · Provides Lovelace-specific editor helpers and wrappers.
- Docs → Cards: documents · Documents each user-facing card family.
- Docs → Badge: documents · Documents the badge component.
- Demo HA → Cards: exercises · Showcases card behavior in a real Home Assistant instance.
- Demo HA → Badge: exercises · Provides demo coverage for badge behavior.
- CI/CD → Rollup: runs · Build workflow validates the bundle pipeline.
- CI/CD → Bundle: publishes · Release workflow ships the compiled asset.
- HACS → Bundle: references · Points Home Assistant install flows at the distributable module.
