chore: initialise la structure du projet SentinelMesh
- 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>
This commit is contained in:
@@ -0,0 +1,112 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user