life-noc/docs/architecture-life-noc.md

# Architecture et fonctionnement de Life-NOC

## 1. Présentation générale

### 1.1 Définition

**Life-NOC** est un système de pilotage personnel qui applique à la vie réelle la logique d’un **NOC** (Network Operations Center / centre d’opérations).

Son but n’est pas d’automatiser la vie à la place de la personne. Son but est de :

- rendre visibles les suivis importants ;
- transformer la charge mentale en état observable ;
- soutenir la mémoire prospective ;
- orienter l’attention vers ce qui mérite réellement d’être vu ;
- réduire la friction entre la prise de conscience et l’action.

Life-NOC peut être résumé ainsi :

> **Voir clair, prioriser juste, agir au bon endroit.**

### 1.2 Finalité

Life-NOC sert à superviser des éléments de la vie personnelle, domestique, administrative, technique ou communautaire comme s’il s’agissait de services critiques dans une salle de contrôle.

Il permet par exemple de suivre :

- des revues périodiques ;
- des échéances ;
- des stocks ;
- des vérifications techniques ;
- des obligations administratives ;
- des contrôles de maintenance ;
- des routines de résilience ;
- des points d’attention dans l’environnement physique.

### 1.3 Positionnement

Life-NOC n’est pas :

- un simple gestionnaire de tâches ;
- un agenda ;
- un ERP ;
- un moteur d’automatisation généraliste ;
- un outil d’inventaire pur.

Life-NOC est :

- un **système de supervision attentionnelle** ;
- un **cadre d’évaluation de suivis** ;
- un **point de convergence** entre intrants, règles, états et actions ;
- une **interface de réduction de charge mentale**.

## 2. Principes de fonctionnement

### 2.1 Séparation des couches

Life-NOC repose sur quatre couches distinctes :

1. **définition** ;
2. **ingestion** ;
3. **persistance** ;
4. **évaluation**.

**Définition**  
Contient les items à superviser, les méthodes, les seuils, les notes et les liens utiles.

**Ingestion**  
Contient les mécanismes par lesquels une donnée entre dans le système :
- saisie manuelle ;
- API ;
- page HTML ;
- QR code ;
- plus tard MQTT, GUI avancée, etc.

**Persistance**  
Contient les intrants vivants à jour.

**Évaluation**  
Contient la logique qui transforme un intrant en état Life-NOC.

### 2.2 Philosophie générale

Le système suit cette logique :

- le **domaine** organise ;
- la **méthode** évalue ;
- l’**item** fait le lien entre les deux ;
- l’**intrant** fournit la valeur vivante ;
- la **page item** réduit la friction d’action ;
- **Icinga** rend les états visibles dans un cadre de supervision.

## 3. États Life-NOC

### 3.1 États

- **UNKNOWN** : pas encore dû, pas encore à faire ;
- **OK** : actionnable maintenant ;
- **WARNING** : il faut se presser ;
- **CRITICAL** : en retard, anormal, ou impossible à évaluer.

### 3.2 Politique d’erreur

Par défaut, si le système ne peut pas conclure techniquement, il retourne **CRITICAL**.

Exemples :

- fichier introuvable ;
- donnée absente ;
- format invalide ;
- parsing impossible ;
- seuil incohérent ;
- type de sonde non pris en charge.

## 4. Organisation métier par domaines

Les domaines servent à organiser les suivis.

Exemples :

- revue ;
- focus ;
- finances-personnelles ;
- obligations-legales-personnelles ;
- maison ;
- energie ;
- voiture ;
- projets ;
- documentation ;
- animaux.

Le domaine est une unité d’organisation métier, pas nécessairement une unité de calcul.

## 5. Taxonomie des méthodes de sonde

### 5.1 `elapsed_time`
Mesure le temps écoulé depuis une dernière exécution.

### 5.2 `days_until_due`
Mesure le temps restant avant une échéance fixe.

### 5.3 `elapsed_distance`
Mesure une distance écoulée depuis une action passée.

### 5.4 `current_value`
Évalue une valeur instantanée contre des seuils.

### 5.5 `remaining_quantity`
Évalue ce qu’il reste d’un stock ou d’une réserve.

## 6. Portée actuellement validée

Au stade actuel, les méthodes réellement validées sont :

- `elapsed_time` ;
- `days_until_due`.

## 7. Définition des items

Les items sont définis dans :

```text
domains.yaml
```

Un item peut contenir :

- `name`
- `date`
- `notes`
- `notes_url`
- `instructions_url`
- `action_url`
- `probe`

### 7.1 Rôle des champs descriptifs

- `notes` : résumé court ;
- `notes_url` : contexte / référence ;
- `instructions_url` : procédure ;
- `action_url` : outil ou page d’action.

## 8. Store des intrants

Les intrants vivants sont stockés sous :

```text
data/inputs/<domaine>.yaml
```

Exemple :

```yaml
revue-hebdomadaire-priorites:
  value: "2026-03-14"
  captured_at: "2026-03-14T23:16:41Z"
  origin: manual
```

## 9. CLI des intrants

Commandes principales :

- `list`
- `get`
- `set`
- `complete`

Exemples :

```bash
life-noc-input list revue
life-noc-input get revue revue-hebdomadaire-priorites
life-noc-input set revue revue-hebdomadaire-priorites 2026-03-14
life-noc-input complete revue revue-hebdomadaire-priorites
```

## 10. API locale des intrants

API locale sur :

```text
http://127.0.0.1:8787
```

Endpoints JSON :

- `GET /health`
- `GET /inputs/{domain}`
- `GET /inputs/{domain}/{item_key}`
- `POST /inputs/{domain}/{item_key}`
- `POST /inputs/{domain}/{item_key}/complete`

Dépendances importantes :

- `python3-fastapi`
- `python3-uvicorn`
- `python3-multipart`

## 11. Pages HTML Life-NOC

Route :

```text
/life-noc/item/<domaine>/<item_key>
```

La page affiche :

- titre humain ;
- état actuel ;
- type de sonde ;
- dernier intrant ;
- domaine ;
- item key ;
- notes ;
- liens utiles ;
- bouton `Compléter`.

Le bouton utilise :

```text
POST /life-noc/item/<domaine>/<item_key>/complete
```

## 12. Intégration Icinga

Life-NOC s’appuie sur Icinga pour :

- la visualisation des états ;
- le `Check Now` ;
- les BPM natifs ;
- les servicegroups ;
- l’affichage des variables utiles.

## 13. Flux complet

1. définition dans `domains.yaml` ;
2. intrant dans `data/inputs/<domaine>.yaml` ;
3. mise à jour par CLI, API ou page HTML ;
4. lecture par la sonde ;
5. calcul de l’état ;
6. affichage dans Icinga ;
7. action de l’usager ;
8. mise à jour de l’intrant.

## 14. Déploiement

Commandes usuelles :

```bash
make check
make deploy-with-bpm
```

Le dépôt doit rester reproductible sans correctifs manuels cachés.