Gilles Soulier
167 lines
9.0 KiB
Markdown
167 lines
9.0 KiB
Markdown
# 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 |
|