116 lines
3.4 KiB
Markdown
116 lines
3.4 KiB
Markdown
# 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:
|
||
```yaml
|
||
- 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:
|
||
```yaml
|
||
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"
|
||
-
|
||
|
||
|