# 📄 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)
```