From bfaf4c35626e735108a88fce215b057840544940 Mon Sep 17 00:00:00 2001
From: Massiles Ghernaout <749-gm213204@users.noreply.www-apps.univ-lehavre.fr>
Date: Mon, 9 Feb 2026 16:39:09 +0100
Subject: [PATCH] added some visuals for our readme, this helps the new commers
 understand the architecture quickly

---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/README.md b/README.md
index 9298af5..66bcd54 100644
--- a/README.md
+++ b/README.md
@@ -12,10 +12,87 @@ Ce dépôt contient une petite infrastructure Docker Swarm capable de bruteforce
 - **worker** : service de bruteforce MD5 (conteneurs réplicables dans le Swarm).
 - **frontend** : application React permettant d’envoyer des hash, choisir les modes *gentil/normal/agressif* et visualiser l’état du cluster.
 - **infra** : configuration Docker Swarm (stack) et scripts éventuels.
+- **proxy** : service Node.js qui expose un WebSocket compatible avec le tester de l’enseignant et le traduit en appels HTTP vers le backend.
 - **CI** : workflows d’intégration continue (fichier `.gitlab-ci.yml`).
 
 ---
 
+### Architecture
+
+#### Vue d’ensemble des services (stack Swarm)
+
+Tous les services tournent sur le réseau overlay `md5_net`. Le backend et le frontend exposent des ports sur l’hôte.
+
+> *Note: Veuillez installer l'extention vsCODE: Markdown Preview: Mermaid Support pour visualiser les diagrammes.*
+
+```mermaid
+flowchart LR
+  subgraph md5_net [Réseau md5_net]
+    Frontend[frontend]
+    Backend[api_backend]
+    Redis[redis]
+    Worker[hash_worker]
+    Proxy[hash_proxy]
+    Checker[hash_checker]
+  end
+  User[Utilisateur] -->|":5173"| Frontend
+  Frontend -->|"HTTP :8080"| Backend
+  Backend --> Redis
+  Backend -->|"Docker API"| Worker
+  Worker --> Redis
+  Checker -->|"WebSocket :3000"| Proxy
+  Proxy -->|"HTTP :8080"| Backend
+```
+
+- **Flux utilisateur (UI)** : le frontend envoie des hash au backend (`POST /hash/manual`), qui les met en file dans Redis. Les workers consomment la file, bruteforcent et écrivent les résultats dans Redis ; le backend lit l’état et les résultats (`GET /hash/:id`). Le scaler (dans le backend) ajuste le nombre de réplicas du service `hash_worker` en fonction de la charge.
+- **Flux tester** : le conteneur `hash_checker` (image enseignante) se connecte en WebSocket au `hash_proxy`. Il envoie `search MD5_HASH BEGIN END`. Le proxy appelle `POST /tester/search` puis poll `GET /tester/job/:id`, et renvoie `found` ou `notfound` au checker.
+
+#### Flux de traitement d’un job (utilisateur ou tester)
+
+```mermaid
+sequenceDiagram
+  participant Client as Client (frontend ou proxy)
+  participant Backend as api_backend
+  participant Redis as redis
+  participant Worker as hash_worker
+
+  Client->>Backend: POST /hash/manual ou POST /tester/search
+  Backend->>Redis: LPUSH jobs:pending, HSET jobs:status
+  Backend-->>Client: 202 { id }
+  Worker->>Redis: BRPOP jobs:pending
+  Worker->>Redis: SADD jobs:in_progress
+  Worker->>Worker: bruteforce (optionnellement entre begin/end)
+  Worker->>Redis: HSET jobs:results, jobs:status
+  Worker->>Redis: SREM jobs:in_progress
+  loop Polling
+    Client->>Backend: GET /hash/:id ou GET /tester/job/:id
+    Backend->>Redis: HGET jobs:results ou jobs:status
+    Backend-->>Client: résultat ou statut
+  end
+```
+
+#### Rôle du proxy (intégration tester)
+
+Le proxy adapte le protocole WebSocket du tester à l’API HTTP du backend.
+
+```mermaid
+flowchart LR
+  subgraph Tester [Tester enseignant]
+    Checker[hash_checker]
+  end
+  subgraph NotreStack [Notre stack]
+    Proxy[hash_proxy]
+    Backend[api_backend]
+  end
+  Checker -->|"search HASH BEGIN END"| Proxy
+  Proxy -->|"POST /tester/search"| Backend
+  Proxy -->|"GET /tester/job/:id"| Backend
+  Backend -->|"found / notfound"| Proxy
+  Proxy -->|"found HASH PLAINTEXT"| Checker
+```
+
+---
+
 ### Prérequis
 
 - Docker et Docker Swarm initialisé (`docker swarm init`).
-- 
GitLab