From 013499a664f98e5240848af1c89bd98f4ba845b8 Mon Sep 17 00:00:00 2001 From: gilles soulier Date: Mon, 5 Jan 2026 13:19:11 +0100 Subject: [PATCH] Actualiser README.md --- README.md | 285 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) diff --git a/README.md b/README.md index 415846e..eb7289c 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,287 @@ +<<<<<<< HEAD # mesh +======= + + +# Mesh + +A self-hosted P2P communication platform for small teams (2-4 people). + +[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/) +[![React](https://img.shields.io/badge/React-18-61DAFB.svg)](https://reactjs.org/) +[![Rust](https://img.shields.io/badge/Rust-stable-orange.svg)](https://www.rust-lang.org/) +[![License](https://img.shields.io/badge/License-TBD-lightgrey.svg)](LICENSE) + +**Status**: 75% MVP Complete +- Server: 85% (Auth, Rooms, WebSocket, WebRTC signaling, Gotify notifications) +- Client: 90% (Auth, Rooms, Chat, WebRTC audio/video/screen, UX polish) +- Agent: 0% (Not started - Rust P2P agent for file/terminal sharing) + +## Features + +### ✅ Implemented (MVP Ready) + +- **Authentication**: JWT-based user registration and login +- **Rooms**: Create, join, and manage team rooms +- **Chat**: Real-time text messaging with room-based organization +- **Audio/Video Calls**: Direct P2P WebRTC connections (browser-to-browser) +- **Screen Sharing**: Share your screen with team members via WebRTC +- **Connection Quality**: Visual indicators for WebRTC connection status +- **Audio Levels**: Speaking indicators for active participants +- **Push Notifications**: Gotify integration for offline users (chat messages + incoming calls) +- **Toast Notifications**: In-app user feedback system + +### 🚧 Planned (Future) + +- **File/Folder Sharing**: P2P file transfers via QUIC (requires Rust agent) +- **Terminal Sharing**: Preview and control remote terminal sessions (requires Rust agent) +- **Mobile Apps**: iOS/Android native apps with deep linking + +## Architecture + +Mesh uses a **three-plane architecture**: + +### Control Plane (Mesh Server - Python) +- User authentication & authorization +- Room management & ACL +- Capability token issuance (short TTL: 60-180s) +- WebRTC signaling +- P2P session orchestration +- Gotify notifications + +### Media Plane (Web Client - WebRTC) +- Direct browser-to-browser audio/video/screen sharing +- No server-side media processing + +### Data Plane (Desktop Agent - Rust/QUIC) +- Peer-to-peer file and folder transfers +- Terminal/SSH session streaming +- Minimal server load (server never handles heavy data) + +## Project Structure + +``` +mesh/ +├── server/ # Python FastAPI server (control plane) +├── client/ # React/TypeScript web app (UI + WebRTC) +├── agent/ # Rust desktop agent (QUIC data plane) +├── infra/ # Docker compose & deployment configs +├── docs/ # Documentation +└── scripts/ # Development scripts +``` + +## Quick Start + +### Server (Python) + +```bash +cd server +python -m venv venv +source venv/bin/activate # or venv\Scripts\activate on Windows +pip install -r requirements.txt +cp .env.example .env +# Edit .env with your configuration +python -m uvicorn src.main:app --reload +``` + +Server runs on http://localhost:8000 + +### Client (React/TypeScript) + +```bash +cd client +npm install +npm run dev +``` + +Client runs on http://localhost:3000 + +### Agent (Rust) + +```bash +cd agent +cargo build +cargo run +``` + +The agent will create a config file at: +- Linux: `~/.config/mesh/agent.toml` +- macOS: `~/Library/Application Support/Mesh/agent.toml` +- Windows: `%APPDATA%\Mesh\agent.toml` + +## Development + +### Pre-commit Hooks + +Install pre-commit hooks to enforce traceability headers: + +```bash +pip install pre-commit +pre-commit install +pre-commit run --all-files +``` + +### Code Quality + +All new files must include a traceability header: + +**Python example:** +```python +# Created by: YourName +# Date: 2026-01-01 +# Purpose: Brief description +# Refs: CLAUDE.md +``` + +**Rust example:** +```rust +// Created by: YourName +// Date: 2026-01-01 +// Purpose: Brief description +// Refs: CLAUDE.md +``` + +**TypeScript example:** +```typescript +// Created by: YourName +// Date: 2026-01-01 +// Purpose: Brief description +// Refs: CLAUDE.md +``` + +VS Code snippets are available in [.vscode/mesh.code-snippets](.vscode/mesh.code-snippets). Use `mesh-header-*` to insert headers. + +## Documentation + +### Main Guides +- [CLAUDE.md](CLAUDE.md) - Main project guide for Claude Code +- [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Complete project overview with metrics and chronology +- [DEVELOPMENT.md](DEVELOPMENT.md) - Development progress tracking with checkboxes +- [TODO.md](TODO.md) - Task list and backlog + +### Session Progress Reports +- [PROGRESS_GOTIFY_2026-01-04.md](PROGRESS_GOTIFY_2026-01-04.md) - Gotify integration session +- [PROGRESS_UX_IMPROVEMENTS_2026-01-03.md](PROGRESS_UX_IMPROVEMENTS_2026-01-03.md) - UX polish session +- [PROGRESS_WEBRTC_2026-01-03.md](PROGRESS_WEBRTC_2026-01-03.md) - WebRTC implementation session + +### Technical Documentation +- [docs/AGENT.md](docs/AGENT.md) - Agent architecture and implementation +- [docs/security.md](docs/security.md) - Security model and requirements +- [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 strategy +- [docs/deployment.md](docs/deployment.md) - Deployment architecture +- [docs/tooling_precommit_vscode_snippets.md](docs/tooling_precommit_vscode_snippets.md) - Development tooling + +### Feature-Specific Documentation +- [GOTIFY_INTEGRATION.md](GOTIFY_INTEGRATION.md) - Complete Gotify push notification setup and usage +- [TESTING_WEBRTC.md](TESTING_WEBRTC.md) - WebRTC testing guide and scenarios + +### Component-Specific Guides +- [server/CLAUDE.md](server/CLAUDE.md) - Server development guide +- [client/CLAUDE.md](client/CLAUDE.md) - Client development guide +- [agent/CLAUDE.md](agent/CLAUDE.md) - Agent development guide +- [infra/CLAUDE.md](infra/CLAUDE.md) - Infrastructure guide + +## Tech Stack + +**Server:** +- Python 3.12+ +- FastAPI +- WebSocket +- JWT authentication +- SQLAlchemy + +**Client:** +- React 18 +- TypeScript +- Vite +- Zustand (state management) +- WebRTC (getUserMedia, RTCPeerConnection, getDisplayMedia) +- Monokai dark theme + +**Agent:** +- Rust (stable) +- tokio (async runtime) +- quinn (QUIC) +- portable-pty (terminal) +- tracing (logging) + +## Security + +- All P2P actions require server-issued capability tokens (60-180s TTL) +- Terminal sharing is preview-only by default +- Terminal control is explicit and server-arbitrated +- Secrets (SSH keys, passwords) never leave the local machine +- WebRTC uses native DTLS/SRTP encryption +- QUIC uses TLS 1.3 + +See [docs/security.md](docs/security.md) for complete security model. + +## Testing + +### Server Tests + +```bash +cd server +python -m pytest tests/ -v +``` + +**Current status**: 13/13 API tests passing + +### Gotify Integration Test + +```bash +cd server +python3 test_gotify.py +``` + +**Last test result**: ✅ Notification ID 78623 sent successfully + +### WebRTC Testing + +Manual testing guide available in [TESTING_WEBRTC.md](TESTING_WEBRTC.md) with scenarios for: +- Audio/video calls +- Screen sharing +- Connection quality indicators +- Multi-peer scenarios + +## Project Metrics + +- **Total Lines of Code**: ~8,250 +- **Total Files**: 47 +- **Components**: Server (Python), Client (React/TS), Agent (Rust - not started) +- **Development Sessions**: 4 (Jan 2-4, 2026) +- **Documentation Files**: 15+ + +## Deployment + +See [docs/deployment.md](docs/deployment.md) for Docker Compose setup and production deployment instructions. + +**Key components:** +- mesh-server (FastAPI) +- coturn (TURN server) +- gotify (notifications) +- Reverse proxy with TLS (Caddy/Nginx) + +## License + +To be determined. + +## Contributing + +1. Read [CLAUDE.md](CLAUDE.md) for project guidelines +2. Install pre-commit hooks +3. Follow the traceability header convention +4. Work in short, controlled iterations +5. Use `/clear` between different tasks + +--- + +**Core Principle**: The truth of the Mesh project is in the files. The conversation is only a temporary tool. +>>>>>>> 99ee4a1 (first)