# 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](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](docs/protocol_events_v_2.md) and [docs/signaling_v_2.md](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:**
```rust
// Created by: YourName
// Date: 2026-01-01
// Purpose: QUIC endpoint management for P2P sessions
// Refs: protocol_events_v_2.md
```

**Python example:**
```python
# Created by: YourName
# Date: 2026-01-01
# Purpose: WebSocket event router
# Refs: protocol_events_v_2.md
```

See [docs/tooling_precommit_vscode_snippets.md](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](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](docs/AGENT.md) - Rust agent architecture and implementation guide
- [docs/security.md](docs/security.md) - Complete security model
- [docs/protocol_events_v_2.md](docs/protocol_events_v_2.md) - WebSocket event protocol
- [docs/signaling_v_2.md](docs/signaling_v_2.md) - WebRTC signaling and QUIC P2P strategy
- [docs/deployment.md](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.