bahmcloud_store/README_DEVELOPER.md

Bahmcloud Store - Developer Documentation

For contributors and maintainers.

Project Scope

Bahmcloud Store is evolving from an integration-only store into a broader Home Assistant git-based content store.

Currently supported install categories:

• Integrations
• Blueprints

Planned categories:

• Templates
• Lovelace / dashboard designs
• Additional content types with category-specific install logic

Repository Layout

Repositories related to the project:

1. Installer add-on: https://git.bahmcloud.de/bahmcloud/addons
2. Core integration: https://git.bahmcloud.de/bahmcloud/bahmcloud_store
3. Store index: https://git.bahmcloud.de/bahmcloud/ha_store

Integration Layout

custom_components/bahmcloud_store/

• __init__.py: setup, panel registration, delayed startup refresh, periodic refresh
• core.py: index merge, repo enrichment, install/update/uninstall, backup/restore, category-aware install groundwork
• providers.py: provider detection, latest version lookup, release notes, README fetching
• metadata.py: reads bcs.yaml, hacs.json, and hacs.yaml
• storage.py: persistent storage for installed repos, settings, caches
• views.py: HTTP API
• update.py: Home Assistant update entities
• repairs.py: restart-required repair flow
• panel/: active frontend panel
• manifest.json

Runtime Model

• RepoItem: merged repository model used by the UI and backend
• Installed repositories: persisted in Home Assistant storage
• Settings: persistent UI and behavior settings such as HACS enablement and pinned repositories
• Repo cache: provider and metadata enrichment cache
• HACS cache: display metadata cache for HACS integration repositories

Metadata

Metadata priority:

1. bcs.yaml
2. hacs.yaml
3. hacs.json

Common fields:

name: Example Project
description: Short description
category: Integrations
author: Example Author
maintainer: Example Maintainer

Category currently matters operationally:

• Integrations -> install from custom_components/...
• Blueprint / Blueprints -> install from blueprints/...

Supported Install Categories

Integrations

• Expected source layout: custom_components/<domain>/manifest.json
• Install target: /config/custom_components/<domain>
• Supports backup, restore, update entities, and restart-required flow

Blueprints

• Expected source layout: blueprints/...
• Install target: /config/blueprints/...
• Supports install, update, uninstall, content backup, and content restore
• Restores and uninstalls are path-based and operate on the recorded installed blueprint files
• Category-aware groundwork is in place so future content types can use their own install strategies

HTTP API

Base path: /api/bcs

• GET /api/bcs
• POST /api/bcs?action=refresh
• GET /api/bcs/settings
• POST /api/bcs/settings
• GET /api/bcs/readme?repo_id=...
• GET /api/bcs/release_notes?repo_id=...&ref=...
• GET /api/bcs/versions?repo_id=...
• GET /api/bcs/repo?repo_id=...
• POST /api/bcs/install?repo_id=...&version=...
• POST /api/bcs/update?repo_id=...&version=...
• POST /api/bcs/uninstall?repo_id=...
• GET /api/bcs/backups?repo_id=...
• POST /api/bcs/restore?repo_id=...&backup_id=...
• POST /api/bcs/restart
• DELETE /api/bcs/custom_repo?id=...

Current UI Features

• Search, source filter, category filter, state filter, sorting
• HACS integration source toggle
• Pinned repositories
• README rendering
• Release notes rendering
• Version selection
• Backup restore UI for integrations and blueprints

Contributing to the Official Store Index

Add a repository to the BCS store index in ha_store.

Example index entry:

- name: Example Project
  url: https://your-git-hoster.example/org/repo
  category: Blueprint

Recommended repository metadata:

name: Example Project
description: One-line description
category: Blueprint
author: Example Author
maintainer: Example Maintainer

Validation should match the category:

• Integrations: verify custom_components/<domain>/manifest.json
• Blueprints: verify blueprints/...

Design Direction

The long-term architecture should remain category-aware:

• category -> validation strategy
• category -> install target
• category -> backup / restore behavior
• category -> UI affordances

This is especially important before Templates and Lovelace support are added, because those should stay compatible with established HACS expectations where possible.