GraphWiz-XR

Modern VR/Social platform - A complete rewrite of the Hubs ecosystem using TypeScript + Rust.

Vision

GraphWiz-XR delivers high-fidelity, browser-based virtual reality without installation barriers. Built with modern technologies for maximum performance and scalability.

Screenshot

Interactive Multiplayer Demo - Click objects to interact, changes sync across all players in real-time

Technology Stack

Frontend

• TypeScript - Type-safe development
• React 18 - UI framework
• React Three Fiber - Declarative 3D rendering
• Three.js r160+ - 3D engine with WebGPU preparation
• Vite - Fast build tool

Backend

• Rust - High-performance microservices
• Actix-Web - Web framework
• SeaORM - Database ORM
• PostgreSQL - Primary database

Networking

• WebTransport - Next-gen real-time transport (HTTP/3)
• gRPC - Structured RPC framework
• Protobuf - Efficient serialization

Editor

• Tauri - Lightweight desktop app framework
• Rust - Native performance
• React - Shared UI with client

Project Structure

graphwiz-xr/
├── packages/
│   ├── clients/           # TypeScript frontend apps
│   ├── services/          # Rust backend services
│   ├── editors/           # Tauri desktop apps
│   ├── shared/            # Shared protocol/types
│   └── deploy/            # Deployment configs
├── Cargo.toml             # Rust workspace
├── package.json           # Node workspace
└── turbo.json             # Build pipeline

Quick Start

Prerequisites

• Node.js 20+
• Rust 1.75+
• pnpm 8+
• Docker & Docker Compose (for local services)

Installation

First, ensure you have pnpm installed:

# Install pnpm using npm (comes with Node.js)
npm install -g pnpm@8

# Or using curl
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Or using Homebrew (macOS/Linux)
brew install pnpm

# Verify installation
pnpm --version

Development with Docker

The easiest way to start development is using Docker Compose:

# Start all services (PostgreSQL, Redis, Core API, Hub Client)
docker-compose -f packages/deploy/docker-compose.dev.yml up -d

# View logs
docker-compose -f packages/deploy/docker-compose.dev.yml logs -f hub-client core-api

# Stop all services
docker-compose -f packages/deploy/docker-compose.dev.yml down

Access Points

• Hub Client: http://localhost:5173
• Core API: http://localhost:8000
• Storage Service: http://localhost:8005
• Adminer (DB): http://localhost:8080

Manual Development

# Install dependencies
pnpm install

# Generate protocol buffers
cd packages/shared/protocol
pnpm build:proto

# Run tests
pnpm test

# Type checking
pnpm check

# Build
pnpm build

📚 Documentation & Planning

Development Planning

• NEXT_STEPS.md - Detailed immediate action items, quick wins, and task breakdowns
• ROADMAP.md - Long-term development roadmap and feature planning
• IMPLEMENTATION_STATUS.md - Detailed implementation progress tracking

Architecture Documentation

• docs/arc42.md - Architecture documentation (arc42 template)
• docs/INTENTION.md - Project intentions and design principles

Quick Reference Guides

• NETWORKING_IMPLEMENTATION_SUMMARY.md - WebSocket implementation details
• PHYSICS_ENGINE_INTEGRATION.md - Physics system documentation
• VOICE_CHAT_IMPLEMENTATION_SUMMARY.md - Voice chat system

Test Reports

• PHYSICS_TEST_REPORT.md - Physics system test results
• FULL_STACK_INTEGRATION_TEST_REPORT.md - Integration test results

Architecture

Components

1. Hub Client - Main VR client (TypeScript + R3F)
2. Admin Client - Dashboard for management
3. Reticulum - Backend microservices (Rust)
   • Core - Shared utilities and models
   • Auth - Authentication & authorization
   • Hub - Room/session management
   • Presence - WebSocket signaling
   • Storage - Asset upload/download service
   • SFU - WebRTC media routing
4. Spoke - Scene editor (Tauri + React)

Protocol

The system uses a custom protocol built on:

• gRPC - Reliable operations (auth, room management)
• WebTransport - Real-time data (positions, voice)
• Protobuf - Message serialization

See packages/shared/protocol/ for protocol definitions.

Performance Targets

• Backend: P50 < 10ms, P99 < 50ms latency
• Frontend: 60 FPS desktop, 90 FPS VR
• Network: < 5KB/s per client (positions)
• Bundle: < 2MB initial load

Contributing

This project follows the "Performance-Hybrid" architecture:

• TypeScript for flexible UI development
• Rust for maximum backend performance
• React for shared UI code across client/editor
• Web-first - browser compatibility is paramount

License

MPL-2.0 - See LICENSE file for details

Implementation Status

✅ Phase 1: Foundation (COMPLETE)

Goal: Establish project infrastructure and tooling

• Configure monorepo build system (Turborepo)
• Set up shared TypeScript configuration
• Configure Rust workspace with Cargo
• Establish CI/CD pipeline (GitHub Actions)
• Set up development Docker Compose with hot-reload
• Configure ESLint, Prettier, and Rust tooling
• Create shared protocol definitions (Protobuf)
• packages/shared/types - Shared TypeScript types
• packages/shared/protocol - gRPC + WebTransport protocol buffers
• packages/services/core - Rust utilities and common code
• packages/clients/ui-kit - React component library

Deliverables: ✅ Working monorepo with build, test, and dev tooling Test Coverage: 138 tests passing (100% pass rate)

---

✅ Phase 2: Core Services (COMPLETE)

Goal: Build backend microservices (Rust replacement for Reticulum)

2.1 Authentication Service ✅

• Email magic link authentication
• JWT token generation and validation
• OAuth integration (GitHub, Google, Discord)
• Session management with Redis
• Account creation and profile management
• Admin role management
• Password hashing with bcrypt
• Database migrations

2.2 Hub Service ✅

• Room creation and configuration
• Room URL generation and routing
• Room listing and discovery
• Entity spawning in rooms
• Entity updates (position, rotation, components)
• Room-to-entity relationships
• Comprehensive test coverage

2.3 Storage Service ✅

• Multipart file upload with progress tracking
• File validation (magic bytes, size limits, MIME types)
• Asset metadata storage (PostgreSQL)
• Asset listing with pagination and filtering
• File download and serving
• Asset deletion with ownership verification
• Storage backend abstraction (S3-ready)
• Frontend React components (Uploader, Browser, Card)
• Drag-and-drop upload interface
• Supported types: Models (GLB/GLTF), Textures, Audio, Video

2.4 Presence Service ✅

• WebSocket connection management
• Room-based broadcasting
• Connection lifecycle (add/remove)
• Binary and text message handling
• Ping/pong handling
• Graceful disconnect handling
• Connection statistics

2.5 SFU (Selective Forwarding Unit) Service ✅

• Room creation and management
• Peer connection tracking
• WebRTC offer/answer handling
• ICE candidate handling
• RTP packet forwarding
• Simulcast layer management
• Room capacity limits

Deliverables: ✅ Five core Rust services with comprehensive APIs

---

🟡 Phase 3: Real-Time Networking (IN PROGRESS)

Goal: Build WebRTC SFU and signaling

3.1 SFU Service ✅ COMPLETE

• WebRTC Selective Forwarding Unit
• Audio/video routing
• Simulcast support
• Transport negotiation (ICE, DTLS, SRTP)
• Multi-user conference management

3.2 Client Networking ✅ COMPLETE

• WebSocket client with auto-reconnect
• Binary message serialization/deserialization
• Position/rotation synchronization
• Entity spawn/despawn networking
• Position interpolation for smooth movement
• Network system for ECS integration

Deliverables: ✅ Rust SFU service + TypeScript client networking

---

🟡 Phase 4: Hub Client Development (IN PROGRESS)

Goal: Build main VR client (TypeScript + R3F replacement for hubs)

4.1 Core Client Foundation ✅ COMPLETE

• React 18 + Vite setup
• React Three Fiber scene initialization
• Camera and controls system
• Asset loading pipeline (GLTF, textures)
• Performance monitoring

4.2 ECS Architecture ✅ COMPLETE

• Complete ECS (Entity Component System)
• Components: Transform, Physics, Collider, Audio, Animation, Model, Light, Camera, NetworkSync, Interactable, Billboard, Particle
• Systems: Transform, Physics, Animation, Audio, Billboard
• Game loop with delta time

4.3 Multiuser Networking ✅ COMPLETE

• WebSocket client implementation
• Networked avatar system
• Interpolation and prediction for smooth movement
• Network quality indicators

4.4 XR Input System ✅ COMPLETE

• WebXR controller input
• Button press handling
• Thumbstick tracking
• Haptic feedback
• Pose tracking and updates

4.5 Physics Engine ✅ COMPLETE

• Physics body components
• Collision detection
• Physics simulation with cannon-es
• Comprehensive physics tests (31 tests)

4.6 Voice Chat System ✅ COMPLETE

• WebRTC audio capture
• Voice activity detection
• Audio mixing and spatialization
• Mute/unmute controls
• Voice chat client implementation

4.7 Scene & Interaction Systems ✅ NEW FEATURES (2026-01-07)

• Text chat UI - Real-time text messaging
• Emoji reactions system - 3D floating emojis with network sync (32 emojis)
• User settings panel - 18 settings across 4 categories
  • Audio settings (volume, mic, push-to-talk)
  • Graphics settings (quality, shadows, VSync)
  • Network settings (bitrate, codec)
  • Account settings (display name, status)
• Avatar customization system - Complete avatar configurator with 3D preview
  • Backend API with 5 endpoints
  • 5 body types (Human, Robot, Alien, Animal, Abstract)
  • Live 3D preview with orbit controls
  • Color customization (primary/secondary)
  • Height adjustment (0.5m - 3.0m)
  • Custom model support
• Interactive multiplayer demo scene - Real-time synchronized objects (NEW!)
  • 3 clickable buttons with state sync (toggle on/off)
  • 2 collectible gems with respawn (5 seconds)
  • Toggleable light switch affecting scene
  • Hover effects (scaling, color brightening)
  • ENTITY_UPDATE message type for state synchronization
  • Timestamp-based conflict resolution
  • Visual feedback (rotation, glow effects, animations)
• Media playing system - Video and audio playback with network synchronization (NEW 2026-01-05)
  • 3D video screen entity with shared playback control
  • Audio spatialization for immersive experience
  • Network sync across all players (play/pause, seek)
  • Support for video and audio media formats
• Drawing tools - Multi-user drawing system (NEW 2026-01-06)
  • Drawing canvas component with brush controls
  • Drawing tools panel with color/size options
  • Network-synchronized drawing across clients
  • Undo/redo functionality
• Portal system - Room-to-room teleportation (NEW 2026-01-06)
  • 3D portal entities with visual effects
  • Room linking and configuration
  • Teleportation on walk-through
  • Seamless room transitions
• Grab and move objects - Physics-based object interaction (NEW 2026-01-06)
  • Multiplayer object grabbing system with physics
  • Real-time position sync during grab
  • Release physics with proper velocity
  • Collision detection and response
• Gesture recognition (in progress)

Deliverables: ✅ VR client with chat, emoji reactions, settings, avatar customization, interactive multiplayer demo, media playback, drawing tools, portals, and object grabbing (NEW 2026-01-07)

---

🟡 Phase 5: Admin & Moderation (IN PROGRESS)

Goal: Build admin dashboard and moderation tools

5.1 Admin Client 🟡 FRONTEND COMPLETE

• Dashboard with service status monitoring
• System statistics display (rooms, users, entities, uptime)
• User management interface
  • List users with pagination
  • Ban/unban users
  • Update user roles
• Room management interface
  • List rooms with pagination
  • Edit room configuration
  • Close and delete rooms
• Room persistence interface
  • Load room state by ID
  • Save room name and description
  • Clear room state
• Historical metrics visualization
  • Time range selection (1h - 7 days)
  • Summary statistics (avg/max rooms, users, latency)
  • Graph visualization for metrics
• System logs viewer
  • Real-time logs from all services
  • Filter by service, level, time
  • Export logs functionality
• Service control
  • Restart individual services
  • Restart all services
  • Emergency shutdown
• Asset library management
• Real-time analytics dashboard

5.2 Moderation Features 🔴 NOT STARTED

• In-room moderation tools
• Kick/ban functionality
• Mute system
• Room locking
• Reporting system

---

🔴 Phase 6: Spoke Editor (PENDING)

Goal: Build scene editor (Tauri replacement for Spoke)

• Tauri + React application setup
• Three.js editor viewport
• Object hierarchy panel
• Transform tools (move, rotate, scale)
• Lighting system editor
• Material editor
• Scene export functionality

---

🔴 Phase 7-8: Advanced Features & Production (PENDING)

Goal: Add differentiating features and production readiness

Advanced Features

• WebGPU rendering backend
• Performance optimization (LOD, instancing)
• Social features (friends, groups)
• Content marketplace
• Developer APIs

Production Readiness

• E2E test suite expansion
• Load testing for SFU
• Cross-browser compatibility testing
• VR headset testing
• Kubernetes deployment
• Monitoring and alerting
• Documentation completion

---

Current Status Summary

Last Updated: 2026-01-07

Overall Progress: ~74% Complete

Recent Updates (January 2026)

• ✅ Admin Dashboard Frontend: Complete admin client interface (NEW 2026-01-07)
  • Dashboard with real-time service health monitoring
  • User management (list, ban/unban, role assignment)
  • Room management (list, edit, close, delete)
  • Room persistence (save/load room state)
  • Historical metrics with time range selection and graphs
  • System logs viewer with filtering and export
  • Service controls (restart, shutdown)
  • Tab-based navigation for all admin functions
• ✅ Grab and Move Objects System: Physics-based object interaction (2026-01-06)
  • Multiplayer object grabbing with physics integration
  • Real-time position synchronization during grab
  • Release physics with proper velocity transfer
  • Collision detection and response during interactions
  • Cannon.js physics engine integration
• ✅ Portal System: Room-to-room teleportation (NEW 2026-01-06)
  • 3D portal entities with visual effects
  • Room linking configuration in backend
  • Teleportation on walk-through with smooth transitions
  • Portal state management and network sync
• ✅ Drawing Tools System: Multi-user drawing capabilities (NEW 2026-01-06)
  • DrawingCanvas component with brush controls
  • DrawingTools panel with color/size/stroke options
  • Network-synchronized drawing across all clients
  • Undo/redo functionality with history management
  • Drawing persistence in room state
• ✅ Media Playback System: Video and audio with network sync (NEW 2026-01-05)
  • 3D video screen entity with MediaPlayer component
  • Shared playback control (play/pause, seek, volume)
  • Audio spatialization for immersive 3D audio
  • Network synchronization across all connected players
  • MediaDemoScene for testing and demonstration
  • Support for multiple video/audio formats
• ✅ Interactive Multiplayer Demo Scene: Real-time synchronized demo objects (2026-01-02)
  • 3 Clickable Buttons - Click to toggle state, all players see changes instantly
  • 2 Collectible Gems - Click to collect, respawn after 5 seconds with glow effects
  • Toggleable Light Switch - Controls scene lighting, synchronized across all clients
  • Hover Effects - Objects scale up, brighten color when hovered
  • Network Sync - Uses ENTITY_UPDATE messages (type 21) for real-time state synchronization
  • Visual Feedback - Active objects rotate continuously, gems have particle glow effects
  • Conflict Resolution - Timestamp-based state resolution ensures consistency
• ✅ Strafe Movement Fixed: Corrected A/D strafe direction (inverted → working)
  • Fixed right vector calculation: [-cos(rotation), sin(rotation)]
  • A key now strafes left, D key strafes right correctly
  • Movement direction matches player's facing direction
• ✅ Multiplayer Visibility Fixed: Players consistently see each other
  • ENTITY_SPAWN handler now uses getMyClientId() for current client ID
  • Fixed closure issue causing myClientId to be null in message handlers
  • Added dual-check: skip if ownerId === myId OR entityId === myId
  • Each client correctly distinguishes local vs remote player entities
• ✅ Camera Controller: Smooth camera following system with orbit controls
  • Camera smoothly follows player at 5% lerp per frame
  • Fixed OrbitControls + manual camera positioning conflict
  • Damping enabled (0.05 factor) for buttery-smooth movement
  • Target follows player position with 10% lerp
• ✅ Player Movement System: WASD keyboard controls with network synchronization
  • Smooth position interpolation at 15% per frame
  • Position updates broadcast at 60 FPS
  • Real-time remote player position tracking with target positions
• ✅ Avatar Persistence & Customization: Complete avatar system with backend API
  • 5 body types (Human, Robot, Alien, Animal, Abstract)
  • Custom colors (primary/secondary) and height adjustment (0.5m - 3.0m)
  • Live 3D preview with orbit controls
  • PostgreSQL persistence with automatic avatar loading on connect

Recent Updates (December 2025)

• ✅ Storage Service Backend: Complete file upload/download service with validation, magic bytes checking, and PostgreSQL metadata storage
• ✅ Storage Service Frontend: React components with drag-drop upload, asset browser, and management UI
• ✅ Docker Integration: Storage service containerized with hot-reload support
• ✅ Asset Type Support: Models (GLB/GLTF), Textures (PNG/JPG), Audio (MP3/OGG), Video (MP4)
• ✅ Fixed Proto.js Browser Compatibility: Updated protobuf generation to use ES6 modules instead of CommonJS for browser compatibility
• ✅ Added Volume Mounts: Protocol and types packages now mounted as Docker volumes for hot-reload
• ✅ Test Suite: All 138 tests passing (100% pass rate)

✅ Fully Implemented (100%)

• Monorepo infrastructure with Turborepo
• CI/CD pipeline with GitHub Actions
• Docker development environment
• Protocol buffer definitions
• Authentication service (email, OAuth, magic links)
• Hub service (room & entity management)
• Storage service (file upload/download, asset management)
• Presence service (WebSocket signaling)
• SFU service (WebRTC media routing)
• Client ECS architecture
• Client networking layer
• XR input system
• Physics engine integration
• Voice chat system

🟡 Partially Implemented (50-90%)

• Hub client UI (core complete, most interactions done, gesture recognition pending)
• Testing infrastructure (138 tests passing, more coverage needed)
• Documentation (READMEs complete, API docs pending)
• Admin dashboard (frontend complete, moderation tools pending)

🔴 Not Started (0%)

• Admin dashboard
• Spoke editor
• Advanced social features
• Production deployment

Test Metrics

• Total Tests: 138 passing (100% pass rate)
• Coverage: Networking (95%), Physics (95%), Protocol (95%), XR (70%), ECS (70%)

---

Roadmap

A modern reimplementation of the Hubs ecosystem with TypeScript + Rust architecture.

Next Priorities (Q1 2026):

1. ✅ Complete client interaction systems (grab, throw, portals)
2. ✅ Implement text chat and emoji reactions
3. ✅ Add media playback (video, audio)
4. ✅ Build admin dashboard frontend
5. Implement in-room moderation tools (NEXT)
6. Build Spoke scene editor
7. Implement S3 backend for storage service
8. E2E testing and cross-browser compatibility

---

Technology Rationale

Why TypeScript + Rust?

Aspect	Hubs (Legacy)	GraphWiz-XR
Frontend	JavaScript + A-Frame	TypeScript + React Three Fiber
Backend	Elixir + Phoenix	Rust + Actix-Web
Performance	Good	Excellent (Rust zero-cost abstractions)
Type Safety	Partial (Elixir dynamic)	Complete (TS + Rust)
Bundle Size	Large (A-Frame deps)	Optimized (tree-shaking)
WebGPU	Not available	Ready for WebGPU migration
WebTransport	Custom implementation	Native HTTP/3 support

Architecture Improvements

• Microservices: Separate Rust services for better scalability
• WebTransport: Modern replacement for WebSocket for real-time data
• React Three Fiber: Declarative 3D with React ecosystem
• Shared Protocol: Protobuf definitions shared between TS and Rust

Acknowledgments

Built on the learnings from Hubs-Foundation while modernizing the architecture for next-generation performance.