bahmcloud_store/README_DEVELOPER.md

Bahmcloud Store – Developer Documentation

For contributors and maintainers.

Architecture

Repositories:

1. Installer Add-on (HAOS/Supervised)
2. Core Integration
3. Store Index (store.yaml)

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

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. Fork index repo (with store.yaml)
2. Add entry:

- name: Your Integration Name
  url: https://github.com/your-org/your-repo
  category: Category

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

name: Your Integration Name
description: One-liner for the store
category: Sensors
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