Philosophy

The core design principles, architectural background, and synchronized workflow of the Aircada SDK and Studio.
Published: 7/10/2026

The Aircada platform is a unified, synchronized environment for building interactive 3D web applications, designed to bridge the gap between strict, code-driven software engineering and visual, spatial design.

It decouples logic and layout across two synchronized spaces: the local Aircada SDK (where developers write logic and 2D UI) and the cloud-based Aircada Studio (where designers build 3D scenes and wire everything together).

Agent-First Design#

How the Aircada SDK is optimized for LLM agents rather than traditional human-only coding environments.

The Aircada SDK is explicitly designed as an AI-first SDK. Key optimization strategies include:

  • Minimized Boilerplate: Simple, declarative decorators allow LLM agents to declare data models, event interfaces, and layout parameters without verbose initialization code.
  • Concise Syntax: Avoids large, complex imperative mesh-manipulation blocks by delegating low-level operations to visual tools and exposing clear, semantic API facades.
  • Strict Typos & Schemas: Uses generated TS interfaces to eliminate string hallucinations and make APIs highly discoverable for LLMs.

Current SDK Capabilities & Boundaries#

Current boundaries of the SDK regarding loading 3D assets vs. interacting with pre-existing docs.studio structures.

To maintain optimal runtime performance and guardrails, the Aircada SDK enforces strict boundaries on resource creation and manipulation.

  • Interacting with Existing Systems: Currently, the SDK is optimized for loading, manipulating, and binding logic to 3D entities that already exist and are configured in the visual Aircada Studio.
  • Built-in Operator Composition: Instead of writing complex imperative math or animation pipelines, agents should leverage pre-baked Built-in Operators (such as spatial controllers and data utilities) when possible.
  • Future Roadmap: Direct dynamic loading of fresh 3D content and runtime instantiation of complex Aircada presets are actively planned, but not yet natively exposed in the SDK. Build off existing assets and Operator setups.

The Aircada CLI & Registry System#

Synchronizing visual docs.studio composition with code using the CLI and generated registry files.

The Aircada CLI acts as the bridge connecting your local codebase with the visual Aircada Studio interface, synchronizing assets and structural mappings dynamically.

  • Visual-to-Code Sync: Developers and designers build and position elements visually in the web-based Aircada Studio, and run the CLI to synchronize changes down to the codebase.
  • Registry Generation: The CLI processes visual structures to generate strictly-typed registry files. These include event mappings (Event Registry), option mappings (Options Registry), and 3D coordinates/facades (Raw IDs, Operator Refs, and Data Registries).
  • Agent Guardrails: Utilizing these registry outputs instead of hardcoded strings protects LLM agents from introducing broken references or layout bugs during code generation.

The Connection Paradigm#

How SDK logic meets 3D visual environments through Aircada's decoupled node-graph architecture.

In traditional 3D development, code is often tightly coupled and hardcoded directly to a specific 3D mesh. Aircada decouples logic from visual layout entirely using a flexible Node-Graph architecture:

1. Operators as Logic Containers: Developers write stateless or stateful TypeScript classes representing Operators using decorators. These define the custom properties (e.g. speed, colors, active selections) and event bindings.

2. The Wiring Layer: When an Operator is saved locally, it compiles and instantly appears in the online Aircada Studio as a floating node panel containing its input/output ports.

3. Logical Connections: Inside the Studio, a designer visually wires these Operator properties directly into 3D meshes, particle effects, or rendering pipelines.

  • Unprecedented Reusability: Developers write generic behaviors once (such as a 'Smart Pedestal' controller), and designers can reuse and wire them to three entirely different 3D models in the viewport without changing code.
  • Strict Separation of Concerns: Software engineers focus purely on writing robust logic, while designers and artists focus on spatial beauty and interactive flow.

Live Developer Workflow#

The real-time synchronization link connecting local developer edits to the cloud visual canvas.

The Aircada SDK and Studio are continuously linked during development via a high-performance feedback loop:

  • WebSocket Hot-Reloading: Developers run a local CLI tool maintaining a live WebSocket connection to the Aircada cloud. Local code updates or React changes hot-reload instantly into the active Studio web workspace.
  • Bi-directional Compilation: When designers upload a new model or create a new dataset in the cloud Studio, the CLI detects the event and immediately regenerates the corresponding local TypeScript definitions.

Aircada SDK Environment#

The local workspace where engineers author logic and design custom 2D React interfaces.

The SDK is the local workspace where software engineers orchestrate the web application's visual flow and state boundaries. Key pillars include:

  • 2D UI Overlay: Built on React, this frontend layer sits cleanly on top of the 3D viewport, reading from the Aircada store, rendering menu lists, and transmitting signals to the active scene.
  • Operator Authoring: The developer workspace for writing the TypeScript classes, state-machines, and mathematical equations that populate the Studio's node list.
  • The Auto-Generated Bridge: Rather than manually copy-pasting resource strings, the SDK CLI automatically compiles cloud-configured datasets and media assets into a strictly typed local registry (media.generated.ts), ensuring complete IDE autocompletion.

Aircada Studio Environment#

The cloud-based visual workspace where physical 3D elements and functional logic are assembled.

The Aircada Studio is the visual web application where physical assets and logical units are assembled into a coherent e-commerce experience. Key systems include:

  • Scene Composition: The real-time WebGL/WebGPU viewport for importing, translating, scaling primitive shapes or visual meshes, and configuring cameras and materials.
  • Media & Asset Management: The central repository hosting 3D models (GLB), textures, images, audio, and visual spreadsheet Datasets used to seed configurator variants.
  • The Node Editor: The visual playground canvas where developers' SDK Operators, built-in engine events, and effects are wired together.

System Overview#

A high-level view of the synchronized Aircada environment, bridging code-driven logic with visual spatial design.

Aircada operates across two continuously linked and synchronized environments during the development lifecycle:

1. The local Aircada SDK (Local Environment): This is the developer's domain. Here, software engineers write business logic, manage global application states in the Twin-Proxy store, author custom Operators, and craft 2D React UI overlays.

2. The cloud-based Aircada Studio (Cloud Environment): This is the designer's domain. Here, 3D artists compose scenes, position cameras and lighting, bake environments, define option sets, and visually stitch interactive behaviors together.