# Documentation Technique : PiAware Monitor Dashboard

Cette documentation décrit de manière exhaustive l'architecture, le fonctionnement et les procédures de maintenance du projet **PiAware Monitor**. Ce document est structuré pour offrir une lecture technique fluide et un apprentissage pas-à-pas pour tout développeur ou administrateur système.

## Introduction et Objectifs du Projet

**PiAware Monitor** est une application web locale (local-first) offrant un tableau de bord analytique et géographique des données de trafic aérien captées par un récepteur ADS-B (typiquement un Raspberry Pi équipé de PiAware / dump1090).

### Vision Globale et Contexte
L'application agit comme une surcouche intelligente à dump1090. Au lieu de se contenter d'afficher le trafic instantané, PiAware Monitor historise les données, génère des statistiques, croise les identifiants OACI (Hex IDs) avec des bases de données externes (Planespotters, HexDB, Wikimedia) pour récupérer le type d'appareil et des photographies, et intègre des calques météorologiques (RainViewer) en temps réel.

### Problématiques Résolues
* **Volatilité des données ADS-B :** Par défaut, dump1090 ne conserve pas l'historique des vols. PiAware Monitor intègre une base de données locale (SQLite) assurant une rétention configurable.
* **Manque d'enrichissement visuel :** dump1090 est basique. Ce projet ajoute des photos, le nom des compagnies aériennes, la météo radar dynamique et des trophées (records d'altitude, de vitesse).
* **Consommation d'API externe :** Une stratégie agressive de mise en cache locale (tuiles cartographiques, JSON de détails, images) est mise en place pour limiter le trafic externe et prévenir les blocages (rate-limiting).

### Valeur Ajoutée Technique
* **Autonomie (Local-First) :** Le cœur fonctionnel repose sur le réseau local (`piaware.local`). Les dépendances externes (météo, photos) dégradent gracieusement en cas de perte de connexion internet.
* **Architecture robuste :** Backend Python Flask léger, séparation des responsabilités entre la collecte (Worker ADS-B), le stockage (Manager SQLite) et la présentation (API REST).

## Architecture et Structure Logicielle

L'application repose sur une architecture **Monolithique Modulaire** de type Client-Serveur léger (Flask pour le backend, JS vanille pour le frontend).

### Choix de Conception
* **Backend (Python / Flask) :** Choisi pour sa légèreté, sa vaste écosystème d'intégration et sa facilité de déploiement sur des systèmes embarqués (Raspberry Pi).
* **Base de données (SQLite) :** Parfaitement adaptée aux lectures/écritures locales de faible concurrence. Élimine le besoin d'un serveur SGBD lourd (type PostgreSQL).
* **Frontend (Vanilla JS / CSS) :** Minimise la taille des assets, garantit une exécution rapide sur des navigateurs clients aux ressources limitées.

### Arborescence du Projet

```text
/home/pi/env_gravity/piaware/
├── app.py                 # Point d'entrée principal (Serveur Flask, Routes API, Gestion du cache tuiles)
├── database.py            # ORM léger et requêtes SQLite (Classe DatabaseManager)
├── piaware_monitor.py     # Client d'interrogation de l'API JSON locale dump1090/PiAware
├── flight_history.db      # (Généré) Base de données SQLite de production
├── config.json            # Configuration utilisateur (Coordonnées, IP PiAware, Rétention)
├── requirements.txt       # Dépendances Python (Flask, requests, rich)
├── start.sh / stop.sh     # Scripts Bash pour le contrôle du démon de l'application
├── data/
│   └── airports.csv       # (Généré) Cache CSV des aéroports locaux
├── cache/                 # Dossier de mise en cache dynamique (Généré)
│   ├── details.json       # Cache persistant des métadonnées avions (photos, types)
│   └── tiles/             # Tuiles cartographiques et météo (OSM, CartoDB, RainViewer)
├── static/                # Assets Frontend servis par Flask
│   ├── css/style.css      # Feuille de style principale
│   └── js/app.js          # Logique applicative côté client (Cartographie, requêtes API)
└── templates/             # Vues HTML (Jinja2)
    ├── index.html         # Tableau de bord principal et carte en temps réel
    ├── atc.html           # Vue "Air Traffic Control" (radar classique)
    ├── history.html       # Historique tabulaire des vols captés
    └── stats.html         # Graphiques analytiques et trophées
```

### Flux de Données (Data Flow)
1. **Acquisition :** À chaque requête frontend (polling), `app.py` sollicite `PiAwareClient` (`piaware_monitor.py`) qui effectue une requête HTTP vers `http://<PIAWARE_IP>:8080/data/aircraft.json`.
2. **Traitement :** Les données JSON brutes sont parsées, filtrées (validation des altitudes, calcul des distances 3D), et transformées en objets Dataclass Python.
3. **Persistance :** Les objets sont passés à `DatabaseManager` (`database.py`). La méthode `update_flight` insère les nouveaux vols ou met à jour les maximums (vitesse, altitude) des vols existants (UPSERT logique).
4. **Enrichissement (Asynchrone/Lazy) :** Lorsqu'un utilisateur clique sur un vol, le frontend appelle `/api/details/<hex>`. Le backend interroge d'abord `details.json` (Cache). Si vide, il cascade les appels : Planespotters -> HexDB -> Wikimedia, puis met en cache le résultat.

## Gestion des Dépendances et Prérequis

### Prérequis Système et Matériel
* **Matériel :** Un Raspberry Pi (3B, 4B ou 5) ou toute machine Linux (Debian/Ubuntu recommandé).
* **Réseau :** Accès local au récepteur PiAware (IP fixe ou `piaware.local`).
* **Python :** Version `3.9` ou supérieure.

### Dépendances Logicielles (`requirements.txt`)
* `Flask==3.0.3` : Framework web WSGI léger.
* `requests==2.31.0` : Bibliothèque HTTP pour interroger PiAware, Rainviewer et les API de métadonnées.
* `rich==13.7.0` : Utilisé (potentiellement) pour les affichages CLI esthétiques et le logging.

> **Note :** La bibliothèque standard Python (`sqlite3`, `json`, `math`, `shutil`, `pathlib`) est massivement utilisée pour limiter les dépendances externes, améliorant ainsi la robustesse et la sécurité.

## Guide de Déploiement et Mode Opératoire

### Installation Pas-à-Pas (Environnement Linux/Raspberry OS)

1. **Clonage ou copie des fichiers :** Placez le dossier `piaware` dans le répertoire utilisateur (ex: `/home/pi/piaware`).
2. **Création de l'environnement virtuel :**
   ```bash
   cd /home/pi/piaware
   python3 -m venv venv
   source venv/bin/activate
   ```
3. **Installation des dépendances :**
   ```bash
   pip install -r requirements.txt
   ```
4. **Configuration initiale :** Éditez (ou créez) le fichier `config.json` à la racine :
   ```json
   {
       "PIAWARE_IP": "127.0.0.1",
       "RECEIVER_LAT": 48.8566,
       "RECEIVER_LON": 2.3522,
       "HISTORY_RETENTION_DAYS": 30,
       "REFRESH_RATE": 5
   }
   ```
   *Remplacez `PIAWARE_IP` par l'IP de votre récepteur, et `RECEIVER_LAT` / `RECEIVER_LON` par vos coordonnées géographiques exactes.*

### Démarrage et Contrôle
L'application inclut des scripts bash pour un contrôle aisé en tâche de fond.
* **Démarrer l'application :**
  ```bash
  ./start.sh
  ```
  Le serveur écoutera sur le port `8000` (accessible via `http://<IP_DU_PI>:8000`). Les logs seront redirigés vers `app.log`.
* **Arrêter l'application :**
  ```bash
  ./stop.sh
  ```

## Guide de Maintenance et Robustesse

### Tolérance aux Pannes
* **API Externes :** Tous les appels réseaux externes (tuiles météo, API d'images) sont encapsulés dans des blocs `try/except` avec un `timeout=5`. Si une API (ex: Planespotters) tombe, l'application retourne une image transparente ou un statut silencieux sans faire crasher l'interface ni le serveur.
* **Cache de Tuiles Cartographiques :** La fonction `tile_cache` de `app.py` sauvegarde les PNG OSM/CartoDB localement (`/cache/tiles`). Une fois une région téléchargée, l'application peut fonctionner presque intégralement hors-ligne (Air-Gapped).

### Gestion de la Base de Données (Purge et Rotation)
La base `flight_history.db` est auto-maintenue.
* **Routine de nettoyage :** Toutes les 100 requêtes API globales (compteur interne `cleanup_counter` dans `app.py`), la méthode `cleanup_history(days)` est appelée.
* **Sécurité des données :** Cette purge est intelligente. Elle supprime les vols vieux de X jours (`HISTORY_RETENTION_DAYS`) **SAUF** s'ils détiennent un record absolu (vitesse max, altitude max de toute la base). Cela garantit que les "Trophées" de la page Statistiques ne sont jamais perdus.

### Logs et Debug
* Les erreurs système et exceptions API sont écrites dans `app.log`.
* Le niveau par défaut est configuré sur `INFO` via `logging.basicConfig(level=logging.INFO)` dans `app.py`. Pour du debug, modifiez cette valeur à `logging.DEBUG`.

## Améliorations et Évolutions Futures (Roadmap)

### Optimisations de la Dette Technique
1. **Migration vers une file d'attente asynchrone (Celery/RQ) :** Actuellement, le téléchargement des images et la vérification des API se font au sein de la requête synchrone Flask (`/api/details/<hex>`). Pour éviter le blocage du thread (Worker), il serait pertinent de déporter ces appels lourds vers un Worker asynchrone (Redis/RQ).
2. **WebSockets pour le Temps Réel :** Remplacer le polling HTTP (intervalle de 5 secondes) du frontend par des WebSockets (Flask-SocketIO). Cela réduirait drastiquement la charge CPU et réseau sur le Raspberry Pi.
3. **Indexation SQLite :** Ajouter des index B-Tree sur les colonnes souvent requêtées comme `max_altitude` et `last_seen` pour améliorer les performances de la page historique lorsque la base dépasse les 100 000 entrées.

### Nouvelles Fonctionnalités
* **Alertes (Push/Email) :** Possibilité de configurer des filtres (ex: "Alerte si Hélicoptère de la sécurité civile à moins de 5km" ou "Alerte si avion en code Squawk 7700 (Urgence)").
* **Export CSV/JSON :** Ajout d'un bouton sur l'interface pour extraire l'historique brut afin que les utilisateurs puissent réaliser leurs propres tableaux croisés dynamiques (Excel/PowerBI).
* **Support Multi-Récepteurs :** Capacité d'agréger les flux JSON de plusieurs dump1090 sur un même réseau local.
