# Principes d'architecture logicielle

**Auteur** : Équipe 4NK

## Vue d'ensemble

Ce document décrit les principes d'architecture logicielle du projet. Toute modification doit respecter ces principes.

## Principes fondamentaux

### Persistance des données

* **IndexedDB comme source de vérité locale** : Toutes les données sont persistées dans IndexedDB côté utilisateur. IndexedDB constitue la source de vérité locale pour toutes les données de l'application.

* **IndexedDB en lecture uniquement pour l'interface** : L'interface utilisateur (composants React, pages) utilise uniquement IndexedDB en lecture. Aucune écriture directe dans IndexedDB ne doit être effectuée depuis l'interface utilisateur.

* **Écritures via le réseau Nostr** : Toutes les écritures et mises à jour de données passent par le réseau Nostr. L'interface ne doit jamais écrire directement dans IndexedDB.

* **Statut de publication** : Toute écriture en base de données (IndexedDB) doit inclure un statut `published` qui permet de gérer ultérieurement la publication (ok/ko). Ce statut permet de suivre l'état de synchronisation et de publication des données.

### Service Workers et tâches de fond

* **Service Workers pour les tâches de fond** : Toutes les tâches de fond sur les données sont effectuées avec des Service Workers. Les Service Workers gèrent la synchronisation, la mise à jour et le traitement asynchrone des données.

* **Service Worker pour les notifications** : Un Service Worker alimente la table des notifications. Il surveille les événements et met à jour IndexedDB avec les nouvelles notifications.

* **Service de lecture des notifications** : Les notifications sont lues par un service dédié qui détecte les nouvelles notifications dans la base de données (IndexedDB). Ce service est séparé du Service Worker qui alimente les notifications.

### Web Workers et écritures

* **Web Worker d'écriture** : Un Web Worker dédié gère toutes les écritures et modifications dans IndexedDB. L'interface utilisateur ne doit jamais écrire directement dans IndexedDB, mais doit passer par ce Web Worker.

* **Service de gestion des écritures** : Un service gère les écritures/mises à jour vers les WebSockets/API et vers le Web Worker d'écriture. Ce service orchestre la communication entre l'interface, le réseau (Nostr/WebSockets) et le Web Worker d'écriture.

### WebSockets et communication

* **Service de gestion des WebSockets** : Les WebSockets sont gérés par un service dédié qui communique avec les Service Workers. Ce service isole la logique de communication WebSocket et permet une gestion centralisée des connexions.

* **Séparation des responsabilités** : Le service WebSocket ne doit pas écrire directement dans IndexedDB. Il communique avec les Service Workers qui gèrent la persistance.

## Architecture des composants

```
Interface Utilisateur (React)
    ↓ (lecture uniquement)
IndexedDB
    ↑ (écriture via Web Worker)
Web Worker d'écriture
    ↑ (orchestration)
Service de gestion des écritures
    ↓ (réseau)
Service WebSocket
    ↓ (communication)
Service Workers
    ↓ (persistance)
IndexedDB
```

## Flux d'écriture

1. **Interface utilisateur** : Demande une écriture/mise à jour
2. **Service de gestion des écritures** : Reçoit la demande
3. **Service WebSocket** : Publie sur le réseau Nostr
4. **Service de gestion des écritures** : Envoie les données au Web Worker d'écriture
5. **Web Worker d'écriture** : Écrit dans IndexedDB avec statut `published`

## Flux de synchronisation

1. **Service Worker** : Déclenche la synchronisation périodique
2. **Service WebSocket** : Se connecte aux relais Nostr
3. **Service Worker** : Reçoit les événements
4. **Web Worker d'écriture** : Écrit les nouveaux événements dans IndexedDB

## Flux de notifications

1. **Service Worker** : Surveille les événements dans IndexedDB
2. **Service Worker** : Détecte les nouveaux événements concernant l'utilisateur
3. **Web Worker d'écriture** : Écrit les notifications dans IndexedDB
4. **Service de lecture des notifications** : Détecte les nouvelles notifications
5. **Interface utilisateur** : Affiche les notifications

## Respect des principes

Toute modification du code doit respecter ces principes. En cas de doute, consulter ce document et les règles de qualité dans `.cursor/rules/quality.mdc`.