mesh/docs/claude(1).md

📄 claude.md — Mesh (spécification générale, Rust pragmatique)

1. Description

Mesh est une application de communication pour petites équipes (2 à 4 personnes), self-hosted, optimisée pour :

• faible charge serveur (control plane uniquement),
• flux directs P2P (média + data),
• sécurité via autorisations centralisées,
• notifications via Gotify.

Fonctionnalités :

• chat,
• audio / vidéo,
• partage d’écran,
• partage fichiers & dossiers,
• partage de terminal (session SSH “preview” + contrôle),
• notifications (serveur + client/agent → Gotify).

---

2. Architecture globale

Séparation stricte :

• Control plane : Mesh Server (Python)
• Media/Data plane : P2P

          ┌──────────────┐
          │    Gotify     │
          └──────▲───────┘
                 │
      events/notify (server+agent)
                 │
Client Web ── P2P (WebRTC RTP) ── Client Web
    │   \                           /   │
    │    \                         /    │
    │     \— P2P (QUIC data) ——--/      │
    │            (agent↔agent)          │
    └────────── WS (signaling) ─────────┘
                Mesh Server

• Audio/Vidéo/Écran : WebRTC (navigateurs)
• Fichiers/Dossiers/Terminal : P2P data
  • recommandé V1 : QUIC (TLS 1.3) via Agent Rust (agent↔agent, agent↔client si support)
  • option V2 : WebRTC DataChannel (si besoin d’unifier)
  • fallback exceptionnel : HTTP temporaire via serveur

---

3. Stack technique (pragmatique)

Serveur (Python)

• Python 3.12+
• FastAPI
• WebSocket /ws (signalisation + events)
• JWT (auth)
• Capabilities tokens TTL court
• SQLite (MVP), PostgreSQL (V1)
• Adapter notifications : Gotify
• Déploiement : Docker

Client (Web)

• Vite + React + TypeScript (ou équivalent)
• WebRTC (call/screen)
• UI terminal : xterm.js

Agent (Rust)

• tokio + reqwest + tokio-tungstenite
• QUIC P2P : quinn
• Terminal : portable-pty / ConPTY
• FS watcher : notify
• Logs : tracing

---

4. Rôles & responsabilités

Mesh Server (control plane)

• Auth / sessions
• Rooms (2–4) + ACL
• Émission de capability tokens (TTL court)
• Signalisation WebRTC (offer/answer/ice)
• Arbitrage contrôle terminal (“take control”)
• Event bus + notifications Gotify

Clients (web)

• UI + WebRTC call/screen
• Chat
• Signaling WS
• Terminal viewer

Agents (Rust)

• Terminal share (PTY + stream)
• Partage fichiers/dossiers P2P
• Sync dossiers (optionnel)
• Notifications Gotify

---

5. Structure du dépôt

mesh/
  server/
  client/
  agent/
  infra/
  docs/

Docs attendus :

• protocol-events.md
• signaling.md
• security.md
• deployment.md

---

6. Règles de permissions (capabilities)

Le serveur émet des tokens de capacités (TTL 60–180 s), scoppés :

• room_id
• peer_id / device_id
• caps[] ex: call, screen, share:file, share:folder, terminal:view, terminal:control
• option : target_peer_id, max_size, max_rate

Règles :

• aucune session P2P ne démarre sans token valide.
• terminal : terminal:view pour recevoir, terminal:control pour envoyer input.

---

7. Étapes du projet (roadmap)

Phase 1 — Fondation (MVP control plane)

• Server skeleton FastAPI (auth/rooms/ws)
• Protocole events & signalling (WS)
• Capabilities tokens + validation
• Adapter Gotify (server)

Phase 2 — Communication (Web)

• Chat (MVP)
• WebRTC audio/vidéo P2P
• Screen share P2P

Phase 3 — Agent Rust (data plane)

• Agent Rust skeleton (WS + config + Gotify)
• Terminal share preview (PTY → P2P QUIC)
• Take control (arbitrage via serveur)

Phase 4 — Partage data

• File transfer P2P (QUIC)
• Folder zip P2P
• Fallback HTTP (exception)

Phase 5 — Sync & polish

• Folder sync (manifest/diff + conflits)
• Packaging multi-OS (MSI/deb/dmg)
• Monitoring minimal + diagnostics

---

8. TODO global

• RBAC simple (owner/member/guest)
• Quotas (taille, débit)
• Préférences notifications (par room / par event)
• Journaux & rotation
• Tests d’intégration (WS + tokens)

---

9. Améliorations futures

• Mobile native
• Federation Mesh↔Mesh
• Plugin system
• E2E applicatif optionnel
• TCP-like tunneling au-dessus de QUIC (SSH tunnel)

---

10. Changelog

0.1.0 – Architecture validée (Python server + Rust agent)
0.2.0 – MVP WebRTC (call/screen)
0.3.0 – Agent terminal preview (QUIC)
0.4.0 – File/folder transfer (QUIC)
0.5.0 – Folder sync (beta)