# piotrmachowski/lovelace-xiaomi-vacuum-map-card architecture

> Architecture diagram of the GitHub repository piotrmachowski/lovelace-xiaomi-vacuum-map-card, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card
- Repository: https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card

## Overview

##### Project type and purpose
- This is a frontend custom card for Home Assistant’s Lovelace UI (“xiaomi-vacuum-map-card”).
- It’s written in TypeScript, built with Rollup, and uses LitElement/web components.

##### File structure
- Top‐level build/config files:
- rollup.config.js / rollup.config.dev.js
- tsconfig.json
- package.json / package-lock.json
- ESLint / Prettier / .devcontainer / .vscode / GitHub workflows
- Source code under src/:
- xiaomi-vacuum-map-card.ts (entry point module)
- config-validators.ts (parses & validates YAML config)
- action-handler-directive.ts (handles tap/hold events → dispatch custom events)
- localize/ (i18n resources with translation files)
- renderers/ (custom UI renderers like toast)
- polyfills/ (shims for old browsers)
- utils.ts, const.ts, types/
- docs/: extensive Markdown/YAML examples, templates, video demos, migration guides.

##### Key insights from README
- Purpose: fully‐featured, map‐based vacuum controls (zones, point/goto, room cleaning, follow path).
- Architecture hints: model/generators for presets, service_call_schema, action_handler, UI components, localization.

a. Main components
- Configuration Input (YAML via UI editor or raw Lovelace resources)
- Configuration Validator & Parser (config-validators.ts)
- Model Layer (src/model):
– Map objects (zones, points, room outlines, path)
– Map modes & service-call schema definitions
- Localization (localize/)
- View Layer (src/components + pinch-zoom + renderers):
– Root element (xiaomi-vacuum-map-card) extends LitElement
- Action Handler (action-handler-directive.ts → custom DOM events)
- Home Assistant Integration (calls HA services via custom‐service events)
- Build Pipeline (Rollup → final JS module)
- External dependencies/services: Home Assistant core, HACS, vacuum platform integrations

b. Relationships & interactions
1. User writes or edits YAML config → fed into Configuration Validator
2. Validator outputs a normalized config object → passed to Model Layer
3. Model Layer generates:
– iconList, tileList (based on platform & presets)
– map mode definitions and service_call_schema
– calibration & coordinate conversion modules
4. The entry‐point component (xiaomi-vacuum-map-card) renders:
5. User interacts (click/tap/drag) → Action Handler Directive translates Lit‐events into custom‐DOM events
6. Custom events carry service_call_schema + placeholders → Home Assistant services are invoked
7. Vacuum platform integration handles the actual device API calls
8. Responses/state updates in Home Assistant cause the card to re‐render via Lit’s reactive properties

c. Architectural patterns & principles
- Separation of Concerns:
- Config parsing → Model generation → View rendering → Event handling → Service calls
- MVC‐Like layering: Model (data & behavior), View (LitElement components), Controller (action handler + service dispatcher)
- Plugin/Generator pattern for supporting multiple vacuum platforms via JSON templates + generator wrapper
- Reactive UI using LitElement
- Single‐bundle modularization with Rollup

d. Key technologies/frameworks
- TypeScript for static typing
- Rollup for bundling into a single JS module
- LitElement / web components for UI
- pinch-zoom library for map interactions
- Polyfills for cross-browser support
- Home Assistant’s Lovelace resource API for integration
- JSON templates for vacuum platforms

##### Essential elements
- Clear component names matching the src/ folder (e.g., config-validators.ts, model/generators, components/tile.ts)
- Build pipeline (Rollup & Polyfills) feeding into the final JS resource

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration" 
        CI["User YAML Config"]:::external
        CVP["Config Validator & Parser"]:::parser
    end
    click CVP "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/config-validators.ts"

    %% Model Layer
    subgraph "Model Layer" 
        direction TB
        MW["Generator Wrapper"]:::model
        ILG["Icon List Generator"]:::model
        TG["Tiles Generator"]:::model
        PG["Platform Generator"]:::model
        PT["Platform Templates (.json)"]:::model
        subgraph "Map Modes" 
            direction TB
            MM["map-mode.ts"]:::model
            SCS["service-call-schema.ts"]:::model
            SCT["service-call.ts"]:::model
            MOD["modifier.ts"]:::model
            RT["repeats-type.ts"]:::model
            ST["selection-type.ts"]:::model
            TV["templatable-value.ts"]:::model
        end
        subgraph "Map Objects & Utils"
            direction TB
            MO["map-object.ts"]:::model
            CTX["context.ts"]:::model
            MPC["coordinates-converter.ts"]:::model
            subgraph "Manual Drawables"
                direction TB
                MP["manual-path.ts"]:::model
                MPT["manual-point.ts"]:::model
                MR["manual-rectangle.ts"]:::model
            end
            subgraph "Predefined Drawables"
                direction TB
                PMO["predefined-map-object.ts"]:::model
                PP["predefined-point.ts"]:::model
                PMR["predefined-multi-rectangle.ts"]:::model
            end
            subgraph "Room & Point Types"
                direction TB
                R["room.ts"]:::model
                MAPT["map-point.ts"]:::model
                MSP["mouse-position.ts"]:::model
            end
        end
    end
    click MW "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/generators/generator-wrapper.ts"
    click ILG "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/generators/icon-list-generator.ts"
    click TG "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/generators/tiles-generator.ts"
    click PG "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/generators/platform-generator.ts"
    click PT "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/tree/master/src/model/generators/platform_templates/"
    click MM "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/map-mode.ts"
    click SCS "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/service-call-schema.ts"
    click SCT "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/service-call.ts"
    click MOD "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/modifier.ts"
    click RT "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/repeats-type.ts"
    click ST "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/selection-type.ts"
    click TV "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_mode/templatable-value.ts"
    click MO "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/map-object.ts"
    click CTX "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/context.ts"
    click MPC "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/coordinates-converter.ts"
    click MP "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/manual-path.ts"
    click MPT "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/manual-point.ts"
    click MR "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/manual-rectangle.ts"
    click PMO "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/predefined-map-object.ts"
    click PP "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/predefined-point.ts"
    click PMR "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/predefined-multi-rectangle.ts"
    click R "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/room.ts"
    click MAPT "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/map-point.ts"
    click MSP "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/model/map_objects/mouse-position.ts"

    %% Localization & Renderers
    subgraph "Localization & Renderers"
        LC["localize.ts"]:::utility
        HASS_HELP["hass helpers"]:::utility
        LANG["language JSON files"]:::utility
        TR["toast-renderer.ts"]:::utility
    end
    click LC "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/localize/localize.ts"
    click HASS_HELP "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/tree/master/src/localize/hass/"
    click LANG "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/tree/master/src/localize/languages/"
    click TR "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/renderers/toast-renderer.ts"

    %% View Layer
    subgraph "View Layer" 
        direction TB
        XVM["xiaomi-vacuum-map-card.ts"]:::view
        subgraph "UI Components"
            direction TB
            RLE["rootless-lit-element.ts"]:::view
            DRP["dropdown-menu.ts"]:::view
            DRI["dropdown-icon.ts"]:::view
            IW["icons-wrapper.ts"]:::view
            SI["single-icon.ts"]:::view
            TLE["tile.ts"]:::view
            TW["tiles-wrapper.ts"]:::view
            PS["preset-selector.ts"]:::view
            IC["icon.ts"]:::view
        end
        subgraph "Map Interaction"
            direction TB
            PZI["pinch-zoom/index.ts"]:::view
            PZ["pinch-zoom.ts"]:::view
        end
    end
    click XVM "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/xiaomi-vacuum-map-card.ts"
    click RLE "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/rootless-lit-element.ts"
    click DRP "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/dropdown-menu.ts"
    click DRI "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/dropdown-icon.ts"
    click IW "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/icons-wrapper.ts"
    click SI "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/single-icon.ts"
    click TLE "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/tile.ts"
    click TW "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/tiles-wrapper.ts"
    click PS "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/preset-selector.ts"
    click IC "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/components/icon.ts"
    click PZI "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/pinch-zoom/index.ts"
    click PZ "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/pinch-zoom/pinch-zoom.ts"

    %% Action & Integration Layer
    AHD["Action Handler Directive"]:::integration
    click AHD "https://github.com/piotrmachowski/lovelace-xiaomi-vacuum-map-card/blob/master/src/action-handler-directive.ts"
    HA["Home Assistant Core"]:::external
    HACS["HACS (Loader)"]:::external
    VP["Vacuum Platform Integration"]:::external

    %% Build Pipeline
    subgraph "Build Pipeline"
        RC["rollup.config.js"]:::build
        RCD["rollup.config.dev.js"]:::build
        TS_CFG["tsconfig.json"]:::build
        PKG["package.json"]:::build
    end

    %% Flows
    CI -->|"validate()"| CVP
    CVP -->|"normalized config"| MW
    MW --> ILG
    MW --> TG
    MW --> PG
    ILG -->|"generateIcons()"| XVM
    TG -->|"generateTiles()"| XVM
    PG -->|"loadTemplates()"| PT
    XVM -->|"render()"| RLE
    RLE --> DRP & DRI & IW & SI & TLE & TW & PS & IC
    PZI --> PZ
    XVM --> PZI
    XVM --> AHD
    AHD -->|"dispatchEvent()"| HA
    HA -->|"callService()"| VP
    VP -->|"stateUpdate"| XVM

    RC --> XVM
    RCD --> XVM
    TS_CFG --> XVM
    PKG --> XVM

    HACS -->|"loads resource"| XVM

    %% Styles
    classDef parser fill:#add8e6,stroke:#000,color:#000
    classDef model fill:#90ee90,stroke:#000,color:#000
    classDef view fill:#ffa500,stroke:#000,color:#000
    classDef integration fill:#dda0dd,stroke:#000,color:#000
    classDef build fill:#d3d3d3,stroke:#000,color:#000
    classDef utility fill:#ffffe0,stroke:#000,color:#000
    classDef external fill:#f0f8ff,stroke:#000,color:#000
```
