# kittycad/modeling-app architecture

> Architecture diagram of the GitHub repository kittycad/modeling-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kittycad/modeling-app
- Repository: https://github.com/kittycad/modeling-app

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FUI1("React App"):::frontend
        FUI2("UI Components"):::frontend
    end

    %% State Management & Domain Logic
    SM("XState State Machines"):::state

    %% Language Processing
    subgraph "Language Processing"
        KCL("KCL Language"):::language
        LCML("CodeMirror Lang"):::language
        LSP("LSP Client"):::language
    end

    %% Transport Layer
    WSC("WebSocket Connector"):::transport

    %% Modeling Engine
    GE("Rust/WASM Geometry Engine (GPU)"):::engine

    %% Desktop Application Integration
    DW("Electron Desktop Wrapper"):::integration

    %% Build & Deployment Pipeline
    CICD("CI/CD Pipeline"):::cicd

    %% Relationships
    FUI1 -->|"UserActions"| SM
    FUI2 -->|"UserActions"| SM

    SM -->|"TriggersCommands"| KCL

    LCML -->|"Supports"| KCL
    LSP -->|"Supports"| KCL

    KCL -->|"SendCommands"| WSC

    WSC -->|"DispatchCommands"| GE

    GE -->|"FrameStream"| FUI1

    DW -->|"WrapsUI"| FUI1

    CICD -->|"AutoBuildTest"| FUI1
    CICD -->|"AutoBuildTest"| GE

    %% Click Events
    click FUI1 "https://github.com/kittycad/modeling-app/blob/main/src/App.tsx"
    click FUI2 "https://github.com/kittycad/modeling-app/tree/main/src/components"
    click SM "https://github.com/kittycad/modeling-app/tree/main/src/machines"
    click KCL "https://github.com/kittycad/modeling-app/tree/main/src/lang"
    click LCML "https://github.com/kittycad/modeling-app/tree/main/packages/codemirror-lang-kcl"
    click LSP "https://github.com/kittycad/modeling-app/tree/main/packages/codemirror-lsp-client"
    click WSC "https://github.com/kittycad/modeling-app/blob/main/src/channels.ts"
    click GE "https://github.com/kittycad/modeling-app/tree/main/rust"
    click DW "https://github.com/kittycad/modeling-app/blob/main/electron-builder.yml"
    click CICD "https://github.com/kittycad/modeling-app/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef state fill:#ffc9de,stroke:#000,stroke-width:2px;
    classDef language fill:#d0f4de,stroke:#000,stroke-width:2px;
    classDef transport fill:#ffe5d9,stroke:#000,stroke-width:2px;
    classDef engine fill:#caffbf,stroke:#000,stroke-width:2px;
    classDef integration fill:#ffd6a5,stroke:#000,stroke-width:2px;
    classDef cicd fill:#e0bbff,stroke:#000,stroke-width:2px;
```
