# 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/...`
- 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:

```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.