SentinelMesh/consigne_claude_project_sentinelmesh_md.md

SentinelMesh — Consignes de développement

Objectif du projet

SentinelMesh est une plateforme modulaire de supervision d’infrastructure orientée homelab et self-hosting.

Le projet est composé de :

• Un backend/API central.
• Deux widgets principaux compatibles Glance.
• Deux agents Rust.
• Un système d’installation et de mise à jour centralisé via Gitea.
• Une architecture extensible permettant l’intégration future avec d’autres dashboards, systèmes domotiques et brokers MQTT.

Le projet doit être pensé dès le départ comme :

• Modulaire.
• API-first.
• Faiblement couplé.
• Auto-documenté.
• Extensible.
• Compatible multi-dashboard.
• Self-hosted.

---

Références documentaires obligatoires

Documentation Glance

Référence principale pour la compatibilité widgets et intégration dashboard :

• https://github.com/glanceapp/glance

IMPORTANT :

Claude doit :

• Étudier la structure de Glance.
• Respecter les conventions Glance.
• Respecter le format des widgets et APIs attendues.
• Vérifier les évolutions de Glance avant toute implémentation.
• Prévoir une compatibilité maximale avec les futures versions.

Documentation locale obligatoire

Le dépôt Glance doit être cloné localement dans un sous-dossier dédié afin de :

• Conserver une documentation locale.
• Permettre l’analyse du code.
• Faciliter le développement des widgets.
• Étudier les conventions UI/API.
• Éviter une dépendance permanente à Internet.

Structure recommandée :

third_party/
└── glance/

Commande recommandée :

git clone https://github.com/glanceapp/glance.git third_party/glance

IMPORTANT :

• Ne jamais modifier directement le dépôt Glance.
• Utiliser uniquement comme référence documentaire et technique.
• Prévoir une procédure simple de mise à jour.

---

Technologies principales

Backend

• Rust
• Axum ou Actix-web
• Tokio
• Serde JSON
• SQLite au début puis possibilité PostgreSQL
• OpenAPI/Swagger obligatoire

Frontend widgets

• Compatible Glance
• Widgets HTML/JS légers
• API REST JSON
• Support futur WebSocket/SSE

Agents

• Rust
• Cross-platform Linux prioritaire
• Faible consommation CPU/RAM
• Systemd
• JSON natif
• Architecture plugin/modulaire

UI / Icônes

Sources autorisées :

• https://github.com/tailwindlabs/heroicons
• https://selfh.st/icons/

IMPORTANT :

• Les icônes doivent être stockées localement.
• Aucun chargement distant.
• Prévoir un cache local.
• Prévoir un mapping automatique par type d’équipement/service.

---

Structure globale du projet

Dépôts Gitea

Le projet doit être organisé dans plusieurs dépôts :

sentinelmesh/
├── backend/
├── widgets/
│   ├── widget-network-scan/
│   └── widget-agent-metrics/
├── agents/
│   ├── agent-scan-network/
│   └── agent-metric/
├── install/
├── docs/
├── api/
├── modules/
└── examples/

---

Philosophie d’architecture

Règles importantes

• Toujours séparer acquisition de données et affichage.
• Toute donnée doit être accessible via API JSON.
• Les widgets ne doivent jamais dépendre directement des agents.
• Le backend centralise tout.
• Les agents doivent fonctionner même sans Glance.
• Les widgets doivent pouvoir être remplacés par d’autres dashboards.
• Les agents doivent pouvoir publier plus tard :
  • MQTT
  • WebSocket
  • Prometheus
  • InfluxDB
  • Home Assistant
  • Grafana
  • Node-RED

---

WIDGET 1 — Network Discovery

Nom

widget-network-scan

Objectif

Afficher les équipements découverts sur le réseau local.

Source des données

agent-scan-network

Fonctionnalités principales

Découverte réseau

• Ping sweep
• ARP discovery
• Détection MAC
• Résolution hostname
• Détection constructeur via OUI
• Détection services
• Scan ports
• Détection OS future
• Détection VLAN future

États

• Online
• Offline
• Veille
• Inconnu

Affichage Glance

Tuile avec :

• Nom
• IP
• Type
• Icône
• État
• Ping
• Services détectés

Popup secondaire :

• MAC
• Ports ouverts
• Historique
• Constructeur
• Dernière activité
• Temps de réponse
• Liens rapides

Auto-placement intelligent

Le widget doit :

• Grouper automatiquement les équipements.
• Réorganiser les tuiles.
• Supporter filtres.
• Supporter tri.
• Supporter favoris.

Personnalisation

Chaque tuile peut configurer :

• Icône.
• URL.
• Métriques affichées.
• Infos primaires.
• Infos secondaires.
• Couleurs futures.
• Groupes.

---

WIDGET 2 — Agent Metrics

Nom

widget-agent-metrics

Objectif

Afficher les métriques système remontées par les agents.

Source des données

agent-metric

Métriques principales

Temps réel

Fréquence : 1 seconde

• CPU usage
• RAM usage
• Load average
• GPU usage
• Températures
• Network throughput

Moyenne fréquence

Fréquence : 30 minutes

• HDD usage
• SSD usage
• SMART status
• Filesystem state
• Docker stats futures

Faible fréquence

Au démarrage puis 2 fois/jour

• Hostname
• Informations DMI
• CPU model
• RAM installed
• GPU info
• Interfaces réseau
• Numéro de série
• BIOS
• OS version

Événements

• Boot
• Shutdown propre
• Veille
• Reprise veille
• Changement état réseau

Processus importants

Afficher :

• Top 5 CPU
• Top 5 RAM
• Services critiques

Affichage Glance

Tuile principale :

• Nom machine
• État
• CPU
• RAM
• HDD
• GPU
• Température

Popup secondaire :

• Hardware complet
• Processus
• SMART
• Historique futur
• Réseau
• Liens rapides

---

AGENT 1 — agent-scan-network

Objectif

Scanner le réseau et découvrir les équipements.

Développement prioritaire

Cet agent doit être développé AVANT agent-metric.

Fonctionnement

• Scan périodique.
• Multi-thread.
• Très faible consommation.
• Mode daemon.
• Configuration YAML/JSON.

Fonctionnalités MVP

Découverte

• ICMP
• ARP
• Résolution DNS locale
• Détection MAC
• Détection constructeur

Scan services

• HTTP
• HTTPS
• SSH
• SMB
• NFS
• MQTT
• Docker
• Proxmox
• Home Assistant

API

L’agent expose :

• API locale JSON.
• Export backend.
• Export futur MQTT.

---

AGENT 2 — agent-metric

Objectif

Collecter les métriques système.

Fonctionnement

• Agent léger.
• Faible overhead.
• Multi fréquence.
• Architecture plugin.

Fréquences obligatoires

Toutes les 1s

• CPU
• RAM
• GPU
• Réseau

Toutes les 30 min

• HDD usage
• SMART
• Température disques

Boot + 2x/jour

• DMI
• Hardware
• BIOS
• Interfaces réseau

Événements instantanés

• Shutdown
• Veille
• Wake
• Changement état

Évolutivité

Prévoir :

• Docker metrics
• VM metrics
• Kubernetes futur
• Proxmox API
• NVIDIA
• Intel GPU
• AMD GPU
• Sensors Linux

---

Backend central

Rôle

Le backend centralise :

• Les agents.
• Les métriques.
• Les états.
• Les événements.
• Les historiques.
• Les commandes.
• Les mises à jour.

Fonctions importantes

Auto découverte agents

Les agents doivent pouvoir :

• S’enregistrer automatiquement.
• Être découverts.
• Être validés.
• Être regroupés.

Mise à jour agents

Le backend doit :

• Générer commandes update.
• Gérer versions.
• Gérer modules.
• Vérifier compatibilité.

API centrale

Toutes les données doivent être accessibles via :

/api/v1/

Formats :

• JSON
• WebSocket futur
• SSE futur

---

Installation agents

Objectif

Le widget doit fournir automatiquement :

curl -fsSL https://gitea.example/install.sh | bash

Paramètres obligatoires

Le script doit accepter :

--server
--port
--token
--agent-type
--hostname

Fonctionnalités installateur

• Installation dépendances.
• Création service systemd.
• Création config.
• Enregistrement backend.
• Gestion update.
• Vérification architecture.
• Vérification permissions.

---

Communication Glance

Objectif

Respecter une architecture compatible Glance.

Format

Les widgets doivent :

• Utiliser JSON.
• Être découplés.
• Pouvoir fonctionner via API externe.

Templates Glance

Prévoir exemples complets :

- type: custom-api
  title: SentinelMesh Metrics
  cache: 1s
  url: http://sentinelmesh/api/v1/widgets/metrics

- type: custom-api
  title: SentinelMesh Network
  cache: 30s
  url: http://sentinelmesh/api/v1/widgets/network

---

API design

Principes

• Stable.
• Versionnée.
• Documentée.
• Prévisible.
• JSON strict.

Exemples endpoints

/api/v1/agents
/api/v1/metrics
/api/v1/network
/api/v1/events
/api/v1/hardware
/api/v1/processes
/api/v1/install
/api/v1/update

---

Stockage

MVP

SQLite

Futur

• PostgreSQL
• Timeseries DB
• InfluxDB

Historique futur

Prévoir :

• Retention.
• Compression.
• Agrégation.

---

Sécurité

Obligatoire

• Auth token.
• TLS futur.
• Validation agent.
• Rate limiting.
• Logs.
• Audit.

---

Plan de développement

Phase 1

• Architecture.
• Structure dépôts.
• API backend.
• Base SQLite.
• agent-scan-network MVP.

Phase 2

• widget-network-scan.
• Découverte équipements.
• API network.
• Auto découverte.

Phase 3

• agent-metric.
• Collecte CPU/RAM.
• Collecte HDD.
• DMI.

Phase 4

• widget-agent-metrics.
• Popups.
• Tri.
• Personnalisation.

Phase 5

• Installateur.
• Update agents.
• Modules.
• Gestion versions.

Phase 6

• MQTT.
• WebSocket.
• Historique.
• Multi-dashboard.
• Plugins.

---

Plan de tests

Tests backend

• API.
• JSON.
• Charge.
• Sécurité.
• Résilience.

Tests agents

• CPU faible.
• RAM faible.
• Stabilité longue durée.
• Déconnexion réseau.
• Reconnexion.
• Mise à jour.

Tests widgets

• Glance.
• Responsive.
• Popup.
• Tri.
• Charge élevée.

Tests réseau

• Plusieurs VLAN.
• Plusieurs sous-réseaux.
• Latence.
• Offline.

---

Déploiement

Priorité

Docker Compose.

Futur

• Kubernetes.
• Helm.
• Packages Debian.
• Binary releases.

CI/CD

Prévoir :

• Build Rust.
• Tests.
• Lint.
• Release automatique.
• Build multi-arch.

Architectures prioritaires :

• amd64
• arm64
• Raspberry Pi

---

Documentation obligatoire

Claude doit produire :

• README.md
• INSTALL.md
• API.md
• ROADMAP.md
• ARCHITECTURE.md
• CONTRIBUTING.md
• CHANGELOG.md

---

Règles de développement pour Claude

Claude doit utiliser les skills adaptés

• plan dossier
• plan dev
• architecture
• roadmap
• feature planning
• tests
• documentation
• API design
• Rust best practices
• Glance compatibility

Règles importantes

• Ne jamais inventer d’API.
• Toujours documenter.
• Toujours prévoir évolutivité.
• Toujours séparer UI/API/agents.
• Toujours privilégier simplicité MVP.
• Toujours prévoir extension future.
• Toujours commenter les choix techniques.

Priorité développement

Ordre obligatoire :

1. Architecture globale
2. Backend API
3. agent-scan-network
4. widget-network-scan
5. agent-metric
6. widget-agent-metrics
7. Install/update system
8. MQTT/plugins/extensions

---

Vision long terme

SentinelMesh doit devenir :

• Une plateforme centralisée de supervision homelab.
• Un système modulaire.
• Un backend universel pour dashboards.
• Une solution légère.
• Une alternative moderne orientée self-hosting.
• Une base extensible pour IA, automatisation et monitoring avancé.

dans le repo, a la base, prevoir un fichier readme.md, feature.md, roadmap.md a minima

tu fera les commit automatic , et les push via http: https://git.maison43gil.com/gilles/SentinelMesh test au debut ( user ; gilles , pass: misstibet5*)

utilise rtk pour limiter la conso de token