417 lines
12 KiB
Markdown
417 lines
12 KiB
Markdown
# 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. |