rsayyed591/motionforge

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.