# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

> **Langue** : réponds toujours en français.

---

## Skills et outils à utiliser

Toujours utiliser les skills appropriés avant d'agir :

- **brainstorming** — avant toute création de feature, composant ou choix d'architecture
- **writing-plans / executing-plans** — pour toute tâche multi-étapes, planifier avant de coder
- **test-driven-development** — avant d'écrire le code d'implémentation
- **systematic-debugging** — avant de proposer un fix sur un bug ou test qui échoue
- **WebSearch** — rechercher la doc, les crates Rust, les packages Go, les conventions
- **verification-before-completion** — vérifier que ça fonctionne réellement avant de déclarer terminé
- utiliser rtk pour reduire la consommation de token
---

## Vue d'ensemble du projet

**Nanometrics** — système client-serveur de surveillance matérielle (CPU, RAM, disque) avec empreinte quasi nulle sur les machines Debian.

Trois composants :
- **Agent Rust** (`agent/`) — collecte les métriques, envoie via UDP et/ou MQTT
- **Serveur Go** (`server/`) — reçoit les données, expose `/metrics` Prometheus + API REST + WebSocket
- **Dashboard web** (`dashboard/`) — UI servi par Nginx dans Docker, temps réel via WebSocket

Un `README.md` doit être écrit à la racine : installation de l'agent et du serveur, liste des features.

## Métriques collectées

Métriques actuelles : `hostname`, `ip`, `memory_free`, `memory_used`, `hdd_total`, `hdd_free`, `hdd_used`, `cpu_percent`, `status` (online/offline), `uptime`.

L'agent a une **architecture modulaire** : chaque métrique est un module indépendant activable/désactivable via config. Ajouter une métrique = ajouter un module sans toucher au cœur.

## Commandes de build

```bash
# Agent Rust
rtk cargo build --release --manifest-path agent/Cargo.toml
rtk cargo test --manifest-path agent/Cargo.toml
rtk cargo clippy --manifest-path agent/Cargo.toml

# Serveur Go
rtk go test ./server/...
```

## Agent Rust — contraintes non négociables

- **Pas de runtime async** (pas de Tokio). Boucle mono-thread avec `std::thread::sleep` pour les fréquences différenciées (CPU 2s, réseau/uptime 10s, disque 60s).
- **sysinfo avec `default-features = false`** — empêche les threads de fond qui gonflent la RAM.
- **Profil release** : `strip = true`, `opt-level = "z"`, `lto = true`.
- **Config via `config.toml`** (serde) — paramètres serveur, métriques activées, protocoles. Rien de codé en dur.
- **Deux protocoles supportables simultanément** :
  - `UDP` — fire-and-forget JSON vers `server_ip:server_port`
  - `MQTT` — bidirectionnel vers broker `mqtt_host:mqtt_port` (défaut 10.0.0.3:1883, sans auth)
- **Échange de config au démarrage** : à la connexion, l'agent envoie un message "birth" et récupère sa config depuis le serveur (push/pull bidirectionnel). Le serveur peut envoyer une nouvelle config à l'agent à tout moment.
- **Architecture future** : prévoir un canal de réception de commandes (reboot, shutdown, screen off, update, upgrade, shell cmd…) sans refonte du cœur.

### MQTT — options de l'agent

- **Auto-discovery** : publication du topic de découverte compatible Home Assistant
- **Birth message** : publié à la connexion sur `{topic_base}/{hostname}/status` = `online`
- **Last Will message** : configuré au connect, publié automatiquement par le broker si l'agent disparaît = `offline`
- **Topic base** configurable (défaut : `nanometrics/agents`)

## Serveur Go — contraintes non négociables

- Déployé dans **Docker** — `docker-compose.yml` fourni avec Nginx pour le dashboard.
- Goroutine par datagramme UDP reçu pour la désérialisation JSON.
- Écoute MQTT en parallèle (subscribe sur `{topic_base}/#`).
- Métriques exposées via `github.com/prometheus/client_golang` (Gauges) sur `/metrics`.
- **API REST** — endpoints pour le dashboard : agents, métriques, historique, config agents, icônes.
- **WebSocket** — push temps réel vers le dashboard (mise à jour des métriques et changements de statut).
- **SQLite** — persistance des métriques historiques avec rétention configurable.
- **Config agent** : le serveur stocke la config de chaque agent (métriques actives, protocoles, options MQTT). Envoyée à l'agent au birth et pushée si modifiée depuis le dashboard.

## Déploiement systemd (agent)

Le fichier `.service` doit utiliser :
- `DynamicUser=yes` — utilisateur éphémère, `ProtectSystem=strict` + `ProtectHome=read-only` automatiques
- `ConfigurationDirectory=` — accès sécurisé au TOML de config

## Dashboard web — spécifications UI

### Grille principale
- **Une tuile rectangulaire par agent** — grille `auto-fill minmax(220px, 1fr)` responsive.
- Métriques en **icônes** (pas de texte) avec **tooltips** sur chaque icône.
- **Jauges barre** pour CPU, RAM, disque dans les tuiles.
- **Effets** : halo lumineux au survol (couleur selon statut), pression 3D au clic.
- **Tooltips globaux** : positionnés en `position:fixed` via JS (jamais clippés).
- **Jusqu'à 20+ agents** — taille de tuiles configurable.

### SMART disque
- L'agent vérifie si `smartctl` est disponible sur la machine cible.
- Si disponible : collecte l'état SMART simplifié (`PASSED` / `FAILED` + température + reallocated sectors).
- Le popup détail affiche un **bouton SMART** dans la section Stockage (couleur ok/warn/err selon état).
- Clic sur le bouton → popup SMART complet, lisible par un non-expert, **en français** : état général, température, durée de vie estimée, secteurs défectueux, explications simples.

### Popup détail agent (clic sur tuile)
- **Redimensionnable** en largeur et hauteur — dernière taille sauvegardée sur le serveur.
- Pas de bouton "Fermer" — uniquement la croix en haut à droite.
- Icône agent cliquable pour upload custom (SVG/JPG/PNG/WEBP, redim. canvas max 128×128 px ratio préservé, sauvegardée sur le serveur).
- KPIs actuels + **courbes historiques** (SVG) pour CPU et RAM.
- Stockage en jauges barre.
- Protocoles actifs affichés en badges.
- **Bouton icône `fa-gears`** en bas à droite → ouvre le popup de configuration de l'agent.

### Popup configuration agent
- Accessible depuis le popup détail via l'icône gears (bas à droite).
- **Tableau métriques — 3 colonnes** : MÉTRIQUE / UDP / MQTT — une case à cocher par métrique par protocole, indépendantes. Pas d'activation générale du protocole.
  - Métriques : cpu, memory, disk, smart, uptime, network, temperature
  - Chaque case peut être cochée/décochée indépendamment (ex : CPU via UDP uniquement, température via MQTT uniquement)
- **Paramètres MQTT** : broker, port, topic base, auto-discovery (Home Assistant) toggle, birth message toggle, last will toggle.
- **Commandes distantes** : section affichée mais désactivée (bientôt) — reboot, shutdown, screen off, update, upgrade, shell cmd.
- **Bouton "Envoyer à l'agent"** — pousse la config via API REST → serveur → agent.

### Header
- Logo + LED animée + compteurs agents (total / ok / warn / err).
- Bouton thème clair/sombre.
- Bouton configuration interface (taille tuiles, texte, seuils, rétention historique) — config sauvegardée sur le serveur.

### Footer (status bar)
- Mode LIVE en fond accent (style tmux).
- CPU et RAM du **serveur** avec mini-jauges.
- Horodatage de la dernière actualisation.

### Stockage local des assets
Toutes les ressources web versionnées localement — pas de CDN en production :
```
dashboard/
├── fonts/          (Inter, JetBrains Mono, Share Tech Mono)
├── vendor/
│   └── fontawesome/
├── design_system/
│   ├── tokens/tokens.css
│   └── components/ui-kit.jsx
```

## Design System — règles obligatoires

Toute UI utilise `design_system/`. Lire `design_system/consigne_design_system.md` entièrement avant d'écrire du code UI.

Règles clés :
- **Toujours les variables CSS** — jamais de hex en dur.
- **`data-theme`** obligatoire sur `<html>`. Sans ça, l'UI casse silencieusement.
- **Composants** dans `ui-kit.jsx` avant d'en créer de nouveaux.
- **Icônes** : Font Awesome via `<Icon name="…">` uniquement — pas d'emoji, pas de SVG inline.
- **Polices** : Inter (UI), JetBrains Mono (valeurs numériques), Share Tech Mono (logs/terminal).
- **Labels** : uppercase + `letter-spacing: 0.08em`.
- **Border-radius** : tuiles 10-12px, boutons 8px, pastilles 999px.
- **`user-select:none`** : uniquement sur les éléments purement interactifs (`.hbtn`, `.btn`, `.pop-close`, `.cbox`, `.btn-agent-cfg`, `.tile-head`, `.tile-foot`). Jamais sur les conteneurs de contenu : le texte (hostname, IP, valeurs, labels) et les icônes doivent rester sélectionnables.

### Tokens de statut

| Token | Usage |
|-------|-------|
| `--ok` | état nominal |
| `--warn` | attention, seuil élevé |
| `--err` | erreur, alerte critique |
| `--accent` | action principale (orange Gruvbox) |
| `--blue` | datavis CPU / secondaire |
| `--purple` | MQTT / datavis tertiaire |