# Mesh A self-hosted P2P communication platform for small teams (2-4 people). [](https://www.python.org/downloads/) [](https://reactjs.org/) [](https://www.rust-lang.org/) [](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.