diff --git a/README.md b/README.md deleted file mode 100644 index eb7289c..0000000 --- a/README.md +++ /dev/null @@ -1,287 +0,0 @@ -<<<<<<< HEAD -# mesh - -======= - - -# Mesh - -A self-hosted P2P communication platform for small teams (2-4 people). - -[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/) -[![React](https://img.shields.io/badge/React-18-61DAFB.svg)](https://reactjs.org/) -[![Rust](https://img.shields.io/badge/Rust-stable-orange.svg)](https://www.rust-lang.org/) -[![License](https://img.shields.io/badge/License-TBD-lightgrey.svg)](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)