gilles/mqtt_explorer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
94cd43a0e89388ff97c4cae917e15e2f05e804f7
mqtt_explorer/prompt_claude.md

12 KiB
Raw Blame History

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 :
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.

Reference in New Issue View Git Blame Copy Permalink