smart-city-digital-twin-martinique/DATA_PERSISTENCE.md

# Smart City Digital Twin - Persistence de données

Documentation technique sur l'emplacement et la structure des données des capteurs dans la stack Smart City Martinique.

## Vue d'ensemble

Les données des capteurs IoT sont persistées dans plusieurs bases de données selon le service consommateur. Le simulateur envoie les mêmes données vers trois systèmes principaux : FROST-Server, Orion-LD, et Stellio.

---

## 1. FROST-Server (Observations temporelles)

**Technologie** : PostgreSQL + PostGIS (OGC SensorThings API)

**Container** : `frost_allinone-database-1`

**Credentials** :
- User: `sensorthings`
- Password: `sensorthings`
- Database: `sensorthings`

**Schéma de données** :
- `THINGS` : Identité des capteurs (1 par capteur)
- `SENSORS` : Type de capteur (température, humidité, etc.)
- `DATASTREAMS` : Flux de données d'un capteur
- `OBSERVATIONS` : Valeurs mesurées avec timestamp

**Accès direct** :
```bash
docker exec frost_allinone-database-1 psql -U sensorthings -d sensorthings
```

**Statut actuel** : ✅ **21 256 observations** enregistrées

**Sauvegarde** :
```bash
docker exec frost_allinone-database-1 pg_dump -U sensorthings sensorthings > frost_backup_$(date +%Y%m%d).sql
```

---

## 2. Orion-LD (Entités contextuelles NGSI-LD)

**Technologie** : MongoDB

**Container** : `fiware-gis-quickstart-mongo-db-1`

**Base de données** : `orion` (ou `orionld`)

**Format** : JSON-LD (NGSI-LD)

**Structure** :
- Collections MongoDB : `entities`, `csubs` (subscriptions), `registrations`
- Chaque entité représente un capteur avec ses attributs (temperature, humidity, etc.)

**Accès direct** :
```bash
docker exec fiware-gis-quickstart-mongo-db-1 mongo orion --eval "db.entities.find().pretty()"
```

**Statut actuel** : ✅ **10 entités** (capteurs) créées

**Sauvegarde** :
```bash
docker exec fiware-gis-quickstart-mongo-db-1 mongodump --db orion --out /backup
```

---

## 3. Stellio (NGSI-LD + TimescaleDB)

**Technologie** : PostgreSQL + TimescaleDB + PostGIS

**Container** : `stellio-postgres`

**Credentials** :
- User: `stellio`
- Password: `stellio_password`
- Databases: `stellio_search`, `stellio_subscription`

**Tables principales** :
- `entity_payload` : Stockage des entités NGSI-LD (14 entités actuellement)
- `temporal_entity_attribute` : Attributs temporels
- `attribute_instance` : Instances d'attributs avec historique

**Accès direct** :
```bash
docker exec -e PGPASSWORD=stellio_password stellio-postgres psql -h 127.0.0.1 -U stellio -d stellio_search
```

**Statut actuel** : ✅ **14 payloads** d'entités enregistrés

**Sauvegarde** :
```bash
docker exec stellio-postgres pg_dump -U stellio stellio_search > stellio_backup_$(date +%Y%m%d).sql
```

---

## 4. OpenRemote (Assets IoT)

**Technologie** : PostgreSQL

**Container** : `openremote-postgresql-1`

**Credentials** :
- User: `openremote`
- Password: (défini dans docker-compose.yml, généralement `openremote`)
- Database: `manager`

**Données stockées** :
- Assets (capteurs, zones géographiques)
- Attributs des assets (valeurs en temps réel)
- Règles et automatisations
- Historique des attributs

**Statut actuel** : ⚪ En attente de réactivation (403 Forbidden à résoudre)

**Accès (quand réactivé)** :
```bash
docker exec openremote-postgresql-1 psql -U openremote -d manager
```

---

## 5. Brokers MQTT (EMQX & Mosquitto)

**EMQX** (`emqx_emqx_1`) :
- **Persistance** : Mnesia (RAM) ou MongoDB externe si configuré
- **Rôle** : Routage des messages uniquement, pas de persistance long-terme
- **Statut** : ⚠️ Transit uniquement

**Mosquitto** (`mosquitto-traefik`) :
- **Persistance** : Fichier `mosquitto.db` (si persistence activée)
- **Rôle** : Routage des messages MQTT
- **Statut** : ⚠️ Transit uniquement

**Note** : Les brokers ne stockent pas les données de manière durable. Ils les transmettent aux consommateurs (FROST, Orion, Stellio).

---

## 6. BunkerM (Service HTTP)

**Technologie** : HTTP Service (détails à confirmer)

**Container** : `bunkerm` (ou similaire)

**Authentification** : Basic Auth avec gestion de session (redirection 307 suivie par le simulateur)

**Statut** : ⚠️ En cours d'investigation (auth 307)

---

## Résumé des statistiques

| Service | Type de données | Nombre d'enregistrements | Statut |
|---------|----------------|-------------------------|--------|
| FROST-Server | Observations | 21 256 | ✅ Actif |
| Orion-LD | Entités NGSI-LD | 10 | ✅ Actif |
| Stellio | Entités NGSI-LD | 14 | ✅ Actif |
| OpenRemote | Assets IoT | 0 (non réactivé) | ⚪ Inactif |
| EMQX/Mosquitto | Messages MQTT | N/A (transit) | ✅ Routage |

---

## Script de sauvegarde complet

```bash
#!/bin/bash
# backup_all.sh - Sauvegarde complète de la stack Smart City

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=~/smart-city-backups/$DATE
mkdir -p $BACKUP_DIR

# FROST-Server
docker exec frost_allinone-database-1 pg_dump -U sensorthings sensorthings > $BACKUP_DIR/frost_$DATE.sql

# Orion-LD (MongoDB)
docker exec fiware-gis-quickstart-mongo-db-1 mongodump --db orion --out $BACKUP_DIR/mongo_backup_$DATE

# Stellio
docker exec stellio-postgres pg_dump -U stellio stellio_search > $BACKUP_DIR/stellio_$DATE.sql

# OpenRemote (quand réactivé)
# docker exec openremote-postgresql-1 pg_dump -U openremote manager > $BACKUP_DIR/openremote_$DATE.sql

echo "✅ Sauvegarde terminée dans $BACKUP_DIR"
```

---

## Génération de diagramme de persistance

```mermaid
graph TD
    A[Simulateur IoT] -->|MQTT| B[EMQX Broker]
    A -->|MQTT| C[Mosquitto Broker]
    B -->|Subscribe| D[FROST-Server]
    B -->|Subscribe| E[Orion-LD]
    B -->|Subscribe| F[Stellio]
    C -->|Subscribe| E
    C -->|Subscribe| F
    D -->|PostgreSQL| G[(FROST DB: 21k+ obs)]
    E -->|MongoDB| H[(Orion DB: 10 entités)]
    F -->|PostgreSQL| I[(Stellio DB: 14 entités)]
    A -->|HTTP| J[BunkerM]
```

---

*Document généré le 3 mai 2026 pour le projet Smart City Digital Twin Martinique*