From a3d450cb9028aa11c1be5550bf3b6522aa551cbc Mon Sep 17 00:00:00 2001
From: admin <root@lelekaos.com>
Date: Mon, 18 May 2026 15:10:33 +0000
Subject: [PATCH] docs: full project README with architecture, logic and
 install guide

---
 README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 003c4dc..16d22a3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,89 @@
 # ns8-backup-monitor
 
-NS8 backup monitoring system: alertmanager trigger, per-module status check, repository health check and unified notification
\ No newline at end of file
+Sistema di monitoraggio dei backup per **NethServer 8** basato su tre livelli:
+
+1. **Trigger**: riceve l'alert da Prometheus/Alertmanager (`NsBackupFailed`)
+2. **Correlazione**: interroga lo stato del piano e dei singoli moduli via Redis/cluster API
+3. **Classificazione**: distingue tra successo totale, fallimento parziale o fallimento globale di repository
+
+## Architettura
+
+```
+Alertmanager --webhook--> receiver.py
+                                |
+                    +-----------v-----------+
+                    |     correlator.py     |  <- stato piano + per-modulo
+                    +-----------+-----------+
+                                |
+                    +-----------v-----------+
+                    |     repo_check.py     |  <- verifica repository destinazione
+                    +-----------+-----------+
+                                |
+                    +-----------v-----------+
+                    |     notifier.py       |  <- email unica con esito classificato
+                    +-----------------------+
+```
+
+## Logica di classificazione
+
+| Esito | Condizione |
+|---|---|
+| SUCCESS | Tutti i moduli del piano completati, nessun errore repo |
+| PARTIAL | Almeno un modulo fallito, repository raggiungibile |
+| REPO_FAILURE | Errori di connessione/scrittura sulla destinazione, backup non avviati |
+
+## Requisiti
+
+- NethServer 8 (leader node)
+- Python 3.9+
+- Accesso Redis locale del cluster NS8
+- `metrics1` configurato con `mail_to` e `mail_from`
+- Alertmanager webhook abilitato verso `http://localhost:9099/alert`
+
+## Installazione
+
+```bash
+bash install.sh
+```
+
+## Configurazione
+
+```bash
+cp config/config.yml.example config/config.yml
+# editare config.yml con smtp, mail_to, soglie temporali
+systemctl enable --now ns8-backup-monitor
+```
+
+## Struttura file
+
+```
+ns8-backup-monitor/
+├── README.md
+├── install.sh
+├── ns8_backup_monitor/
+│   ├── receiver.py        # HTTP webhook receiver (porta 9099)
+│   ├── correlator.py      # correlazione stato backup cluster
+│   ├── repo_check.py      # verifica repository destinazione
+│   └── notifier.py        # invio email con esito classificato
+├── systemd/
+│   └── ns8-backup-monitor.service
+└── config/
+    └── config.yml.example
+```
+
+## Integrazione Alertmanager
+
+Aggiungere in `alertmanager.yml` il receiver:
+
+```yaml
+receivers:
+  - name: ns8-backup-monitor
+    webhook_configs:
+      - url: 'http://localhost:9099/alert'
+        send_resolved: true
+
+route:
+  receiver: ns8-backup-monitor
+  matchers:
+    - alertname =~ "NsBackupFailed|NsBackupMissing"
+```