{"id":50417841,"url":"https://github.com/antoinevalentinha/arsenal","last_synced_at":"2026-05-31T07:01:59.559Z","repository":{"id":360179508,"uuid":"1247272240","full_name":"antoinevalentinHA/arsenal","owner":"antoinevalentinHA","description":"Home Assistant as a governed system","archived":false,"fork":false,"pushed_at":"2026-05-25T10:16:41.000Z","size":30229,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T11:27:27.011Z","etag":null,"topics":["architecture","automation","contract-driven","home-assistant","home-automation","mqtt","observability","state-machine","system-design","validation","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antoinevalentinHA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T05:17:35.000Z","updated_at":"2026-05-25T10:16:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/antoinevalentinHA/arsenal","commit_stats":null,"previous_names":["antoinevalentinha/arsenal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/antoinevalentinHA/arsenal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinevalentinHA%2Farsenal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinevalentinHA%2Farsenal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinevalentinHA%2Farsenal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinevalentinHA%2Farsenal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antoinevalentinHA","download_url":"https://codeload.github.com/antoinevalentinHA/arsenal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinevalentinHA%2Farsenal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33722156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","automation","contract-driven","home-assistant","home-automation","mqtt","observability","state-machine","system-design","validation","yaml"],"created_at":"2026-05-31T07:01:58.206Z","updated_at":"2026-05-31T07:01:59.553Z","avatar_url":"https://github.com/antoinevalentinHA.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arsenal\n\n\u003e Home Assistant as a governed system.\n\nArsenal est une configuration Home Assistant construite comme un **logiciel long terme** — avec une architecture en couches, des contrats explicites, et une séparation stricte entre ce qui décide et ce qui agit.\n\nCe n'est pas un dump de configuration. Ce n'est pas un smart home setup à copier.\nC'est une **référence d'architecture** pour qui veut traiter HA sérieusement.\n\n---\n\n## Le problème\n\nHome Assistant est remarquablement puissant. Il est aussi très facile à laisser dériver vers un système difficilement maintenable.\n\nLa trajectoire naturelle d'une installation HA non gouvernée :\n\n- Des automatisations qui déclenchent d'autres automatisations\n- Une logique métier dispersée entre l'UI, les scripts, les automations et les helpers\n- Des dashboards qui *font des choses* au lieu de les rendre visibles\n- Des entités dont personne ne sait plus si elles sont encore utilisées\n- Un `configuration.yaml` qui a grandi organiquement depuis 2019\n- Une dette système invisible jusqu'à la rupture opérationnelle\n\nArsenal existe pour répondre à une question simple :\n\n\u003e Comment construire une installation HA qui reste maintenable, observable et cohérente sur le long terme ?\n\n---\n\n## Le modèle mental\n\nArsenal repose sur trois principes qui ne se négocient pas.\n\n**1. Le backend décide. L'UI observe. Jamais l'inverse.**\n\nAucune logique dans les dashboards. Les cartes affichent des états — elles ne les calculent pas. Les décisions sont prises en amont, dans des entités dédiées. L'UI est un miroir, pas un moteur.\n\n**2. Contrat avant YAML.**\n\nChaque domaine fonctionnel a un contrat écrit avant d'avoir du code. Ce contrat définit les entités impliquées, leurs rôles, leurs transitions d'état valides, et les invariants que le système doit respecter. Le YAML implémente le contrat — pas l'inverse.\n\n**3. L'exposition est une décision, pas un accident.**\n\nCe qui est visible depuis l'extérieur (API, MQTT, notifications) est explicitement gouverné. Ce qui est interne reste interne. La séparation n'est pas une convention de nommage — c'est une contrainte architecturale.\n\n---\n\n## L'architecture\n\nArsenal est organisé en trois couches :\n\n```\n┌─────────────────────────────────────────────┐\n│  Capteurs physiques · Intégrations · MQTT   │  PERCEPTION\n└───────────────────────┬─────────────────────┘\n                        │ états bruts\n                        ▼\n┌─────────────────────────────────────────────┐\n│  Template sensors · Helpers · Admissibilité │  DECISION\n└───────────────────────┬─────────────────────┘\n                        │ états de décision\n                        ▼\n┌─────────────────────────────────────────────┐\n│  Automatisations · Scripts souverains       │  EXECUTION\n└───────────────────────┬─────────────────────┘\n                        │ commandes\n                        ▼\n                    Hardware\n```\n\nL'UI n'apparaît pas dans ce schéma. Elle observe — elle ne participe pas au flux.\n\n**Perception** — Ce que le système observe. Capteurs physiques, états d'intégration, données MQTT, métriques NAS. Aucune logique ici — seulement de la mesure.\n\n**Decision** — Ce que le système conclut. Template sensors, helpers d'état, scripts souverains. C'est ici que vivent les règles métier : admissibilité, besoin brut, contraintes, verrouillages. Le résultat est toujours un état lisible, pas une action directe.\n\n**Execution** — Ce que le système applique. Automatisations déclenchées par des états de décision, scripts d'action, commandes physiques. Cette couche ne contient pas de logique — elle réagit à des états.\n\nCette séparation n'est pas théorique. Elle est visible dans l'arborescence et vérifiable par les scripts d'audit.\n\n---\n\n## Structure du repo\n\n```\n00_documentation_arsenal/   Contrats, changelogs, architecture, doctrine\n01_customize/               Personnalisation des entités\n02_groups/                  Groupes Home Assistant\n03_input_numbers/           Helpers numériques — seuils et paramètres métier\n04_input_texts/             Helpers texte — mémoire des décisions\n05_input_booleans/          Helpers booléens — activation, modes, verrous\n06_input_selects/           Helpers sélection — modes et états énumérés\n07_input_datetimes/         Helpers date/heure — planification métier\n08_timers/                  Timers — temporisations explicites\n09_counters/                Compteurs — mémoires incrémentales\n10_scripts/                 Scripts souverains — actions atomiques\n11_automations/             Réactions à des états — jamais de logique\n12_template_sensors/        Capteurs de décision — cerveau du système\n13_sensor_platforms/        Capteurs par plateformes Home Assistant\n14_mqtt_sensors/            Surface MQTT — perception externe\n15_mqtt_binary_sensors/     Capteurs binaires MQTT — perception externe\n16_template_alarm_panels/   Panneau alarme contractualisé\n17_zones/                   Zones métier\n18_lovelace/                UI — rendu uniquement\n19_button_card_templates/   Palette de composants UI\nscripts/                    Outillage — audit, validation, CI\nutility_meter.yaml          Compteurs d’énergie\nrecorder.yaml               Politique de persistance\nlogbook.yaml                Politique du journal\nlogger.yaml                 Politique de logs\n```\n\nLes numéros de préfixe ne sont pas décoratifs. Ils expriment l'ordre de chargement et la couche architecturale.\n\n---\n\n## Les patterns clés\n\n**Sovereign script** — Un script qui encapsule une action atomique avec ses préconditions, son ACK et son logging. Aucune automatisation ne fait une action directement : elle appelle un script souverain.\n\n**Helper memory** — Les helpers ne stockent pas que des valeurs — ils stockent des décisions. `input_text.alarme_raison` n'est pas un champ texte libre, c'est le motif formel de la dernière décision de la centrale d'alarme.\n\n**Métier truth sensor** — Un `template sensor` qui synthétise l'état réel d'un domaine en un seul état lisible. L'UI lit ce capteur. Les automatisations se déclenchent sur ce capteur. Les diagnostics interrogent ce capteur.\n\n**Transactional ACK** — Les commandes critiques (alarme, ECS, VMC) suivent un cycle request → applied/rejected/timeout avec `request_id`. L'état n'est jamais supposé — il est confirmé.\n\n**Reconciliation engine** — Après un redémarrage HA, les domaines critiques se reconcilent avec l'état réel du hardware avant d'accepter de nouvelles commandes.\n\n---\n\n## Exemple — le domaine VMC\n\nUn domaine Arsenal complet, de la perception à l'exécution.\n\n**Perception**\n`sensor.vmc_etat_reel` — état retourné par le relais Sonoff Dual R3 via MQTT.\n`sensor.co2_salon`, `sensor.humidite_sdb` — mesures environnementales.\n\n**Decision**\n`sensor.vmc_besoin_brut` — template sensor : y a-t-il un besoin de ventilation ?\n`sensor.vmc_admissibilite` — le contexte permet-il d'agir ? (heure, présence, contraintes)\n`input_text.vmc_decision` — état de décision final : `on_demande` / `off_demande` / `verrouille`\n\n**Execution**\n`automation.vmc_application_decision` — se déclenche sur changement de `vmc_decision`.\n`script.vmc_allumage` / `script.vmc_extinction` — scripts souverains avec ACK MQTT.\n\n**Diagnostic**\n`sensor.vmc_coherence` — détecte les incohérences entre décision et état réel.\nUn watchdog se déclenche si l'état réel diverge de la décision pendant plus de 30 secondes.\n\nLe même modèle architectural se retrouve dans chaque domaine : alarme, ECS, déhumidificateur, chauffage.\n\n---\n\n## Ce que contient `00_documentation_arsenal`\n\nLa documentation n'est pas un supplément — elle est normative.\n\n- **Contrats** — Spécifications formelles de chaque domaine. Un contrat dit ce que le système *doit* faire, pas comment il le fait. Le YAML implémente le contrat.\n- **Changelogs** — Chaque version d'Arsenal a un changelog structuré. Les décisions architecturales y sont documentées, pas seulement les changements.\n- **Architecture** — Schémas d'infrastructure, topologie MQTT, organisation des couches.\n- **Outils externes** — Contrats et documentation des composants satellites : bridge boiler Pi, pipelines NAS, proxies BLE.\n\n---\n\n## Outillage\n\n```\nscripts/security/audit_publication_git.py   Audit sécurité pré-publication\nscripts/arsenal_contracts/                  Validation des contrats par domaine\n```\n\nL'audit de publication est bloquant. Zéro CRITICAL = condition nécessaire pour publier. Les WARNING documentaires sont qualifiés et traçables (`[scope=doc]`).\n\nLes scripts de validation de contrats vérifient la cohérence des entités déclarées dans les contrats avec leur implémentation réelle dans le YAML.\n\n---\n\n## Ce qu'Arsenal n'est pas\n\n**Pas une installation à copier.** Les entités, les IPs, les topics MQTT et les noms de devices sont spécifiques à une installation. Ce qui est réutilisable, ce sont les patterns, les invariants et la doctrine.\n\n**Pas une vitrine.** Arsenal n'est pas optimisé pour être impressionnant en screenshot. Il est optimisé pour rester maintenable, observable et gouvernable plusieurs années après sa construction.\n\n**Pas une documentation Home Assistant.** La documentation officielle reste la référence pour les intégrations, Lovelace et les comportements natifs. Arsenal se concentre sur l'architecture du système : séparation décision/exécution, gouvernance documentaire, robustesse runtime et contractualisation.\n\n---\n\n## Versions\n\nArsenal n'a pas évolué comme une simple configuration Home Assistant.\nChaque période correspond à une mutation d'architecture, de gouvernance ou de modèle d'exécution.\n\n| Ère       | Période                | Inflexion dominante                                                                                                                                                                          |\n|-----------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Émergence | 2025-08 → 2025-10      | Atomisation progressive de l'arborescence, normalisation des includes, premières conventions UI et gouvernance des entités.                                                                  |\n| v1 → v5   | 2025-10 → 2026-01      | Construction des premiers moteurs décisionnels : chauffage centralisé, ouvertures temporisées, doctrine `systeme_stable`, pipelines reboot-safe.                                             |\n| v6 → v8   | 2026-01                | Fondation du modèle Arsenal moderne : applicateurs idempotents, séparation décision/exécution, observabilité thermique structurée, gouvernance UI et temporelle.                             |\n| v9        | 2026-02                | Industrialisation massive : architecture UI à trois niveaux, templates factorisés, corpus contractuel versionné, réconciliation Zigbee et pipelines diagnostiques.                           |\n| v10       | 2026-03                | Canonisation des temporalités et des ouvertures : qualification métier, anti-zombie, orchestration déterministe, moteurs de réconciliation robustes.                                         |\n| v11       | 2026-03 → 2026-04      | Passage transactionnel local : Boiler Bridge, ACK corrélés, souveraineté Viessmann locale, pipelines ECS/chauffage transactionnels et retry externe.                                         |\n| v12       | 2026-04                | Durcissement architectural : admissibility locks, invariants système, pipelines météo structurés, VMC dual-relais, transactionnel SwitchBot/guard.                                           |\n| v13       | 2026-04 → 2026-05      | Extension satellite : supervision NAS Imprimerie, Bluetti, UPS, snapshots santé/sommeil, taxonomie intégrité paramètres, observabilité multi-domaines.                                       |\n| v14       | 2026-05                | Formalisation totale de la gouvernance : arborescence numérique canonique `00_* → 19_*`, contrats opposables par domaine, doctrine “documentation avant implémentation”.                     |\n| v15       | 2026-05 → aujourd'hui  | Consolidation runtime et gouvernance documentaire : deadlines persistantes, robustesse post-restart, diagnostics UI structurés, outillage NAS Arsenal, validation contractuelle automatisée. |\n\nLe détail complet est disponible dans [`00_documentation_arsenal/changelog/`](00_documentation_arsenal/changelog/).\n\n---\n\n## Licence\n\nMIT — les patterns sont libres de réutilisation.\n\nArsenal est publié pour partager une façon d'architecturer Home Assistant, pas une maison.\nLe but n'est pas d'être reproduit. Le but est d'être étudié.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantoinevalentinha%2Farsenal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantoinevalentinha%2Farsenal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantoinevalentinha%2Farsenal/lists"}