mesh/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Mesh is a self-hosted communication application for small teams (2-4 people) designed with:

• Minimal server load: Server handles control plane only
• Direct P2P flows: Media and data transfer happen peer-to-peer
• Centralized security: Server manages authentication, authorization, and arbitration
• Excellent multi-OS portability: Works across Linux, Windows, and macOS

Key features: Chat, audio/video, screen sharing, file/folder sharing, terminal sharing (SSH preview + control), Gotify notifications.

Dark Theme like monokai

Architecture: Three Planes

This architecture separation is fundamental and must never be violated:

Control Plane: Mesh Server (Python)

• Authentication & authorization
• Room management & ACL
• Capability tokens (short TTL: 60-180s)
• WebRTC signaling
• P2P orchestration
• Gotify notifications

Media Plane: WebRTC

• Audio/video/screen (web client only)
• Direct browser-to-browser connections

Data Plane: P2P

• Primary: QUIC (TLS 1.3) via Rust Agent for files, folders, terminal
• Exceptional fallback: Temporary HTTP via server

Critical rule: The server NEVER transports media or heavy data flows.

Technology Stack

• Server: Python 3.12+, FastAPI, WebSocket
• Client: Web (React/TypeScript), WebRTC
• Agent: Rust (tokio, quinn for QUIC)
• Notifications: Gotify
• Deployment: Docker, reverse-proxy with TLS

Security Model

These security rules are non-negotiable:

1. All P2P actions require capability tokens issued by the server
2. Tokens are short-lived (60-180s TTL)
3. Terminal sharing is preview-only by default (read-only)
4. Terminal control is explicit and server-arbitrated
5. Secrets (SSH keys, passwords) never leave the local machine

See docs/security.md for complete security model.

Protocol & Events

• WebSocket: Client/Agent ↔ Server (signaling, events, control)
• WebRTC: Browser ↔ Browser (audio/video/screen media)
• QUIC: Agent ↔ Agent (files, folders, terminal data)

All events follow a structured format with type, id, timestamp, from, to, payload.

First message on QUIC session must be P2P_HELLO with session validation.

See docs/protocol_events_v_2.md and docs/signaling_v_2.md for complete protocol specifications.

Repository Structure

Expected structure (to be created during implementation):

mesh/
├── server/          # Python FastAPI server
│   └── CLAUDE.md    # Server-specific guidance
├── client/          # React/TypeScript web client
│   └── CLAUDE.md    # Client-specific guidance
├── agent/           # Rust desktop agent
│   ├── CLAUDE.md    # Agent-specific guidance
│   └── src/
│       ├── config/
│       ├── mesh/       # Server communication
│       ├── p2p/        # QUIC implementation
│       ├── share/      # File/folder transfer
│       ├── terminal/   # PTY management
│       └── notifications/
├── infra/           # Deployment configs
│   └── CLAUDE.md    # Ops-specific guidance
└── docs/            # Additional documentation

Code Quality Standards

Traceability Headers

All new files MUST include a traceability header at the top. This is enforced by pre-commit hooks.

Rust example:

// Created by: YourName
// Date: 2026-01-01
// Purpose: QUIC endpoint management for P2P sessions
// Refs: protocol_events_v_2.md

Python example:

# Created by: YourName
# Date: 2026-01-01
# Purpose: WebSocket event router
# Refs: protocol_events_v_2.md

See docs/tooling_precommit_vscode_snippets.md for VS Code snippets and pre-commit setup.

Rust-Specific Requirements (Agent)

• Rust stable only
• Runtime: tokio async
• Error handling: Explicit Result<T, E>, use thiserror
• Logging: Use tracing crate
• NO unwrap() or expect() in production code
• Work in short, controlled iterations: compilable skeleton first, then add modules one-by-one

Language Requirements

CRITICAL: All code comments and documentation in French must be written in French:

• Code comments: French (// Connexion au serveur, # Gestion des erreurs)
• Documentation strings: French (docstrings, JSDoc, Rustdoc)
• Commit messages: French
• TODO comments: French
• Error messages: English (for technical compatibility)
• Log messages: English (for technical compatibility)

This ensures consistency across the team and facilitates collaboration.

Development Workflow

Context Management (Critical)

The conversation history is not reliable for long-term context. Project truth lives in files, not chat history.

Use /clear regularly, especially:

• Between different tasks
• Between design and implementation phases
• Between implementation and review

Sub-agents for Complex Work

For multi-step or specialized work, delegate to sub-agents explicitly:

"Use a sub-agent to perform a security review of this code."

Each sub-agent works with isolated context.

Progress Tracking (Mandatory)

When reaching a significant milestone or ~80% of session usage, provide a progress report:

ÉTAT D'AVANCEMENT – Mesh
Phase: <phase_name>

✔ Completed:
- ...

◻ In Progress:
- ...

✖ To Do:
- ...

Risks/Blockers:
- ...

Next Recommended Action:
- ...

Deployment

See docs/deployment.md for Docker Compose setup, environment variables, and infrastructure requirements.

Key components:

• mesh-server (FastAPI + WebSocket)
• coturn (TURN server for NAT traversal fallback)
• gotify (notification server)
• Reverse proxy with TLS (Caddy or Nginx)

Key Documentation References

• docs/AGENT.md - Rust agent architecture and implementation guide
• docs/security.md - Complete security model
• docs/protocol_events_v_2.md - WebSocket event protocol
• docs/signaling_v_2.md - WebRTC signaling and QUIC P2P strategy
• docs/deployment.md - Deployment architecture

Hierarchical CLAUDE.md Files

This root CLAUDE.md defines global vision and common rules.

Component-specific CLAUDE.md files (in server/, agent/, client/, infra/) provide local context and specific rules but must never contradict this root file.

Always consult the nearest CLAUDE.md first, then defer to this root file for global rules.

---

Core Principle: The truth of the Mesh project is in the files. The conversation is only a temporary tool.