gilles/mesh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mesh/README.md
Gilles Soulier 1d177e96a6 first
2026-01-05 13:20:54 +01:00

7.7 KiB
Raw Permalink Blame History

Mesh

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

Python React Rust 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)

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

Session Progress Reports

Technical Documentation

Feature-Specific Documentation

Component-Specific Guides

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.

Reference in New Issue View Git Blame Copy Permalink