Actualiser README.md
This commit is contained in:
285
README.md
285
README.md
@@ -1,2 +1,287 @@
|
||||
<<<<<<< HEAD
|
||||
# mesh
|
||||
|
||||
=======
|
||||
<!--
|
||||
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.
|
||||
>>>>>>> 99ee4a1 (first)
|
||||
|
||||
Reference in New Issue
Block a user