212 lines
6.8 KiB
Markdown
212 lines
6.8 KiB
Markdown
# 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.
|