diff --git a/prompt_claude.md b/prompt_claude.md new file mode 100644 index 0000000..192032a --- /dev/null +++ b/prompt_claude.md @@ -0,0 +1,417 @@ +# Prompt Claude Code — MQTT Web Explorer (Go backend persistant + UI Monokai) + +Tu es **Claude Code**. Tu dois générer un **projet complet** (code + fichiers + docker) pour un client web MQTT avancé, inspiré de **MQTT Explorer**, avec un **backend Go persistant** (toujours connecté au broker même si aucune page web n’est ouverte) et une UI moderne **responsive** (laptop + smartphone/tablette) avec **thèmes Dark Monokai / Light** séparés en fichiers. + +Le résultat doit être **prêt à builder et lancer** via Docker. +tu me parlera en francais et les commentaire de code en francais egalement +effectue une analyse globale du projet et tu me proposera en detail de l architecture, un dessin ascii draww de l interface web. +un plan de devellopement, un structure des dossier. les fichiers de documentation seront stocker dans un dossier doc et doc/analyse. +recherche des icones et images a utiliser dans le projet avec des propositions + +--- + +## 0) Principes d’architecture (non négociables) + +### Backend persistant +- Le backend Go doit **se connecter au(x) broker(s)** et **rester connecté** en continu. +- Les messages doivent **continuer d’être reçus et stockés** même si : + - aucun navigateur n’est ouvert, + - aucune session WebSocket n’est active. +- Le frontend n’est qu’un **client de visualisation** (il ne parle jamais directement au broker MQTT). + +### Perf / ressources +- Priorité à la sobriété CPU/RAM côté serveur. +- Éviter les dépendances lourdes. +- UI fluide même avec **beaucoup de topics**. + +--- + +## 1) Objectif fonctionnel + +Créer une application web permettant de : + +1. **Explorer les topics MQTT** sous forme d’arbre hiérarchique (type “CLI tree” pliable/dépliable). +2. **Filtrer / rechercher** efficacement (pour lisibilité). +3. **Inspecter les messages** : raw, JSON lisible, JSON tree, diff dernier/précédent. +4. **Historiser** les messages en **SQLite** avec **auto-purge** (TTL). +5. **Afficher des images** dans le payload (base64 data URL, base64 brut, champ JSONPath). +6. **Publier** des messages (topic/payload/qos/retain). +7. **Tracer** des valeurs numériques (payload brut ou JSONPath) via un graphe léger. +8. **Gérer plusieurs brokers** depuis l’UI (profils), avec **test réseau** (DNS/TCP/TLS/MQTT). +9. Être utilisable sur **laptop** et **mobile/tablette** (layout adaptatif). +10. Avoir un onglet **Paramètres** complet. +11. Être dockerisé (Dockerfile multi-stage + docker-compose). + +--- + +## 2) Stack imposée + +### Backend +- Langage : **Go** +- Framework : **Fiber** ou **Gin** (choisis-en un) +- MQTT client : lib robuste Go (ex: paho) +- WebSocket : natif Go + hub +- Stockage : **SQLite obligatoire** +- Configuration : variables d’environnement + fichiers optionnels + +### Frontend +- **TypeScript + Vite** +- **React** (préféré) +- UI : CSS variables + composants simples +- Icônes : **Lucide** (ou équivalent SVG, via `currentColor`) +- Graphe : **uPlot** (léger) +- Police monospace : **JetBrains Mono** (topics/payload) + option UI sans-serif (Inter) + +--- + +## 3) Arborescence attendue (monorepo) + +``` +/ +├─ backend/ +│ ├─ cmd/server/main.go +│ ├─ internal/ +│ │ ├─ api/ # routes HTTP +│ │ ├─ ws/ # hub websocket + events +│ │ ├─ mqtt/ # connexion, subscribe, reconnexion +│ │ ├─ storage/ # sqlite, migrations, purge TTL +│ │ ├─ topics/ # index/arbre, stats +│ │ ├─ images/ # helpers détection (optionnel) +│ │ └─ config/ # parsing env + validation +│ ├─ migrations/ +│ └─ go.mod +│ +├─ frontend/ +│ ├─ public/ +│ │ ├─ favicon/ +│ │ │ ├─ favicon.svg +│ │ │ ├─ favicon-32.png +│ │ │ ├─ favicon-16.png +│ │ │ └─ apple-touch-icon.png +│ │ └─ site.webmanifest +│ ├─ src/ +│ │ ├─ themes/ +│ │ │ ├─ theme-dark-monokai.css +│ │ │ ├─ theme-light.css +│ │ │ ├─ index.ts +│ │ │ └─ types.ts (optionnel) +│ │ ├─ styles/ +│ │ │ ├─ base.css +│ │ │ ├─ typography.css +│ │ │ └─ components.css +│ │ ├─ utils/ +│ │ │ ├─ theme.ts +│ │ │ ├─ api.ts +│ │ │ └─ format.ts +│ │ ├─ components/ +│ │ │ ├─ TopicTreeCli.tsx +│ │ │ ├─ TopicDetails.tsx +│ │ │ ├─ PayloadViewer.tsx +│ │ │ ├─ PublishPanel.tsx +│ │ │ ├─ ChartsDock.tsx +│ │ │ ├─ SettingsPanel.tsx +│ │ │ └─ Icons.tsx +│ │ ├─ pages/ +│ │ │ └─ App.tsx +│ │ └─ main.tsx +│ ├─ index.html +│ └─ package.json +│ +├─ docker/ +│ └─ mosquitto/ +│ └─ mosquitto.conf +│ +├─ docker-compose.yml +├─ Dockerfile +└─ README.md +``` + +--- + +## 4) UI/UX — exigences de design (Monokai + responsive + CLI tree) + +### 4.1 Thèmes séparés (obligatoire) +- Chaque thème dans un fichier CSS séparé (chargement dynamique). +- Thèmes requis : + - `dark-monokai` (fond principal **#272822**, palette Monokai officielle) + - `light` (clair neutre, accents cohérents) +- Stocker le choix utilisateur (localStorage) + respecter `prefers-color-scheme` au premier chargement. + +**Variables minimales dans chaque thème** (au moins) : +- `--bg-main`, `--bg-panel`, `--bg-code`, `--border` +- `--text-main`, `--text-secondary`, `--text-muted` +- Accents : `--accent-blue`, `--accent-green`, `--accent-yellow`, `--accent-orange`, `--accent-red`, `--accent-purple` +- JSON : `--json-key`, `--json-string`, `--json-number`, `--json-boolean`, `--json-null` +- Tree : `--tree-guide`, `--selected-bg`, `--hover-bg` +- `--focus-ring`, `--icon` + +### 4.2 Polices +- `JetBrains Mono` pour topics, payload, diff, timestamps. +- Option : `Inter` pour UI générale. + +### 4.3 Layout responsive +- Desktop : 3 zones (TopicTree / Details / Graph dock). +- Tablet : tree en drawer + details plein, graphs en dessous. +- Mobile : navigation par onglets : + - **Topics | Details | Publish | Graphs | Settings** +- Zones tactiles larges, barres collantes (sticky) quand utile. + +### 4.4 “CLI Topic Tree” (forte valeur ajoutée) +- Rendu monospace type terminal + glyphes : + - `▾` ouvert, `▸` fermé, `│` guides. +- Actions : + - clic: toggle + - Alt+clic: expand récursif + - Shift+clic: collapse récursif + - clavier: flèches ↑↓←→ +- Boutons globaux : + - Collapse all + - Expand all (profondeur max) + - Expand to selection +- Performance : + - éviter re-render complet + - mémoriser open/closed par profil + - virtualisation si trop de topics (si faisable simplement) + +### 4.5 Icônes +Utiliser des icônes SVG (Lucide) : +- copier topic, copier payload +- clear history topic +- delete retained +- publish +- afficher image (preview) +- graph +- settings +- search/focus + +Tooltips obligatoires sur desktop. + +--- + +## 5) Recherche / filtres (efficacité et lisibilité) + +Zone de recherche + filtres qui doit permettre : +1. Filtre topic : texte + wildcard + mode regex +2. Filtre payload : contains + regex +3. Toggles rapides : + - retained-only + - json-only + - numeric-only + - image-only + - active-only (activité < X secondes) +4. Mode Focus : masque tout sauf résultats +5. Tri : + - activité récente + - alphabétique + - taille payload + - fréquence msgs/s + +Option : auto-collapse des branches non matchées pendant filtre. + +--- + +## 6) Payload viewer (optimisé JSON lisible + diff) + +Dans `TopicDetails` : +- Onglets : **Raw | Pretty JSON | JSON Tree | Diff** +- JSON Pretty : + - indentation configurable + - wrap/nowrap + - erreurs JSON visibles +- JSON Tree : + - expand/collapse + - recherche interne + - copy value + - copy JSONPath +- Diff : + - dernier vs précédent + - diff texte (ligne à ligne) + - diff JSON si valide + +Limiter le rendu si payload énorme (max bytes) + bouton “charger complet”. + +--- + +## 7) Détection & affichage images (base64 + brut) + +Détecter et afficher des images si : +- payload commence par `data:image/...;base64,` +- base64 pur décodable contenant signature PNG/JPEG/GIF/WEBP +- JSON contenant champ image via liste JSONPath configurable (ex: `$.image`, `$.snapshot`, `$.payload.image`) + +Afficher : +- thumbnail dans details +- modal zoom (fit-to-panel) +- lazy-load + taille max preview configurable + +--- + +## 8) Historique SQLite (obligatoire) + auto purge TTL + +### Stockage +- Tous les messages reçus sont insérés en SQLite (asynchrone, queue). +- Ring buffer RAM optionnel pour ultra-réactivité UI. + +### Auto-purge +- TTL configurable (ex: 7 jours) +- Job périodique (toutes les 5–15 min) : + - `DELETE FROM messages WHERE ts < now - ttl` +- `VACUUM` : pas trop fréquent (1/jour max ou bouton manuel). + +### Purge par topic +- Endpoint + bouton UI : “Clear topic history” +- Efface l’historique complet du topic en base. + +### Indexation +- Index indispensable : `(topic, ts)`. + +--- + +## 9) Multi-serveurs MQTT (profils) + test réseau + +### Profils depuis l’UI +CRUD profils : +- name +- host / port +- TLS (on/off) +- username / password +- clientId (stable) +- keepalive +- default subscribe (ex `#`) +- qos default +- reconnect policy + +Sauvegarde : +- au minimum localStorage +- idéalement SQLite côté backend (si multi-user envisagé) + +### Test réseau (obligatoire) +Depuis l’UI, bouton “Test” → backend : +- DNS resolve +- TCP connect (latence + timeout) +- TLS handshake (si TLS) +- MQTT connect/auth (CONNACK) +Retour UI : statut + détails d’erreur. + +--- + +## 10) Paramètres (onglet Settings) — options à afficher + +L’onglet Paramètres doit contenir ces sections : + +1. **Profils MQTT** + - liste + CRUD + import/export JSON + - bouton Test + - bouton Connect/Disconnect +2. **Souscriptions & filtrage global** + - topic root subscribe (ex `#`) + - filtres par défaut + Focus mode par défaut + - tri par défaut +3. **Historique & rétention SQLite** + - TTL (durée conservation) + - fréquence purge + - stats DB (taille, nb lignes) + - boutons : Purge now, Vacuum now (warning) +4. **Affichage payload** + - mode par défaut (Raw/JSON/Tree) + - indentation, wrap + - diff auto (on/off) + - max bytes rendu +5. **Détection images** + - activer (on/off) + - JSONPath list + - taille max preview +6. **Graphiques** + - activer auto-plot + - JSONPath numeric list + - fenêtre (N points / X minutes) +7. **Topics tree** + - profondeur expand-all + - auto-collapse pendant filtre + - mémoriser open/closed +8. **Thème & UI** + - sélecteur de thème (dark-monokai / light) +9. **Sécurité** + - mode lecture seule (désactive publish/delete) + - masque secrets dans logs +10. **Diagnostic** + - niveau logs + - stats runtime (ws clients, msgs/s) + +--- + +## 11) Endpoints backend requis + +### HTTP +- `GET /api/health` +- `POST /api/test-connection` +- `GET /api/topics` (snapshot arbre + last message + stats) +- `GET /api/topic/:topic/history?limit=&from=&to=` +- `POST /api/topic/:topic/clear-history` +- `POST /api/publish` +- `POST /api/retained/delete` (optionnel) +- `GET/POST /api/settings` (optionnel si stockage serveur) +- `GET/POST /api/profiles` (optionnel si stockage serveur) + +### WebSocket +- `GET /ws/events` + - push des events : + - message reçu (topic, ts, qos, retain, payloadPreview, type hint json/image/numeric) + - stats périodiques + +--- + +## 12) Docker (obligatoire) + Mosquitto de test + +### docker-compose +- Service `mosquitto` avec config fournie (websockets activés pour tests). +- Service `mqtt-web-explorer` : + - build multi-stage + - expose `http://localhost:8088` + - volume persistant pour SQLite (ex: `./data:/data`) + - restart: unless-stopped + +### Dockerfile multi-stage +- build frontend → fichiers statiques +- build backend → binaire Go +- image finale minimale + +--- + +## 13) Favicon / manifest / PWA basique + +Prévoir : +- `public/favicon/favicon.svg` +- `favicon-16.png`, `favicon-32.png` +- `apple-touch-icon.png` +- `site.webmanifest` (name, icons, theme_color, background_color) + +Icône simple lisible : ondes MQTT + node. + +--- + +## 14) Qualité attendue + +- Code propre, structuré, commenté (là où ça aide) +- Erreurs affichées clairement dans l’UI +- Pas de dépendances inutiles +- Le projet doit fonctionner après : + +```bash +docker compose up -d --build +``` + +--- + +## 15) Sortie attendue de Claude Code + +1. Génère l’arborescence complète. +2. Génère le contenu complet de chaque fichier. +3. Fournis un `README.md` clair : + - configuration env + - lancement docker + - description features + - limites connues +4. Assure-toi que le projet compile et démarre. + +Fin. \ No newline at end of file