System Architecture

Yugma is an AI-native 3D studio — a professional web-based scene editor where natural language is the primary interface. Users describe what they want, and an AI Director composes the scene using structured tool calls against a live Three.js scene graph.

High-Level Architecture

Browser (yugma-app)                Firebase
+----------------------------+    +----------------------------+
|  React 18 + TypeScript     |    |  Cloud Functions v2        |
|  +----------+ +---------+  |    |  +------------------------+|
|  | AIPanel  | | Scene   |  |    |  | aiCompose (agentic)    ||
|  | + spatial| | Renderer|  |    |  |  - planning pass       ||
|  |   preproc| | (R3F)   |  |    |  |  - 15 tools, 8-iter   ||
|  +----------+ +---------+  |    |  |  - style injection     ||
|  +----------+ +---------+  |    |  |  - Firestore persist   ||
|  | 14 Zustand| | Physics |  |    |  +------------------------+|
|  |   stores  | | World   |  |    |  | generateAsset (Meshy)  ||
|  +----------+ +---------+  |    |  | generateMaterial (AI)  ||
|  +----------+ +---------+  |    |  | startVideoRecon (stub) ||
|  | Twin     | | Cinematic|  |    |  | renderStoryboard (stub)||
|  | Panel    | | Panel    |  |    |  | octopartProxy (stub)   ||
|  +----------+ +---------+  |    |  | getRecentAISessions    ||
+----------------------------+    +----------------------------+
         |   |                     |   |
         |   |  Firestore          |   |  Realtime DB
         |   |  - projects         |   |  - collab/cursors
         |   |  - aiSessions       |   |  - rooms
         |   |  - *Jobs            |   |  - sensors (Phase 13)
         |   |                     |   |
         |   +---------------------+   |
         |                             |
         +-----------------------------+

Key Design Principles

1. AI-first, not AI-bolted-on. The scene graph, serialization format (YSL), and every data structure are designed for LLM consumption at ~45 tokens/object.

2. Agentic loop, not one-shot. The AI Director calls tools, sees the results (including generated IDs), and chains dependent operations across up to 8 iterations. This produces coherent multi-object scenes, not random placements.

3. Client-side spatial computation. LLMs are bad at trigonometry. The spatial preprocessor detects patterns ("arrange 6 in a circle") and injects exact coordinates. The AI just uses them.

4. Firebase-native data layer. Firebase handles auth, real-time collab, document storage, and AI session persistence via Firestore.

5. Phase scaffolding. Phases 12-16 are scaffolded with full type systems, stores, service stubs, and panel UIs, but the actual ML pipelines (SAM2, physics engines, render workers) are not yet connected.

Monorepo Structure

Package	Purpose	Stack
yugma-app	Main 3D studio editor	React + R3F + Zustand + Vite
yugma-functions	Cloud Functions backend	Node 20 + Firebase Functions v2
yugma-landing	Marketing site	Static HTML/CSS
yugma-admin	Admin dashboard	React + Tailwind
yugma-docs	This documentation	Docusaurus

Managed with pnpm workspaces + Turborepo. Exception: yugma-functions uses npm (Firebase Cloud Build constraint).

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite
3D Engine	Three.js via React Three Fiber + Drei
State	Zustand (14 stores)
AI	Anthropic Claude API (@anthropic-ai/sdk)
3D Generation	Meshy.ai API
Auth	Firebase Auth (email/password + Google OAuth)
Document DB	Firestore
Realtime	Firebase Realtime Database
Storage	Firebase Cloud Storage
AI Memory	Firestore (aiSessions collection)
Hosting	Firebase multi-site hosting