first

2026-01-05 13:13:08 +01:00
parent 8e14adafc6
commit 1d177e96a6
149 changed files with 29541 additions and 1 deletions
@@ -0,0 +1,211 @@
+# 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.