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

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