# rsayyed591/motionforge architecture

> Architecture diagram of the GitHub repository rsayyed591/motionforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rsayyed591/motionforge
- Repository: https://github.com/rsayyed591/motionforge

## Overview

1. **Overall shape**
   MotionForge Studio is a single-page, browser-only application. There is no backend service or API layer in this repo; all capture, processing, rendering, recording, and playback happen locally in the browser.

2. **Bootstrapping**
   `index.html` is the Vite entry page, `src/main.tsx` mounts the React app, and `src/App.tsx` acts as the top-level workspace orchestrator. Build and dev tooling are centered on Vite, with TypeScript and Tailwind/PostCSS for styling and compilation.

3. **Primary runtime boundary**
   The app is split into two major runtime concerns:
   - **UI/state orchestration** in React
   - **Real-time motion processing/rendering** in dedicated modules
   This keeps the webcam/vision pipeline isolated from the workspace UI so the app can update motion data independently of panel layout and controls.

4. **Motion capture pipeline**
   The live data flow starts with the user’s webcam, passes through `src/PoseTracker.tsx` for MediaPipe-based pose detection, then into motion processing logic that normalizes and smooths landmarks before they become application state. This is the core real-time pipeline driving the rest of the system.

5. **Motion state and session logic**
   `src/useMotionCapture.ts` is the main non-visual state engine. Based on the README, it likely owns capture session lifecycle, recording buffers, playback position, import/export of JSON sessions, and feedback events. This hook is the boundary between raw tracking data and user-facing motion sessions.

6. **3D visualization subsystem**
   `src/AvatarModel.tsx` renders the tracked motion as a 3D skeletal avatar using Three.js / React Three Fiber. It consumes motion state from the capture pipeline and converts it into joint transforms, interpolation, and viewport rendering. This subsystem is intentionally separate from capture so rendering can evolve independently of tracking.

7. **Workspace UI and control panels**
   `src/App.tsx` composes the product-style workspace described in the README: viewport, inspector, camera viewfinder, timeline, playback/recording controls, status telemetry, and session tools. `src/DebugPanel.tsx` is a developer-facing control surface used to test and inspect tracking behavior without disturbing the main experience.

8. **Data flow between subsystems**
   The main flow is:
   webcam input → pose detection → landmark extraction → motion smoothing/constraints → capture state → 3D avatar update
   In parallel, the same capture state feeds recording buffers and playback timelines. That means recording is not a separate system; it is a consumer of the same motion stream used for live visualization.

9. **Local persistence and exchange format**
   The project supports session import/export in JSON, so captured motion can be saved and replayed without re-running live tracking. Since there is no server, session portability is a client-side concern and likely relies on browser download/upload interactions rather than network storage.

10. **Browser APIs and device dependencies**
   The architecture depends on browser-native capabilities: webcam access, animation/render loops, and audio feedback. The README also indicates Web Audio API usage for UI sounds and PWA support via `public/site.webmanifest`. These are important because they define the app as an installable desktop-like browser tool rather than a traditional web service.

11. **Styling and presentation layer**
   `src/index.css`, Tailwind config, and PostCSS drive the cyber/glassmorphism workspace styling. Presentation is a separate concern from the motion engine, which is important for diagramming because the UI is not tightly coupled to tracking logic even though both update live.

12. **What to draw as the main architectural boundaries**
   For an architecture diagram, the most important boxes are:
   - Browser shell / React app
   - Pose tracking input layer
   - Motion processing and session state
   - 3D avatar rendering
   - Workspace UI controls and telemetry
   - JSON import/export and playback
   The key boundary to emphasize is that all of this runs client-side in one browser process, with MediaPipe and the webcam as the only external runtime dependencies.

Main entry points: [`src/App.tsx`](https://github.com/rsayyed591/motionforge/blob/main/src/App.tsx) (App), [`src/useMotionCapture.ts`](https://github.com/rsayyed591/motionforge/blob/main/src/useMotionCapture.ts) (useMotionCapture), [`src/PoseTracker.tsx`](https://github.com/rsayyed591/motionforge/blob/main/src/PoseTracker.tsx) (PoseTracker), [`src/main.tsx`](https://github.com/rsayyed591/motionforge/blob/main/src/main.tsx) (main.tsx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Browser runtime"]
  node_n_index["index.html<br/>Vite entry<br/>[index.html]"]
  node_n_main["main.tsx<br/>React bootstrap<br/>[main.tsx]"]
  node_n_webcam(("Webcam<br/>device input"))
  node_n_media(("MediaPipe<br/>pose library"))
  node_n_audio(("Web Audio<br/>feedback API"))
end

subgraph group_g_motion["Motion engine"]
  node_n_pose["PoseTracker<br/>vision capture<br/>[PoseTracker.tsx]"]
  node_n_capture["useMotionCapture<br/>session engine"]
  node_n_state[("Motion state<br/>runtime data")]
  node_n_timeline["Playback timeline<br/>session playback"]
  node_n_export["JSON sessions<br/>import/export"]
end

subgraph group_g_ui["Workspace UI"]
  node_n_app["App<br/>workspace shell<br/>[App.tsx]"]
  node_n_debug["Debug Panel<br/>dev controls<br/>[DebugPanel.tsx]"]
end

subgraph group_g_render["3D rendering"]
  node_n_avatar["Avatar Model<br/>3D avatar<br/>[AvatarModel.tsx]"]
end

subgraph group_g_tooling["Tooling"]
  node_n_css["index.css<br/>styling<br/>[index.css]"]
  node_n_manifest["site.webmanifest<br/>PWA manifest<br/>[site.webmanifest]"]
  node_n_vite{{"Vite<br/>build tool<br/>[vite.config.ts]"}}
end

node_n_index -->|"loads"| node_n_main
node_n_main -->|"mounts"| node_n_app
node_n_app -->|"hosts"| node_n_pose
node_n_app -->|"hosts"| node_n_avatar
node_n_app -->|"includes"| node_n_debug
node_n_app -->|"consumes"| node_n_capture
node_n_pose -->|"reads"| node_n_webcam
node_n_pose -->|"detects"| node_n_media
node_n_pose -->|"streams"| node_n_capture
node_n_capture -->|"updates"| node_n_state
node_n_capture -->|"drives"| node_n_timeline
node_n_capture -->|"serializes"| node_n_export
node_n_state -->|"renders"| node_n_avatar
node_n_state -->|"inspects"| node_n_debug
node_n_timeline -->|"replays"| node_n_avatar
node_n_app -->|"styles"| node_n_css
node_n_app -.->|"plays"| node_n_audio
node_n_manifest -.->|"installs"| node_n_main
node_n_vite -->|"serves"| node_n_index

click node_n_index "https://github.com/rsayyed591/motionforge/blob/main/index.html"
click node_n_main "https://github.com/rsayyed591/motionforge/blob/main/src/main.tsx"
click node_n_app "https://github.com/rsayyed591/motionforge/blob/main/src/App.tsx"
click node_n_debug "https://github.com/rsayyed591/motionforge/blob/main/src/DebugPanel.tsx"
click node_n_css "https://github.com/rsayyed591/motionforge/blob/main/src/index.css"
click node_n_pose "https://github.com/rsayyed591/motionforge/blob/main/src/PoseTracker.tsx"
click node_n_capture "https://github.com/rsayyed591/motionforge/blob/main/src/useMotionCapture.ts"
click node_n_avatar "https://github.com/rsayyed591/motionforge/blob/main/src/AvatarModel.tsx"
click node_n_manifest "https://github.com/rsayyed591/motionforge/blob/main/public/site.webmanifest"
click node_n_vite "https://github.com/rsayyed591/motionforge/blob/main/vite.config.ts"

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_n_index,node_n_main,node_n_webcam,node_n_media,node_n_audio toneBlue
class node_n_pose,node_n_capture,node_n_state,node_n_timeline,node_n_export toneAmber
class node_n_app,node_n_debug toneMint
class node_n_avatar toneRose
class node_n_css,node_n_manifest,node_n_vite toneIndigo
```

## Components

### Browser runtime

Everything that runs in the user's browser, including app bootstrap and device APIs.

- [index.html](https://github.com/rsayyed591/motionforge/blob/main/index.html): Vite entry · Browser entry page that loads the SPA bundle. · `index.html`
- [main.tsx](https://github.com/rsayyed591/motionforge/blob/main/src/main.tsx): React bootstrap · Mounts the React application into the browser shell. · `src/main.tsx`
- **Webcam**: device input · User camera feed consumed by pose tracking.
- **MediaPipe**: pose library · External vision runtime used for landmark detection.
- **Web Audio**: feedback API · Browser audio used for UI and interaction feedback.

### Motion engine

Live capture, processing, session state, playback, and export/import.

- [PoseTracker](https://github.com/rsayyed591/motionforge/blob/main/src/PoseTracker.tsx): vision capture · Browser webcam and MediaPipe-based pose detection entry point. · `src/PoseTracker.tsx`
- [useMotionCapture](https://github.com/rsayyed591/motionforge/blob/main/src/useMotionCapture.ts): session engine · Owns capture lifecycle, motion state, recording buffers, playback, and session exchange. · `src/useMotionCapture.ts`
- **Motion state**: runtime data · Normalized motion data shared across visualization, recording, and playback.
- **Playback timeline**: session playback · Time-positioned motion stream used for scrubbing and replay.
- **JSON sessions**: import/export · Client-side session serialization for save/load without a backend.

### Workspace UI

Top-level workspace composition and developer-facing panels.

- [App](https://github.com/rsayyed591/motionforge/blob/main/src/App.tsx): workspace shell · Top-level orchestrator that composes the studio layout and cross-panel state. · `src/App.tsx`
- [Debug Panel](https://github.com/rsayyed591/motionforge/blob/main/src/DebugPanel.tsx): dev controls · Developer-facing surface for inspecting and testing capture behavior. · `src/DebugPanel.tsx`

### 3D rendering

Avatar visualization built on Three.js / React Three Fiber.

- [Avatar Model](https://github.com/rsayyed591/motionforge/blob/main/src/AvatarModel.tsx): 3D avatar · Renders tracked motion as a skeletal avatar and interpolated viewport scene. · `src/AvatarModel.tsx`

### Tooling

Build, styling, and installability assets.

- [index.css](https://github.com/rsayyed591/motionforge/blob/main/src/index.css): styling · Global presentation layer for the workspace look and feel. · `src/index.css`
- [site.webmanifest](https://github.com/rsayyed591/motionforge/blob/main/public/site.webmanifest): PWA manifest · Installability metadata for the browser app. · `public/site.webmanifest`
- [Vite](https://github.com/rsayyed591/motionforge/blob/main/vite.config.ts): build tool · Development server and production bundler for the SPA. · `vite.config.ts`

## Connections

- index.html → main.tsx: loads · The HTML shell loads the React bundle.
- main.tsx → App: mounts · Bootstraps the application workspace.
- App → PoseTracker: hosts · Places capture UI alongside the live tracker.
- App → Avatar Model: hosts · Displays the 3D visualization in the workspace.
- App → Debug Panel: includes · Surfaces developer controls in the same shell.
- App → useMotionCapture: consumes · Coordinates the shared motion/session engine.
- PoseTracker → Webcam: reads · Consumes camera input from the browser device.
- PoseTracker → MediaPipe: detects · Uses MediaPipe for pose landmark extraction.
- PoseTracker → useMotionCapture: streams · Sends tracked landmarks into the session engine.
- useMotionCapture → Motion state: updates · Normalizes and stores live motion data.
- useMotionCapture → Playback timeline: drives · Feeds recording and playback position.
- useMotionCapture → JSON sessions: serializes · Exports captured sessions and imports saved ones.
- Motion state → Avatar Model: renders · Avatar visualization consumes current motion state.
- Motion state → Debug Panel: inspects · Debug tools observe the same live state.
- Playback timeline → Avatar Model: replays · Playback updates the avatar independently of live capture.
- App → index.css: styles · Workspace presentation is provided by global styling.
- App → Web Audio: plays · UI feedback sounds are triggered from the browser runtime.
- site.webmanifest → main.tsx: installs · PWA metadata supports browser installation.
- Vite → index.html: serves · Build tool entrypoint for the browser app.