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| | | | - composeCore loop ||
| | preproc| | (R3F) | | | | - 20 tools, <=5 iter ||
| +----------+ +---------+ | | | - style injection ||
| +----------+ +---------+ | | | - Firestore persist ||
| | 17 Zustand| | Physics | | | +------------------------+|
| | stores | | World | | | | saveProviderConfig ||
| +----------+ +---------+ | | | generateMaterial (AI) ||
| +----------+ +---------+ | | | sweepGenerationJobs ||
| | Catalog | | ROS/Robot| | | | stripeWebhook ||
| | Panel | | Panel | | | | createShareLink + OG ||
| +----------+ +---------+ | | | publicApi (read API) ||
+----------------------------+ +----------------------------+
| | | |
| | Firestore | | Realtime DB
| | - projects | | - collab/cursors
| | - aiSessions | | - rooms
| | - *Jobs | | - shareLinks
| | | |
| +---------------------+ |
| |
+-----------------------------+
Key Design Principles
-
AI-first, not AI-bolted-on. The scene graph, serialization format (YSL), and every data structure are designed for LLM consumption at ~60 tokens/object (measured).
-
Agentic loop, not one-shot. The AI Director calls tools, sees the results (including generated IDs), and chains dependent operations across up to 5 iterations (default 3). This produces coherent multi-object scenes, not random placements.
-
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.
-
Firebase-native data layer. Firebase handles auth, real-time collab, document storage, and AI session persistence via Firestore.
-
Phase scaffolding. Phases 12-16 are planned verticals. Their earlier prototype stores, service stubs, and panel UIs were removed in the 2026-07 cleanup; the ROS 2 / robotics and industrial-catalog integrations that overlap them remain as real, in-progress code.
Monorepo Structure
| Package | Purpose | Stack |
|---|---|---|
yugma-app | Main 3D studio editor | React + R3F + Zustand + Vite |
yugma-functions | Cloud Functions backend | Node 22 + 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 (17 stores) |
| AI | Google Gemini, managed server-side (gemini-3.7-flash, GEMINI_API_KEY, model overridable in Admin → Providers). The only inference provider; no user-facing model picker. |
| 3D Assets | First-party only: Library v2 (procedural world library, bundled), yugma-lib v1 industrial catalog, Omniverse OpenUSD packs |
| Auth | Firebase Auth (Google OAuth only) |
| Document DB | Firestore |
| Realtime | Firebase Realtime Database |
| Storage | Firebase Cloud Storage |
| AI Memory | Firestore (aiSessions collection) |
| Hosting | Firebase multi-site hosting |