# 📐 Architecture MQTT pour IPWatch

## 1. Vue d'ensemble

L'architecture MQTT d'IPWatch implémente un système de contrôle à distance des équipements réseau basé sur le protocole MQTT (Message Queuing Telemetry Transport).

### 1.1 Objectifs

- **Contrôle centralisé** : Gérer shutdown/reboot depuis l'interface IPWatch
- **Légèreté** : Protocol MQTT léger et performant
- **Fiabilité** : QoS MQTT pour garantir la livraison des messages
- **Scalabilité** : Support de centaines d'équipements simultanément
- **Intégration** : Compatible Home Assistant et autres systèmes domotiques

### 1.2 Composants

```
┌─────────────────────────────────────────────────────────────────┐
│                        IPWatch Ecosystem                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────┐         ┌──────────────┐                    │
│  │ Web Interface │────────►│   Backend    │                    │
│  │  (Vue.js)     │  HTTP   │  (FastAPI)   │                    │
│  └───────────────┘  API    └──────┬───────┘                    │
│                                    │                             │
│                            paho-mqtt (publish)                   │
│                                    │                             │
│                                    ▼                             │
│  ┌─────────────────────────────────────────────────┐            │
│  │           MQTT Broker (Mosquitto)               │            │
│  │                                                  │            │
│  │  Topics:                                        │            │
│  │  • ipwatch/device/{IP}/command                 │            │
│  │  • ipwatch/device/{IP}/status                  │            │
│  │  • ipwatch/device/{IP}/availability            │            │
│  └─────────────────┬───────────────────────────────┘            │
│                    │ MQTT (subscribe)                            │
│                    │                                             │
│         ┌──────────┼──────────┬──────────┬──────────┐          │
│         ▼          ▼          ▼          ▼          ▼          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│  │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │  ...    │ │ Agent N │ │
│  │ 10.0.0.1│ │ 10.0.0.2│ │ 10.0.0.3│ │         │ │ 10.0.0.N│ │
│  │         │ │         │ │         │ │         │ │         │ │
│  │ Python  │ │ Python  │ │ Python  │ │ Python  │ │ Python  │ │
│  │ systemd │ │ systemd │ │ systemd │ │ systemd │ │ systemd │ │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## 2. Topics MQTT

### 2.1 Hiérarchie des Topics

```
ipwatch/
└── device/
    └── {IP_ADDRESS}/
        ├── command         # Commandes envoyées par IPWatch
        ├── status          # Statut publié par l'agent
        ├── availability    # Disponibilité de l'agent (online/offline)
        └── response        # Réponses/acquittements de l'agent
```

### 2.2 Détail des Topics

#### `ipwatch/device/{IP}/command`
- **Direction** : IPWatch Backend → Agent
- **QoS** : 1 (at least once)
- **Retain** : false
- **Payload** : JSON
- **Commandes supportées** :
  - `shutdown` : Arrêt de la machine
  - `reboot` : Redémarrage de la machine
  - `status` : Demande de statut

**Exemple** :
```json
{
  "command": "shutdown",
  "timestamp": "2025-12-23T10:30:00Z"
}
```

#### `ipwatch/device/{IP}/status`
- **Direction** : Agent → IPWatch Backend
- **QoS** : 1
- **Retain** : false
- **Payload** : JSON avec métriques système

**Exemple** :
```json
{
  "hostname": "server-01",
  "ip": "10.0.0.100",
  "platform": "Linux",
  "platform_version": "5.15.0-91-generic",
  "uptime": 86400,
  "cpu_percent": 45.2,
  "memory_percent": 62.5,
  "disk_percent": 78.3,
  "timestamp": "2025-12-23T10:30:00Z"
}
```

#### `ipwatch/device/{IP}/availability`
- **Direction** : Agent → Tous
- **QoS** : 1
- **Retain** : true (important!)
- **Payload** : Texte simple
- **Valeurs** : `online` | `offline`

#### `ipwatch/device/{IP}/response`
- **Direction** : Agent → IPWatch Backend
- **QoS** : 1
- **Retain** : false
- **Payload** : JSON avec résultat de la commande

**Exemple** :
```json
{
  "success": true,
  "message": "Shutdown en cours...",
  "timestamp": "2025-12-23T10:30:05Z"
}
```

## 3. Flux de Communication

### 3.1 Shutdown/Reboot

```mermaid
sequenceDiagram
    participant UI as IPWatch UI
    participant BE as Backend
    participant BR as MQTT Broker
    participant AG as Agent (10.0.0.100)

    UI->>BE: POST /api/tracking/shutdown/10.0.0.100
    BE->>BR: PUBLISH ipwatch/device/10.0.0.100/command
    Note over BR: QoS 1
    BR->>AG: {"command": "shutdown"}
    AG->>BR: PUBLISH ipwatch/device/10.0.0.100/response
    Note over AG: {"success": true, "message": "Shutdown en cours..."}
    AG->>BR: PUBLISH ipwatch/device/10.0.0.100/availability
    Note over AG: "offline"
    AG->>AG: sudo shutdown -h now
    BE-->>UI: 200 OK {"message": "Commande envoyée"}
```

### 3.2 Wake-on-LAN

```mermaid
sequenceDiagram
    participant UI as IPWatch UI
    participant BE as Backend
    participant AG as Agent (offline)

    UI->>BE: POST /api/tracking/wol/10.0.0.100
    BE->>BE: send_magic_packet(MAC)
    Note over BE: Broadcast UDP
    BE-->>UI: 200 OK
    Note over AG: Machine démarre
    AG->>AG: Agent systemd démarre
    AG->>BR: CONNECT
    AG->>BR: PUBLISH availability "online"
    AG->>BR: PUBLISH status {...}
```

### 3.3 Monitoring périodique

```mermaid
sequenceDiagram
    participant AG as Agent
    participant BR as MQTT Broker
    participant HA as Home Assistant

    loop Chaque 30 secondes
        AG->>BR: PUBLISH ipwatch/device/10.0.0.100/status
        Note over AG: CPU, RAM, Disk, Uptime
        BR->>HA: Forward status
        Note over HA: Update sensors
    end
```

## 4. Gestion des Erreurs

### 4.1 Agent déconnecté

**Problème** : L'agent perd la connexion MQTT

**Solution** :
- **Last Will Testament** : Message `offline` publié automatiquement sur `availability`
- **Reconnexion automatique** : L'agent tente de se reconnecter (retry avec backoff)
- **QoS 1** : Garantit la livraison du message d'offline

### 4.2 Commande non livrée

**Problème** : La commande n'atteint pas l'agent

**Solution** :
- **QoS 1** : Le broker MQTT garantit au moins une livraison
- **Timeout** : Le backend attend 5 secondes puis retourne une erreur
- **Retry** : L'utilisateur peut retenter l'opération

### 4.3 Agent en erreur

**Problème** : L'agent reçoit la commande mais ne peut l'exécuter

**Solution** :
- **Message de réponse** : L'agent publie sur `response` avec `success: false`
- **Logging** : Logs détaillés dans journalctl
- **Notification** : L'UI affiche l'erreur à l'utilisateur

## 5. Sécurité

### 5.1 Authentification

```
┌──────────────────────┐
│   MQTT Broker        │
│  (Mosquitto)         │
│                      │
│  password_file:      │
│  /etc/mosquitto/passwd│
│                      │
│  Users:              │
│  • ipwatch (backend) │
│  • agent (clients)   │
└──────────────────────┘
```

**Configuration** :
```bash
# Créer les utilisateurs
mosquitto_passwd -c /etc/mosquitto/passwd ipwatch
mosquitto_passwd /etc/mosquitto/passwd agent

# Dans mosquitto.conf
allow_anonymous false
password_file /etc/mosquitto/passwd
```

### 5.2 Chiffrement TLS/SSL

```
listener 8883
cafile /etc/mosquitto/ca.crt
certfile /etc/mosquitto/server.crt
keyfile /etc/mosquitto/server.key
require_certificate false
```

### 5.3 ACL (Access Control List)

```
# /etc/mosquitto/acl
# Backend peut publier sur command
user ipwatch
topic write ipwatch/device/+/command

# Agents peuvent publier sur status/response/availability
user agent
topic write ipwatch/device/+/status
topic write ipwatch/device/+/response
topic write ipwatch/device/+/availability
topic read ipwatch/device/+/command
```

## 6. Performance et Scalabilité

### 6.1 Dimensionnement

| Métrique | Valeur | Notes |
|----------|--------|-------|
| Agents max | 500 | Limité par le broker |
| Messages/sec | 1000 | Dépend du hardware |
| Latence | <100ms | Sur réseau local |
| Bande passante | ~10 KB/s par agent | Pour statut 30s |

### 6.2 Optimisations

**Payload compression** :
- JSON minifié (pas d'indentation)
- Champs courts
- Pas de données redondantes

**Keep-alive** :
- 60 secondes (défaut)
- Réduit le trafic réseau

**QoS adaptatif** :
- QoS 1 pour commandes critiques
- QoS 0 pour statut non-critique

## 7. Compatibilité Home Assistant

### 7.1 MQTT Discovery

L'agent publie automatiquement sa configuration pour Home Assistant :

```json
{
  "name": "Server 01",
  "unique_id": "ipwatch_10_0_0_100",
  "state_topic": "ipwatch/device/10.0.0.100/status",
  "availability_topic": "ipwatch/device/10.0.0.100/availability",
  "json_attributes_topic": "ipwatch/device/10.0.0.100/status",
  "device": {
    "identifiers": ["ipwatch_10_0_0_100"],
    "name": "Server 01",
    "model": "IPWatch MQTT Agent",
    "manufacturer": "IPWatch"
  }
}
```

**Topic Discovery** :
```
homeassistant/sensor/ipwatch_10_0_0_100/config
```

### 7.2 Entités créées

Home Assistant crée automatiquement :
- **Sensor** : CPU, RAM, Disk, Uptime
- **Binary Sensor** : Availability (online/offline)
- **Button** : Shutdown, Reboot

## 8. Monitoring et Logs

### 8.1 Logs Agent

```bash
# Logs en temps réel
sudo journalctl -u ipwatch-mqtt-agent -f

# Logs des dernières 24h
sudo journalctl -u ipwatch-mqtt-agent --since "24 hours ago"

# Recherche d'erreurs
sudo journalctl -u ipwatch-mqtt-agent -p err
```

### 8.2 Logs Broker

```bash
# Logs Mosquitto
sudo journalctl -u mosquitto -f

# Activer le debug dans mosquitto.conf
log_type all
log_dest /var/log/mosquitto/mosquitto.log
```

### 8.3 Métriques

**Collecte via MQTT** :
- Nombre de clients connectés
- Messages publiés/reçus
- Latence des messages

**Grafana + Prometheus** (optionnel) :
- Dashboard pour visualiser les métriques
- Alertes sur déconnexions

## 9. Diagrammes Détaillés

### 9.1 État de l'Agent

```
┌─────────┐
│  Start  │
└────┬────┘
     │
     ▼
┌─────────────────┐
│ Load Config     │
└────┬────────────┘
     │
     ▼
┌─────────────────┐
│ Connect MQTT    │──┐
│ Broker          │  │
└────┬────────────┘  │
     │               │ Retry
     │ Success       │ on error
     ▼               │
┌─────────────────┐  │
│ Subscribe to    │  │
│ command topic   │  │
└────┬────────────┘  │
     │               │
     ▼               │
┌─────────────────┐  │
│ Publish         │◄─┘
│ availability    │
│ "online"        │
└────┬────────────┘
     │
     ▼
┌─────────────────┐
│  Main Loop      │
│ • Listen MQTT   │
│ • Publish status│
│   every 30s     │
└────┬────────────┘
     │
     │ Receive shutdown
     ▼
┌─────────────────┐
│ Publish         │
│ "offline"       │
└────┬────────────┘
     │
     ▼
┌─────────────────┐
│ Execute         │
│ shutdown        │
└─────────────────┘
```

## 10. Références

- **MQTT v3.1.1 Specification** : http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
- **Mosquitto Documentation** : https://mosquitto.org/documentation/
- **Paho MQTT Python** : https://github.com/eclipse/paho.mqtt.python
- **Home Assistant MQTT Discovery** : https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery

## 11. TODO / Améliorations Futures

- [ ] Support SSL/TLS par défaut
- [ ] Compression des payloads (gzip)
- [ ] Authentification par certificat client
- [ ] Métriques Prometheus
- [ ] Dashboard Grafana
- [ ] Support MQTT v5
- [ ] Broadcast pour commandes multi-équipements
- [ ] Planification de shutdown/reboot (cron-like)