bahmcloud_store/README_DEVELOPER.md

Bahmcloud Store – Developer Documentation

For contributors and maintainers.

Architecture

Repositories:

1. Installer Add-on (HAOS/Supervised) https://git.bahmcloud.de/bahmcloud/addons
2. Core Integration https://git.bahmcloud.de/bahmcloud/bahmcloud_store
3. Store Index (store.yaml) https://git.bahmcloud.de/bahmcloud/ha_store

Integration Layout

custom_components/bahmcloud_store/

• init.py: setup, panel registration, schedule background after HA started
• core.py: index merge, enrichment, install/update/uninstall, backups, restore, caching
• providers.py: GitHub/GitLab/Gitea repo info + latest version helpers
• metadata.py: read bcs.yaml / hacs.json / hacs.yaml
• storage.py: persistent storage (installed, custom, repo cache, hacs cache)
• views.py: HTTP API endpoints
• update.py: UpdateEntity implementation
• repairs.py: (optional) Repairs flow for restart
• panel/: UI (panel.js, styles.css, etc.)
• manifest.json

Runtime Model

• RepoItem (merged)
• Installed repos (storage)
• Repo cache (persisted enrichment)
• HACS meta cache (mapping owner/repo → name/description)

Background

• Heavy work only after homeassistant_started
• Refresh: if index unchanged → installed-only refresh + schedule enrichment
• Opening a repo triggers ensure_repo_details() and persists to cache

Providers

• GitHub: API/releases/tags/atom + raw readme
• GitLab: API releases/tags + raw readme
• Gitea: API releases/tags + raw readme
• Custom: API or HTTPS Request to your Git Provider

Metadata

• Prefer bcs.yaml, fallback hacs.json / hacs.yaml
• Populate name/description/category/author/maintainer

HTTP API (excerpt)

Base: /api/bcs

• GET /api/bcs
• POST /api/bcs?action=refresh
• GET /api/bcs/readme?repo_id=...
• GET /api/bcs/versions?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=...
• (optional) POST/DELETE custom_repo

Update Entities

• Unique id bcs:<repo_id>
• Compare installed ref vs latest ref
• Dispatcher signal on refresh/install/update

Storage

• JSON in HA .storage
• async read/write helpers
• repo cache applied on startup

Contributing to BCS Official

1. Add pull request to https://git.bahmcloud.de/bahmcloud/ha_store (with your integration added to) store.yaml)
2. Add entry:

- name: Your Integration Name
  url: https://your-git-hoster.com/your-org/your-repo
  category: Category (actually only "Integrations" are supported)

3. (Recommended) Add bcs.yaml to your repo:

name: Your Integration Name
description: One-liner for the store (optional, store information are also catched from git repository)
category: Integrations (actually only supported)
author: Your Name
maintainer: Your Handle

4. Open PR; validation checks: reachable, has custom_components/<domain>/manifest.json, sensible metadata
5. Merge → appears in BCS Official after refresh

Coding Guidelines

• Async I/O, no blocking event loop
• Respect provider rate limits
• Clean logging around refresh/install/update/restore
• Keep UI responsive; throttle updates

---

Planed Features

• Add Downloads and install for category "Dashboard"
• Add Downloads and install for category "Template"
• Add Downloads and install for category "Theme"
• Add Downloads and install for category "Blueprint"