160 lines
4.3 KiB
Markdown
160 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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/...`
|
|
- Initial support is focused on direct install and uninstall
|
|
- 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
|
|
|
|
## Contributing to the Official Store Index
|
|
|
|
Add a repository to the BCS store index in `ha_store`.
|
|
|
|
Example index entry:
|
|
|
|
```yaml
|
|
- name: Example Project
|
|
url: https://your-git-hoster.example/org/repo
|
|
category: Blueprint
|
|
```
|
|
|
|
Recommended repository metadata:
|
|
|
|
```yaml
|
|
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.
|
|
|