283 lines
7.7 KiB
Markdown
283 lines
7.7 KiB
Markdown
<!--
|
|
Created by: Claude
|
|
Date: 2026-01-01
|
|
Purpose: Main README for Mesh project
|
|
Refs: CLAUDE.md
|
|
-->
|
|
|
|
# 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.
|