SDK Code Architecture: @System, @Operator & Blueprint Foundations

Architectural decision matrix for @System singleton managers, @Operator scene mutators, React UI components, and contextual blueprint foundations.
Published: 7/10/2026

The SDK Code Architecture Plan bridges high-level product specifications into concrete TypeScript source files before code generation.

The architecture is organized into 3 core functional layers: Headless @System Singleton Managers (lifecycle, state orchestration, event bus routing), Modular @Operator Scene Mutators (direct 3D mesh swapping, material bindings, laser monograms), and React UI Components (@aircada/react customizer drawers and pricing footers).

Aircada Blueprints are attached directly as contextual starting foundations on each planned system, operator, or UI component, complete with actionable modification notes (e.g. 'Import calculateSubtotal() and adapt for laser engraving offset').

  • ### 1. The 3D Architectural Triad
  • Unidirectional data flow: @aircada/react UI Component -> Reactive Store (useAirStore / store.patch) -> @System Singleton Manager (Business Logic Orchestrator) -> @Operator Scene Mutator (3D Three.js Render Updates) -> WebGL Canvas.
  • ### 2. @System Singleton Managers vs @Operator Scene Mutators
  • Systems handle business logic, pricing math, store subscriptions (@Input({ onStore: ... })), and typed event dispatch (@Output()). Operators mutate Three.js scene graphs, swap shader materials, and attach geometry targeting generic mesh slots (@StringProperty() targetSlot = 'slot*mesh').
  • ### 3. Contextual Blueprint Foundations (air bp apply)
  • Attach blueprintReferences with clear notesForUsage in manifest.architecture. During manifestation, execute 'air bp apply <id> -d . -o -v --no-install' (or inspect via aircada-mcp getblueprintby_id) to deploy foundational code, then tailor store keys and dataset bindings to the active project.
  • ### 4. Strongly-Typed Schemas & Constants
  • Centralize all store keys (STOREKEY...), event signals (EVENT...), and dataset IDs (DATASETID_...) into src/schemas/<Name>Schemas.ts for strict type safety and zero string typos.