# 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 :

```text
third_party/
└── glance/
```

Commande recommandée :

```bash
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 :

```text
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 :

```text
/api/v1/
```

Formats :

- JSON
- WebSocket futur
- SSE futur

---

# Installation agents

## Objectif

Le widget doit fournir automatiquement :

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

## Paramètres obligatoires

Le script doit accepter :

```bash
--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 :

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

```yaml
- 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

```text
/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