<!-- Codex created 2025-12-29_0224 -->
# Architecture v2 (Rust)

## Vue d'ensemble
- Binaire Rust unique par OS (Linux/Windows).
- Modules separes pour MQTT, telemetry, commands, HA discovery.
- Backends OS selectionnes via YAML.

## Diagramme ASCII

[config.yaml] -> [runtime] -> [mqtt client] <-> [broker]
                    |            |-> discovery/status/capabilities
                    |            |-> publish states
                    |            |-> receive commands
                    |
                    +-> [telemetry providers]
                    +-> [commands providers]
                    +-> [ha discovery]
                    +-> [platform backends]

## Structure du projet (reference)
```
pilot-v2/
  Cargo.toml
  src/
    main.rs
    lib.rs
    config/
    mqtt/
    ha/
    telemetry/
    commands/
    platform/
      linux/
      windows/
    runtime/
    security/
```

## Contrat MQTT (stable)
Base topic: `pilot/<device>/...`

### Topics
- `pilot/<device>/availability` : online/offline (LWT recommande)
- `pilot/<device>/status` : JSON (version, os, uptime, last_error, backends)
- `pilot/<device>/capabilities` : JSON (features actives)
- `pilot/<device>/state/<name>` : capteurs et etats systeme
- `pilot/<device>/cmd/<action>/set` : commandes

### QoS / retain
- Discovery: retain=true, qos=1
- States: retain configurable (defaut true), qos=0 ou 1 selon config
- Commands: retain=false, qos=0
- Availability: retain=true (LWT possible), qos=1

### Home Assistant discovery
- Prefix: `homeassistant`
- Discovery payloads conformes HA (device_info, unique_id, state_topic, availability_topic, command_topic).
- Lien discovery -> topics v2 (state/cmd).

## Schema JSON (exemples)
- status:
  - `{ "version": "2.0.0", "os": "linux", "uptime_s": 1234, "last_error": "", "backends": {"power":"logind", "screen":"gnome_busctl"} }`
- capabilities:
  - `{ "telemetry": ["cpu_usage","cpu_temp","memory"], "commands": ["shutdown","reboot","sleep","screen"], "gpu": false }`

## Flux MQTT (Mermaid)
Telemetry:
```mermaid
flowchart LR
  subgraph Agent
    T[Telemetry Providers] --> M[MQTT Client]
  end
  M -->|state/<name>| B[Broker MQTT]
  M -->|status/capabilities| B
  M -->|availability| B
  B -->|Discovery| H[Home Assistant]
```

Commandes:
```mermaid
flowchart LR
  H[Home Assistant] -->|cmd/<action>/set| B[Broker MQTT]
  B -->|cmd/<action>/set| M[MQTT Client]
  M --> C[Command Handlers]
  C --> P[Platform Backend]
  P -->|result/state| M
  M -->|state/<name>| B
```

## Traits internes
- `TelemetryProvider` : read() -> map name->value
- `PowerControl` : shutdown/reboot/sleep/hibernate
- `ScreenControl` : screen_on/screen_off

## Plateformes
- Linux: logind/polkit ou sudoers, gnome busctl ou x11 xset.
- Windows: winapi_session ou external_tool (limite service vs session).
<!-- Codex modified 2025-12-29_0224 -->