gilles
7cf56f24ef
- Workspace Cargo avec backend, agent-scan-network, agent-metric - Skeleton Rust pour les trois crates (Axum, Tokio, SQLx) - Documentation : README, FEATURES, ROADMAP, ARCHITECTURE, API, INSTALL - Exemples de widgets Glance (custom-api) - Script d'installation agents (squelette Phase 5) - Docker Compose + Dockerfile backend - .gitignore et CLAUDE.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
# 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`
|