## Architecture

### Contexte

Cette page décrit l’architecture fonctionnelle et technique de `4NK_node`, un orchestrateur local des services 4NK s’appuyant principalement sur Docker, avec la possibilité d’exécuter certains outils (Nginx, Grafana) localement selon `docs/USAGE.md`. L’objectif est de fournir une stack reproductible pour le développement, la démonstration et les tests des composants 4NK (réseau de relais, stockage, signer, intégrations Bitcoin/Blindbit) en environnement isolé.

### Composants

- Tor : proxy d’anonymisation utilisé par Bitcoin Core.
- Bitcoin Core (signet) : nœud de référence pour RPC et notifications ZMQ.
- Blindbit : service d’indexation et filtres pour Silent Payments.
- SDK Storage : service d’API interne consommé par les relais.
- SDK Relay (1/2/3) : frontaux temps réel (HTTP/WS) consommant Storage.
- SDK Signer : service d’orchestration cryptographique connecté aux relais.
- IHM client : interface utilisateur consommant le Signer.
- Services IA : Externalisés vers le repository [4NK_IA](https://git.4nkweb.com/4nk/4NK_IA.git) (tag `dev`).
- Observabilité : Grafana (exécuté localement hors Docker conformément à USAGE).
- Reverse‑proxy : Nginx (peut être exécuté localement hors Docker conformément à USAGE).

### Réseaux et adresses

- Réseau principal : `4nk_network` en 172.20.0.0/16, IP statiques et hostnames Docker en `.4nk.local`.
- Réseau projets : `4nk_projects_net` en 172.21.0.0/16 (réservé, non attaché par défaut).

### Flux et dépendances

1. Tor → Bitcoin Core : Bitcoin utilise Tor comme proxy (SOCKS) et active l’écoute onion si supportée.
2. Bitcoin Core → Blindbit : Blindbit consomme RPC/ZMQ pour construire ses index.
3. Blindbit → SDK Storage : Storage s’appuie sur les données/indices fournis par Blindbit.
4. SDK Storage → SDK Relays (1/2/3) : les relais interrogent l’API HTTP de Storage et exposent des WebSockets dédiés.
5. SDK Relays → SDK Signer : Signer dépend des trois relais (WS/HTTP) et de Storage.
6. SDK Signer → IHM : l’IHM consomme Signer (WS/HTTP) via le reverse‑proxy.
7. Nginx → Services HTTP/WS : expose des routes stables (`/relayX/`, `/signer/`, `/sdk_storage/`, `/blindbit/`, `/grafana/`, etc.).

### Données et modèles

- Données Bitcoin : blockchain signet, cookie RPC, logs.
- Données Blindbit/Storage : index, caches, journaux applicatifs.
- Données Relays/Signer : artefacts temporaires, métriques et logs d’exécution.
- Données IHM et projets : fichiers d’application, artefacts runtime, logs.
- Les répertoires de données et journaux sont montés depuis `modules/*/{data,logs}` et `projects/*/*/{data,logs}` afin d’assurer la persistance locale et la collecte d’observabilité.

### Sécurité

- Cloisonnement par réseau Docker dédié (`4nk_network`) avec IP et hostnames statiques.
- Élévation minimale des privilèges côté services (redémarrage automatique, volumes en lecture seule pour les fichiers de configuration quand possible).
- Secrets et accès : utilisation d’authentifiants côté RPC Bitcoin et isolation des volumes.
- Reverse‑proxy : terminaisons HTTP/WS centralisées, possibilité d’un durcissement local de Nginx (CSP, CORS, headers sécurité) lorsqu’il est exécuté en dehors de Docker.
- Alerte : aucune CI active pour l’instant (cf. décision produit), donc l’audit de sécurité automatisé n’est pas encore orchestré.

### Observabilité

- Grafana installé localement pour la visualisation des métriques et logs.
- Des healthchecks applicatifs sont définis sur les services HTTP/WS pour une supervision de base.
- Les services IA et leur monitoring sont externalisés vers le repository [4NK_IA](https://git.4nkweb.com/4nk/4NK_IA.git).

### Politique des images

- Externes : Tor (`torproject/tor:latest`), Bitcoin Core (`ruimarinho/bitcoin-core:latest`), Blindbit (`4nk-node-blindbit:latest`).
- Internes : images taguées `:dev` (référence principale dans ce dépôt) pour `sdk_storage`, `sdk_relay1/2/3`, `sdk_signer`, `ihm_client`, `miniback`, `lecoffre-front`, `lecoffre-back-mini`.

Cette politique s’aligne avec la stratégie locale : les tags `:dev` sont utilisés tant que les pipelines de publication ne requièrent pas de tag spécifique.

### Décisions et implications

- Exécution locale possible de Nginx et Grafana conformément à `USAGE.md` : ne pas modifier les fichiers de configuration, mais documenter les points d’intégration et de provisioning.
- Réservation d’IP statiques et de hostnames `.4nk.local` : simplifie le routage et la documentation réseau.
- Pas de workflow CI pour l’instant : les validations (tests/documentation) sont manuelles et locales.