# praveenkumar0031/3d-voxel-builder architecture

> Architecture diagram of the GitHub repository praveenkumar0031/3d-voxel-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/praveenkumar0031/3d-voxel-builder
- Repository: https://github.com/praveenkumar0031/3d-voxel-builder

## Overview

GesticStudio is a gesture-controlled, browser-based 3D voxel builder. Its main workflow is webcam hand tracking → gesture recognition and orbital-menu selection → SceneEngine voxel/scene operations, with authenticated scene saving and retrieval alongside account, dashboard, and history flows. The graph preserves documented effects and scene-management capabilities. Some connections are supported by README descriptions where implementation excerpts were unavailable; those evidence limits are noted by using the README only for documented relationships.

Main entry points: [`frontend/src/hooks/useGestureStateMachine.js`](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/hooks/useGestureStateMachine.js) (Gesture state machine), [`frontend/src/hooks/useVoxelArchitect.js`](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/hooks/useVoxelArchitect.js) (Builder lifecycle), [`backend/server.js`](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/server.js) (Express API server), [`backend/routes/scenes.js`](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/routes/scenes.js) (Scene routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Gesture interaction"]
  node_camera_source["Camera source<br/>[cameraSource.js]"]
  node_fsm["Gesture state machine"]
  node_gesture_shapes["Gesture predicates<br/>[gestures.js]"]
  node_overlay["Tracking overlay<br/>[overlayRenderer.js]"]
  node_event_bus["UI event bus<br/>[eventBus.js]"]
  node_orbital_sync["Menu state sync<br/>[orbitalMenuSync.js]"]
end

subgraph group_builder["Voxel builder"]
  node_architect["Builder lifecycle"]
  node_scene_engine["3D scene engine<br/>[SceneEngine.js]"]
  node_world_math["World and grid math<br/>[math.js]"]
end

subgraph group_product_ui["Application UI"]
  node_builder_page["Builder page<br/>[BuilderPage.jsx]"]
  node_orbital_menu["Orbital tool ring<br/>[OrbitalMenu.jsx]"]
  node_dashboard["Scene dashboard<br/>[Dashboard.jsx]"]
  node_history["Scene history<br/>[HistoryPage.jsx]"]
  node_landing["Public gallery<br/>[LandingPage.jsx]"]
end

subgraph group_accounts["Accounts and scenes"]
  node_auth_context["Authentication state<br/>[AuthContext.jsx]"]
  node_auth_api["Auth client<br/>[authApi.js]"]
  node_http_client["HTTP client<br/>[axios.js]"]
  node_scene_api["Scene client<br/>[scenesApi.js]"]
end

subgraph group_backend["API and persistence"]
  node_api_server["Express API server<br/>[server.js]"]
  node_auth_routes["Account routes<br/>[auth.js]"]
  node_scene_routes["Scene routes<br/>[scenes.js]"]
  node_auth_middleware["JWT authorization<br/>[auth.js]"]
  node_user_model[("User records<br/>[User.js]")]
  node_scene_model[("Scene records<br/>[Scene.js]")]
  node_db_connection[("MongoDB connection<br/>[db.js]")]
end

node_user(("Builder user"))
node_camera["Webcam tracking"]
node_mongo[("MongoDB")]

node_user -->|"provides hand motion"| node_camera
node_camera -.->|"supplies video"| node_camera_source
node_builder_page -.->|"starts builder"| node_architect
node_architect -.->|"selects tracking source"| node_camera_source
node_architect -->|"sets up gesture control"| node_fsm
node_architect -->|"creates scene engine"| node_scene_engine
node_fsm -->|"tests hand poses"| node_gesture_shapes
node_fsm -->|"draws tracking cues"| node_overlay
node_fsm -->|"dispatches scene operations"| node_scene_engine
node_fsm -->|"publishes menu events"| node_event_bus
node_fsm -->|"updates menu state"| node_orbital_sync
node_orbital_menu -->|"subscribes to events"| node_event_bus
node_orbital_menu -->|"reads menu state"| node_orbital_sync
node_scene_engine -->|"uses grid helpers"| node_world_math
node_fsm -->|"projects hand coordinates"| node_world_math
node_auth_context -->|"calls account operations"| node_auth_api
node_auth_context -->|"sets token and callback"| node_http_client
node_auth_api -->|"sends auth requests"| node_http_client
node_dashboard -->|"loads scene data"| node_scene_api
node_history -->|"loads scene history"| node_scene_api
node_landing -->|"loads public scenes"| node_scene_api
node_scene_api -->|"sends scene requests"| node_http_client
node_http_client -.->|"calls REST API"| node_api_server
node_api_server -->|"mounts auth routes"| node_auth_routes
node_api_server -->|"mounts scene routes"| node_scene_routes
node_api_server -->|"connects database"| node_db_connection
node_auth_routes -->|"reads and writes users"| node_user_model
node_auth_routes -->|"protects profile route"| node_auth_middleware
node_scene_routes -->|"guards scene routes"| node_auth_middleware
node_scene_routes -->|"reads and writes scenes"| node_scene_model
node_scene_routes -->|"uses user records"| node_user_model
node_db_connection -.->|"connects to"| node_mongo
node_user_model -.->|"persists users"| node_mongo
node_scene_model -.->|"persists scenes"| node_mongo

click node_builder_page "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/BuilderPage.jsx"
click node_architect "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/hooks/useVoxelArchitect.js"
click node_camera_source "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/engine/cameraSource.js"
click node_fsm "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/hooks/useGestureStateMachine.js"
click node_gesture_shapes "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/gestures.js"
click node_overlay "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/engine/overlayRenderer.js"
click node_event_bus "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/eventBus.js"
click node_orbital_sync "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/orbitalMenuSync.js"
click node_orbital_menu "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/components/OrbitalMenu/OrbitalMenu.jsx"
click node_scene_engine "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/engine/SceneEngine.js"
click node_world_math "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/math.js"
click node_auth_context "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/context/AuthContext.jsx"
click node_auth_api "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/api/authApi.js"
click node_http_client "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/api/axios.js"
click node_scene_api "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/api/scenesApi.js"
click node_dashboard "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/Dashboard.jsx"
click node_history "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/HistoryPage.jsx"
click node_landing "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/LandingPage.jsx"
click node_api_server "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/server.js"
click node_auth_routes "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/routes/auth.js"
click node_scene_routes "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/routes/scenes.js"
click node_auth_middleware "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/middleware/auth.js"
click node_user_model "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/models/User.js"
click node_scene_model "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/models/Scene.js"
click node_db_connection "https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/config/db.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_camera_source,node_fsm,node_gesture_shapes,node_overlay,node_event_bus,node_orbital_sync,node_user toneBlue
class node_architect,node_scene_engine,node_world_math,node_mongo toneAmber
class node_builder_page,node_orbital_menu,node_dashboard,node_history,node_landing toneMint
class node_auth_context,node_auth_api,node_http_client,node_scene_api toneRose
class node_api_server,node_auth_routes,node_scene_routes,node_auth_middleware,node_user_model,node_scene_model,node_db_connection,node_camera toneIndigo
```

## Components

### Gesture interaction

- [Camera source](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/engine/cameraSource.js): `frontend/src/engine/cameraSource.js`
- [Gesture state machine](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/hooks/useGestureStateMachine.js): `frontend/src/hooks/useGestureStateMachine.js`
- [Gesture predicates](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/gestures.js): `frontend/src/utils/gestures.js`
- [Tracking overlay](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/engine/overlayRenderer.js): `frontend/src/engine/overlayRenderer.js`
- [UI event bus](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/eventBus.js): `frontend/src/utils/eventBus.js`
- [Menu state sync](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/orbitalMenuSync.js): `frontend/src/utils/orbitalMenuSync.js`

### Voxel builder

- [Builder lifecycle](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/hooks/useVoxelArchitect.js): `frontend/src/hooks/useVoxelArchitect.js`
- [3D scene engine](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/engine/SceneEngine.js): `frontend/src/engine/SceneEngine.js`
- [World and grid math](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/utils/math.js): `frontend/src/utils/math.js`

### Application UI

- [Builder page](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/BuilderPage.jsx): `frontend/src/pages/BuilderPage.jsx`
- [Orbital tool ring](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/components/OrbitalMenu/OrbitalMenu.jsx): `frontend/src/components/OrbitalMenu/OrbitalMenu.jsx`
- [Scene dashboard](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Scene history](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/HistoryPage.jsx): `frontend/src/pages/HistoryPage.jsx`
- [Public gallery](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/pages/LandingPage.jsx): `frontend/src/pages/LandingPage.jsx`

### Accounts and scenes

- [Authentication state](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Auth client](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/api/authApi.js): `frontend/src/api/authApi.js`
- [HTTP client](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/api/axios.js): `frontend/src/api/axios.js`
- [Scene client](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/frontend/src/api/scenesApi.js): `frontend/src/api/scenesApi.js`

### API and persistence

- [Express API server](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/server.js): `backend/server.js`
- [Account routes](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/routes/auth.js): `backend/routes/auth.js`
- [Scene routes](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/routes/scenes.js): `backend/routes/scenes.js`
- [JWT authorization](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/middleware/auth.js): `backend/middleware/auth.js`
- [User records](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/models/User.js): `backend/models/User.js`
- [Scene records](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/models/Scene.js): `backend/models/Scene.js`
- [MongoDB connection](https://github.com/praveenkumar0031/3d-voxel-builder/blob/render/backend/config/db.js): `backend/config/db.js`

### Other components

- **Builder user**
- **Webcam tracking**
- **MongoDB**

## Connections

- Builder user → Webcam tracking: provides hand motion
- Webcam tracking → Camera source: supplies video
- Builder page → Builder lifecycle: starts builder
- Builder lifecycle → Camera source: selects tracking source (evidence: `frontend/src/hooks/useVoxelArchitect.js`)
- Builder lifecycle → Gesture state machine: sets up gesture control (evidence: `frontend/src/hooks/useVoxelArchitect.js`)
- Builder lifecycle → 3D scene engine: creates scene engine (evidence: `frontend/src/hooks/useVoxelArchitect.js`)
- Gesture state machine → Gesture predicates: tests hand poses (evidence: `frontend/src/hooks/useGestureStateMachine.js`)
- Gesture state machine → Tracking overlay: draws tracking cues (evidence: `frontend/src/hooks/useGestureStateMachine.js`)
- Gesture state machine → 3D scene engine: dispatches scene operations
- Gesture state machine → UI event bus: publishes menu events (evidence: `frontend/src/hooks/useGestureStateMachine.js`)
- Gesture state machine → Menu state sync: updates menu state (evidence: `frontend/src/hooks/useGestureStateMachine.js`)
- Orbital tool ring → UI event bus: subscribes to events (evidence: `frontend/src/components/OrbitalMenu/OrbitalMenu.jsx`)
- Orbital tool ring → Menu state sync: reads menu state (evidence: `frontend/src/components/OrbitalMenu/OrbitalMenu.jsx`)
- 3D scene engine → World and grid math: uses grid helpers (evidence: `frontend/src/engine/SceneEngine.js`)
- Gesture state machine → World and grid math: projects hand coordinates (evidence: `frontend/src/hooks/useGestureStateMachine.js`)
- Authentication state → Auth client: calls account operations (evidence: `frontend/src/context/AuthContext.jsx`)
- Authentication state → HTTP client: sets token and callback (evidence: `frontend/src/context/AuthContext.jsx`)
- Auth client → HTTP client: sends auth requests (evidence: `frontend/src/api/authApi.js`)
- Scene dashboard → Scene client: loads scene data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Scene history → Scene client: loads scene history (evidence: `frontend/src/pages/HistoryPage.jsx`)
- Public gallery → Scene client: loads public scenes (evidence: `frontend/src/pages/LandingPage.jsx`)
- Scene client → HTTP client: sends scene requests (evidence: `frontend/src/api/scenesApi.js`)
- HTTP client → Express API server: calls REST API
- Express API server → Account routes: mounts auth routes (evidence: `backend/server.js`)
- Express API server → Scene routes: mounts scene routes (evidence: `backend/server.js`)
- Express API server → MongoDB connection: connects database (evidence: `backend/server.js`)
- Account routes → User records: reads and writes users (evidence: `backend/routes/auth.js`)
- Account routes → JWT authorization: protects profile route (evidence: `backend/routes/auth.js`)
- Scene routes → JWT authorization: guards scene routes (evidence: `backend/routes/scenes.js`)
- Scene routes → Scene records: reads and writes scenes (evidence: `backend/routes/scenes.js`)
- Scene routes → User records: uses user records (evidence: `backend/routes/scenes.js`)
- MongoDB connection → MongoDB: connects to
- User records → MongoDB: persists users
- Scene records → MongoDB: persists scenes
