How kittycad/modeling-app works
Main Components of the System
• Frontend UI:
– A React-based web application (located in the top–level “src” folder) driven by state machines (XState) that manages components such as the code editor, toolbar, project sidebar, and 3D stream view.
– Multiple UI submodules including the CodeMirror–based editor (with custom WASM LSP server integration) and various React components (in “src/components”).
– The 3D view is rendered by a video element that displays a stream from the remote geometry engine.
• State Machines and Domain Logic:
– “machines” directory contains state machine definitions (e.g., for authentication, file management, project navigation, modeling interactions) that coordinate UI actions, command execution, and transitions.
• Code Editing and KCL Language:
– The “lang” folder and packages like “packages/codemirror-lang-kcl” and “packages/codemirror-lsp-client” are key for syntax highlighting, language server protocols, parsing, and manipulation of KCL code.
– This underpins the fundamental design principle that every CAD artifact is code (which aids version control and reproducibility).
• Modeling & Rendering Engine:
– The geometry engine is implemented in Rust, compiled to WASM (as seen in the “rust” folder and WASM build scripts). It handles the heavy–lifting of CAD geometry calculations and rendering.
– The application sends modeling commands (via WebSockets) from the frontend state machines to a hosted geometry engine that returns updated video frames.
– Offloading rendering tasks to the GPU (using technologies like Vulkan on Nvidia GPUs) is central to performance.
• Desktop Application and Integration:
– There is also an Electron (or similar desktop) build (files like “electron-builder.yml” and “tron:start”) which wraps the web app to create a desktop experience.
• Backend/Networking:
– WebSocket communications form the backbone between the UI and the geometry engine, using the “KittyCAD TS client” for this purpose.
– Authentication flows and API integrations (using Zoo API tokens) are handled briefly in configuration (environment files and readme instructions).
• Build & Deployment Pipeline:
– The repository includes diverse CI/CD configurations (in “.github/workflows” and scripts) to build Rust (and WASM) code, run multiple integration tests (Playwright tests, unit tests with Vitest, and Rust tests with cargo-nextest), as well as package and release the application.
Relationships and Interactions
– The UI (React) interacts with state machines (XState) which drive the core workflow. User actions in the editor or toolbar trigger command execution.
– Modeling commands get transformed into KCL code through language utilities (in “lang”) and are then sent via the WebSocket connection to the remote geometry engine.
– The geometry engine processes the commands (with heavy computation performed in Rust/WASM on the GPU) and returns streaming video frames for real-time display.
– The Electron desktop wrapper (if running in desktop mode) integrates tightly with the same web app for file system access and native UI interactions.
– CI/CD tools (GitHub workflows, build scripts, Rust fuzzing scripts, etc.) ensure code quality, automated testing, and packaging for different platforms.
Architectural Patterns and Design Principles
– Hybrid UI: Combining point–and–click controls with code–driven modeling (all CAD artifacts are “plain text”).
– Separation of Concerns: The frontend (React/UI and state machines) is clearly separated from the modeling engine (Rust/WASM) and from the networking layer (API, WebSockets).
– Modularity: Clear boundaries are seen in separate directories for source code (“src”), Rust–based engine (“rust”), packages (language tooling), and tests (e2e and unit tests).
– Performance Focus: The heavy geometry computations are offloaded to a high–performance WASM module utilizing GPU rendering.