Skip to content

Technical: Dashboard Generation

Jump to bottom
ccpk1 edited this page Feb 28, 2026 · 4 revisions

Target audience: Developers and advanced maintainers Covers: Generator contract, view model behavior, overwrite semantics, and diagnostics

Purpose

This page is the technical contract for ChoreOps dashboard generation.

Use it to:

  • Understand create/update/delete behavior
  • Diagnose missing/stale/broken generated dashboards
  • Build custom UI or automation flows that rely on generated entities/views

Generator entry points

Dashboard generation is managed through ChoreOps Options Flow:

  • Manage Dashboard → Create Dashboard
  • Manage Dashboard → Update Dashboard
  • Manage Dashboard → Delete Dashboard

The generator writes/updates Lovelace dashboard definitions via Home Assistant dashboard APIs.

Release execution contract

Dashboard release handling is flow-scoped and deterministic:

  1. Step 1 resolves release mode to one concrete effective_release_ref.
  2. Step 1 prepares release assets (registry, templates, translations, preferences).
  3. Prepared assets are applied to local vendored runtime dashboard paths.
  4. Step 3 executes with the prepared release context (no dynamic re-resolution).

Mode behavior:

  • Explicit release tag: strict pin
  • Latest stable/latest compatible: resolve once, then pin
  • Current installed: use local registry release_version

Technical update workflow (dashboard repo)

Use this workflow for template/registry updates.

  1. Update canonical assets in choreops-dashboards:
    • dashboard_registry.json
    • templates/
    • translations/
    • preferences/
  2. In choreops, mirror assets into vendored runtime:
    • python utils/sync_dashboard_assets.py
  3. Verify parity gate locally:
    • python utils/sync_dashboard_assets.py --check
  4. Run integration validation gates before merge:
    • ./utils/quick_lint.sh --fix
    • targeted dashboard tests

Authoritative references:

Generated view model contract

Depending on selected options, the generator can produce:

  • Assignee views (for selected assignees/profiles)
  • Optional admin views

Admin view path conventions commonly include:

  • Shared admin path: admin
  • Per-assignee admin path: admin-<assignee-slug>

Paths may vary when Home Assistant resolves collisions.

Overwrite and update semantics

Generator-managed content is authoritative for generated dashboards.

  • Update Dashboard may replace generated view/card sections
  • Manual edits inside generated sections are not guaranteed to persist
  • Custom long-lived modifications are safer in separately managed custom dashboards

This is the expected tradeoff for deterministic regeneration.

Dependency contract

Generated dashboards rely on frontend cards documented in the canonical prerequisites list:

Dependency handling is template-driven:

  • missing recommended dependencies warn and allow continue,
  • each missing dependency row is prefixed with ❌,
  • missing required dependencies trigger a confirmation step before continuing.

Translation sensor contract (localization)

Generated dashboard templates use translation sensors to render localized terms across languages.

  • Dashboard helper entities provide a translation_sensor reference
  • Templates resolve localized strings from the referenced sensor (for example from translation attributes)
  • This allows one generated dashboard model to adapt to different user language settings

If translation-sensor references are missing or stale, labels can fall back to placeholder/error text.

Entity/data contract

Generated cards consume runtime entities and attributes created by ChoreOps.

Primary references:

Do not hardcode assumptions about entity IDs. Resolve from Home Assistant runtime/registry.

Admin selector behavior

Shared admin layouts may depend on a selector entity for assignee context switching.

If admin switching appears broken:

  1. Verify selector entity exists and is enabled
  2. Verify selected assignees still exist and are active
  3. Re-run Update Dashboard

Failure modes and diagnostics

Preflight: confirm integration operations

Before troubleshooting dashboard rendering/layout behavior, verify core ChoreOps operations are healthy:

  1. Confirm core entities are present and updating in Developer Tools
  2. Confirm basic action flows (for example claim/redeem/approve paths) operate correctly
  3. Confirm related helper entities exist for the affected assignee/profile

If these core checks fail, troubleshoot integration state first using:

Generation succeeds but UI shows card errors

Likely missing frontend dependencies. Install cards and reload dashboard.

Expected views are missing

Likely mismatch between selected assignees/admin layout and current options. Re-run update with corrected selections.

Update appears stale

Possible path/name collision or browser cache masking.

  • Check dashboard list and paths in Home Assistant
  • Hard refresh browser
  • Re-run update and inspect logs

Historical duplicate dashboard records

Generator rework includes dedupe/idempotent handling for historical duplicate paths. If behavior still looks inconsistent, run update/delete/create from the generator and re-check dashboard registry state.

Implementation context

Implementation details are tracked in the in-repo dashboard initiative documents.

Related docs

Last Updated: February 2026

ChoreOps

🚀 Getting Started

⚙️ Configuration

🔧 Services

💡 Tips & Tricks

📖 Advanced Topics

📚 Technical Reference

👩‍🔧 Troubleshooting

Clone this wiki locally