Frontend Guideline Document

Frontend Guideline Document: 3D One AI

Version 1.0
Date: October 26, 2023

1. Introduction

Project Overview
3D One AI is an educational platform for K-12 AI/robotics education, integrating 3D physics simulation, virtual hardware, programming interfaces, and AI behavior modeling. The frontend must deliver:

• Real-time 3D rendering with physics interactions.
• Block-based (visual) and text-based programming interfaces.
• Cross-platform compatibility (web/desktop).
• Secure sandboxing for code execution.
• Compliance with WCAG 2.1 accessibility standards.

2. Technology Stack

Core Frameworks

Programming & AI Integration

Tooling & Infrastructure

• Bundler: Vite 5.0.0 (SWC compiler).
• Testing: Jest 29.7 + Cypress 13.6.
• CI/CD: GitHub Actions + Vercel.
• Accessibility: Axe-core 4.8.1.

3. Architecture Design

Component Structure

src/
├── core/
│   ├── physics/       # Rapier physics wrappers
│   ├── ai/            # TF.js model integration
│   └── simulation/    # 3D scene lifecycle
├── ui/
│   ├── editor/        # Blockly/Monaco interfaces
│   ├── hardware/      # Virtual Arduino/RPi components
│   └── workspace/     # Canvas for 3D rendering
├── services/
│   ├── auth/          # JWT-based role management
│   └── api/           # Axios client for backend
└── stores/            # Zustand state slices

Key Flows

1. Simulation Initialization:
   • Load 3D assets (GLTF) via useGLTF (Drei 9.85.0).
   • Initialize Rapier physics world with gravity/constraints.
2. Code Execution:
   • Blockly → Generate Python → Execute in Web Worker.
   • Sandboxed via iframe + postMessage.
3. AI Behavior:
   • Pre-trained TF.js models (e.g., object detection) run in WebGL backend.

4. Implementation Guidelines

3D Rendering & Physics

• Optimization:
  • Use instancedMesh for repeated objects (e.g., sensors).
  • Decouple physics updates (60Hz) from rendering (requestAnimationFrame).
• Example Snippet:
  复制

  import { useRapier } from '@react-three/rapier';
  const { world } = useRapier();
  useEffect(() => {
    world.gravity = { x: 0, y: -9.8, z: 0 };
  }, []);

Programming Interfaces

• Blockly Customization:
  • Define custom blocks for hardware actions (e.g., move_robot()).
  • Map blocks to Python using Blockly’s generator API.
• Monaco Integration:
  • Embed with @monaco-editor/react.
  • Add LSP support via WebSocket for autocomplete.

Security & Sandboxing

• Code Execution:
  • Run user code in Web Workers with restricted WorkerGlobalScope.
  • Validate I/O using regex whitelists (e.g., allowed sensor APIs).
• Data Handling:
  • Sanitize 3D model uploads with glTF-Validator.

Accessibility (a11y)

• Keyboard navigation for 3D controls (WASD + screen reader labels).
• High-contrast themes and ARIA roles for Blockly/Monaco.

5. Performance & Scalability

• Bundle Optimization:
  • Code-split routes with React.lazy().
  • Compress textures via Basis Universal.
• Caching:
  • Cache TF.js models with IndexedDB.
  • Use react-query for API data.
• Load Testing:
  • Target 60 FPS with ≤50ms input latency on mid-tier devices.

6. Testing Strategy

7. Compliance & Best Practices

• Pedagogical Standards:
  • Map UI/features to CSTA K-12 CS standards.
• Privacy:
  • GDPR/COPPA compliance: No PII in client logs.
• Extensibility:
  • Plugin API for third-party hardware simulations.

Approved by: Lead Architect
Next Steps: Phase 1 implementation (Q4 2023) focusing on core simulation and Blockly integration.