Michael Mainguy
c1503d959e
Implement comprehensive feature toggle system allowing menu options and features to be controlled via JSON configuration fetched from API endpoint or static files. Core System: - Create FeatureConfig type system with page, feature, and limit-based flags - Add React Context (FeatureProvider) that fetches from /api/user/features - Implement custom hooks (useFeatures, useIsFeatureEnabled, useFeatureLimit, etc.) - Default config disables everything except home page Integration: - Update PageHeader to filter menu items based on page flags - Add ProtectedRoute component to guard routes - Update VR menu to conditionally render items based on feature flags - Update CreateDiagramModal to enable/disable options (private, encrypted, invite) - Update ManageDiagramsModal to use configurable maxDiagrams limit Configuration Files: - Add static JSON files for local testing (none, free, basic, pro tiers) - Add dev proxy for /api/user/features endpoint - Include README with testing instructions Updates: - Complete CLAUDE.md naming conventions section - Version bump to 0.0.8-27 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
137 lines
6.1 KiB
Markdown
137 lines
6.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is "immersive" - a WebXR/VR diagramming application built with BabylonJS and React. It allows users to create and interact with 3D diagrams in both standard web browsers and VR environments, with real-time collaboration via PouchDB sync.
|
|
|
|
## Build and Development Commands
|
|
|
|
### Development
|
|
- `npm run dev` - Start Vite dev server on port 3001 (DO NOT USE per user instructions)
|
|
- `npm run build` - Build production bundle (includes version bump)
|
|
- `npm run preview` - Preview production build on port 3001
|
|
- `npm test` - Run tests with Vitest
|
|
- `npm run socket` - Start WebSocket server for collaboration (port 8080)
|
|
- `npm run serverBuild` - Compile TypeScript server code
|
|
- `npm run havok` - Copy Havok physics WASM files to Vite deps
|
|
|
|
### Testing
|
|
- Run all tests: `npm test`
|
|
- No single test command is configured; tests use Vitest
|
|
|
|
## Architecture
|
|
|
|
### Core Technologies
|
|
- **BabylonJS 8.x**: 3D engine with WebXR support and Havok physics
|
|
- **React + Mantine**: UI framework for 2D interface and settings
|
|
- **PouchDB**: Client-side database with CouchDB sync for collaboration
|
|
- **Auth0**: Authentication provider
|
|
- **Vite**: Build tool and dev server
|
|
|
|
### Key Architecture Patterns
|
|
|
|
#### Singleton Scene Management
|
|
The application uses a singleton pattern for the BabylonJS Scene via `DefaultScene` (src/defaultScene.ts). Always access the scene through `DefaultScene.Scene` rather than creating new instances.
|
|
|
|
#### Observable-Based Event System
|
|
The application heavily uses BabylonJS Observables for event handling:
|
|
- **DiagramManager.onDiagramEventObservable**: Central hub for diagram entity changes
|
|
- **DiagramManager.onUserEventObservable**: User position/state updates for multiplayer
|
|
- **AppConfig.onConfigChangedObservable**: Application settings changes
|
|
- **controllerObservable**: VR controller input events
|
|
|
|
Event observers use a mask system (`DiagramEventObserverMask`) to distinguish:
|
|
- `FROM_DB`: Events coming from database sync (shouldn't trigger database writes)
|
|
- `TO_DB`: Events that should be persisted to database
|
|
|
|
#### Diagram Entity System
|
|
All 3D objects in the scene are represented by `DiagramEntity` types (src/diagram/types/diagramEntity.ts):
|
|
- Entities have a template reference (e.g., `#image-template`)
|
|
- Managed by `DiagramManager` which maintains a Map of `DiagramObject` instances
|
|
- Changes propagate through the Observable system to database and other clients
|
|
|
|
#### VR Controller Architecture
|
|
Controllers inherit from `AbstractController` with specialized implementations:
|
|
- `LeftController`: Menu interactions, navigation
|
|
- `RightController`: Object manipulation, selection
|
|
- Controllers communicate via `controllerObservable` with `ControllerEvent` messages
|
|
- `Rigplatform` manages the player rig and handles locomotion
|
|
|
|
#### Database & Sync
|
|
- `PouchdbPersistenceManager` (src/integration/database/pouchdbPersistenceManager.ts) handles all persistence
|
|
- Supports optional encryption via `Encryption` class
|
|
- Syncs to remote CouchDB via proxy (configured in vite.config.ts)
|
|
- URL pattern `/db/public/:db` or `/db/private/:db` determines database name
|
|
- Uses `presence.ts` for broadcasting user positions over WebSocket
|
|
|
|
### Project Structure
|
|
- `src/vrcore/`: Engine initialization and core VR setup
|
|
- `src/controllers/`: VR controller implementations and input handling
|
|
- `src/diagram/`: 3D diagram entities, management, and scene interaction
|
|
- `src/integration/`: Database sync, encryption, and presence system
|
|
- `src/menus/`: In-VR 3D menus (not React components)
|
|
- `src/objects/`: Reusable 3D objects (buttons, handles, avatars)
|
|
- `src/react/`: React UI components for 2D interface
|
|
- `src/util/`: Shared utilities and configuration
|
|
- `server/`: WebSocket server for real-time presence
|
|
|
|
### Configuration System
|
|
Two configuration systems exist (being migrated):
|
|
1. **AppConfig class** (src/util/appConfig.ts): Observable-based config with typed properties
|
|
2. **ConfigType** (bottom of appConfig.ts): Legacy localStorage-based config
|
|
|
|
Settings include snapping values, physics toggles, fly mode, and turn snap angles.
|
|
|
|
## Important Development Notes
|
|
|
|
### Proxy Configuration
|
|
The dev and preview servers proxy certain routes to production:
|
|
- `/sync/*` - Database sync endpoint
|
|
- `/create-db` - Database creation
|
|
- `/api/images` - Image uploads
|
|
|
|
### Physics System
|
|
- Uses Havok physics engine (requires WASM file via `npm run havok`)
|
|
- Physics can be enabled/disabled via AppConfig
|
|
- `customPhysics.ts` provides helper functions
|
|
|
|
### WebGPU Support
|
|
The engine initializer supports both WebGL and WebGPU backends via the `useWebGpu` parameter.
|
|
|
|
### Encryption
|
|
Databases can be optionally encrypted. The `Encryption` class handles AES encryption with password-derived keys. Salt is stored in metadata document.
|
|
|
|
### Environment Variables
|
|
- `VITE_USER_ENDPOINT`: User authentication endpoint
|
|
- `VITE_SYNCDB_ENDPOINT`: Remote database sync endpoint
|
|
|
|
Check `.env.local` for local configuration.
|
|
|
|
## Naming Conventions
|
|
|
|
### Tool and Material Naming
|
|
|
|
**Material Names:** Materials follow the pattern `material-{color}` where `{color}` is the hex color string (e.g., `material-#ff0000` for red).
|
|
|
|
**Tool Mesh Names:** Tools use the pattern `tool-{toolType}-{color}`:
|
|
- Example: `tool-BOX-#ff0000` (red box tool)
|
|
- ToolTypes: `BOX`, `SPHERE`, `CYLINDER`, `CONE`, `PLANE`, `PERSON`
|
|
|
|
**Tool Instance Names:** `tool-instance-{toolType}-{color}` (e.g., `tool-instance-BOX-#ff0000`)
|
|
|
|
**Implementation details:**
|
|
- 16 predefined toolbox colors (see docs/NAMING_CONVENTIONS.md)
|
|
- Materials created in `src/toolbox/functions/buildColor.ts`
|
|
- Tool meshes created in `src/toolbox/functions/buildTool.ts`
|
|
- When extracting colors from materials, use: `emissiveColor || diffuseColor` (priority order)
|
|
|
|
### Rendering Modes
|
|
|
|
Three rendering modes affect material properties:
|
|
1. **Lightmap with Lighting**: Uses `diffuseColor` + `lightmapTexture` (expensive)
|
|
2. **Unlit with Emissive Texture** (default): Uses `emissiveColor` + `emissiveTexture` (lightmap)
|
|
3. **Flat Emissive**: Uses only `emissiveColor` (fastest)
|
|
|
|
See `src/util/renderingMode.ts` and `src/util/lightmapGenerator.ts` for implementation. |