SentinelMesh/CLAUDE.md

CLAUDE.md

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

Langue de travail

Toutes les discussions, commentaires dans le code, messages de commit et réponses de Claude doivent être en français uniquement.

Project Overview

SentinelMesh is a modular homelab infrastructure monitoring platform (currently in Phase 1 — architecture/bootstrap). It is composed of:

• backend/ — Central Rust API server (Axum + Tokio + SQLite + OpenAPI)
• agents/agent-scan-network/ — Rust daemon: network discovery (ICMP, ARP, MAC, services)
• agents/agent-metric/ — Rust daemon: system metrics collection (CPU/RAM/HDD/GPU/DMI)
• widgets/widget-network-scan/ — Glance-compatible widget: discovered devices
• widgets/widget-agent-metrics/ — Glance-compatible widget: system metrics
• install/ — Automated agent install/update scripts (curl | bash, systemd)

Architecture Rules

• Strict separation: agents collect → backend centralizes → widgets display. Widgets never talk to agents directly.
• API-first: every piece of data must be reachable via /api/v1/. No data without an endpoint.
• Agents are standalone: they expose their own local JSON API and push to the backend, independent of Glance.
• Glance widgets use custom-api type (or extension). Never modify the Glance codebase — it lives in repo_glance/glance/ as a read-only reference.
• Development order is fixed: backend → agent-scan-network → widget-network-scan → agent-metric → widget-agent-metrics → install system.

Glance Reference

The Glance dashboard source is cloned locally at repo_glance/glance/ — consult it for widget conventions, API formats, and template patterns. Never modify it. Glance widget types to use: custom-api (preferred), extension (WIP, needs separate HTTP server), iframe (for full interactive apps).

Example Glance widget config targets:

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

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

Technology Stack

Layer	Technologies
Backend	Rust, Axum, Tokio, Serde JSON, SQLx, SQLite (→ PostgreSQL later)
Agents	Rust, Tokio, systemd, JSON, plugin/module architecture
Widgets	HTML/JS (minimal vanilla), Glance custom-api format
API	REST JSON /api/v1/, OpenAPI/Swagger mandatory, WebSocket/SSE planned
Icons	Heroicons or selfh.st/icons — stored locally, no remote loading
Deployment	Docker Compose (MVP), multi-arch: amd64, arm64, Raspberry Pi

Build & Dev Commands

Once code exists, standard commands will be:

# Backend
rtk cargo build                  # Build
rtk cargo check                  # Fast type check
rtk cargo clippy                 # Lint
rtk cargo test                   # Run all tests
rtk cargo test <test_name>       # Run single test
rtk cargo test -- --nocapture    # Tests with stdout

# Agents (same pattern, from agent directory)
rtk cargo build --release        # Release binary for deployment

Always use rtk prefix for all shell commands to reduce token consumption.

Gitea Remote

Project is hosted at: https://git.maison43gil.com/gilles/SentinelMesh User: gilles — credentials are in local environment, not in code.

API Design Principles

• Versioned: all endpoints under /api/v1/
• Strict JSON, no optional formats
• OpenAPI spec must be maintained alongside code
• Key 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

Agent Architecture

Agents must:

• Self-register with the backend on startup
• Expose a local JSON API
• Support future publish targets: MQTT, WebSocket, Prometheus, InfluxDB, Home Assistant, Grafana, Node-RED
• Be installable via: curl -fsSL https://gitea.../install.sh | bash --server <url> --port <n> --token <t> --agent-type <type>
• Run as systemd services

Metric collection frequencies (agent-metric)

• 1s: CPU, RAM, GPU, network throughput
• 30min: HDD usage, SMART, disk temps
• Boot + 2×/day: hostname, DMI, CPU model, RAM, GPU info, network interfaces, BIOS, OS version
• Instant events: boot, shutdown, sleep, wake, network state change

Storage

MVP: SQLite via SQLx. Schema must anticipate future migration to PostgreSQL and timeseries DB (InfluxDB). Plan for retention, compression, and aggregation from the start.

Security Requirements (MVP)

Token-based auth for all API calls, rate limiting, input validation, audit logs. TLS and agent validation planned for later phases.

Documentation to Maintain

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