mesh/README.md

Mesh

A self-hosted P2P communication platform for small teams (2-4 people).

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)

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)

cd client
npm install
npm run dev

Client runs on http://localhost:3000

Agent (Rust)

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:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Code Quality

All new files must include a traceability header:

Python example:

# Created by: YourName
# Date: 2026-01-01
# Purpose: Brief description
# Refs: CLAUDE.md

Rust example:

// Created by: YourName
// Date: 2026-01-01
// Purpose: Brief description
// Refs: CLAUDE.md

TypeScript example:

// Created by: YourName
// Date: 2026-01-01
// Purpose: Brief description
// Refs: CLAUDE.md

VS Code snippets are available in .vscode/mesh.code-snippets. Use mesh-header-* to insert headers.

Documentation

Main Guides

• CLAUDE.md - Main project guide for Claude Code
• PROJECT_SUMMARY.md - Complete project overview with metrics and chronology
• DEVELOPMENT.md - Development progress tracking with checkboxes
• TODO.md - Task list and backlog

Session Progress Reports

• PROGRESS_GOTIFY_2026-01-04.md - Gotify integration session
• PROGRESS_UX_IMPROVEMENTS_2026-01-03.md - UX polish session
• PROGRESS_WEBRTC_2026-01-03.md - WebRTC implementation session

Technical Documentation

• docs/AGENT.md - Agent architecture and implementation
• docs/security.md - Security model and requirements
• docs/protocol_events_v_2.md - WebSocket event protocol
• docs/signaling_v_2.md - WebRTC signaling and QUIC strategy
• docs/deployment.md - Deployment architecture
• docs/tooling_precommit_vscode_snippets.md - Development tooling

Feature-Specific Documentation

• GOTIFY_INTEGRATION.md - Complete Gotify push notification setup and usage
• TESTING_WEBRTC.md - WebRTC testing guide and scenarios

Component-Specific Guides

• server/CLAUDE.md - Server development guide
• client/CLAUDE.md - Client development guide
• agent/CLAUDE.md - Agent development guide
• 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 for complete security model.

Testing

Server Tests

cd server
python -m pytest tests/ -v

Current status: 13/13 API tests passing

Gotify Integration Test

cd server
python3 test_gotify.py

Last test result: ✅ Notification ID 78623 sent successfully

WebRTC Testing

Manual testing guide available in 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 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 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.