Mechanica - a Mechanical Systems Explorer - Full-Stack 3D Viewer Build Prompt

You are a senior frontend engineer, Three.js expert, WebGL specialist, and product designer. Your task is to build a production-quality interactive web application called "Mechanical Systems Explorer". --- ## PROJECT OVERVIEW Create a modern web-based platform for learning mechanical systems through interactive 3D visualizations. The platform should feel like a premium engineering reference tool — part interactive textbook, part CAD viewer, part simulation environment. Users should be able to: * Browse a catalogue of mechanical systems * Explore engines, gearboxes, pumps, and mechanisms in 3D * Rotate, zoom, and pan freely * Play physically accurate working animations * Toggle exploded views with adjustable separation * Show, hide, and adjust opacity of individual components * View systems from saved camera presets * Switch between solid, wireframe, and cross-section modes * Read component descriptions and engineering facts * Share links to specific machines and view states No AI assistant is required. --- ## TECH STACK Frontend: * React * TypeScript * Vite 3D: * Three.js * React Three Fiber * Drei Animation: * GSAP * React Spring (if needed) Styling: * Tailwind CSS * CSS Variables * Framer Motion State: * Zustand Asset Format: * GLB / GLTF Deployment: * Vercel-ready --- ## ARCHITECTURE ``` src/ ├── components/ ├── modules/ ├── pages/ ├── three/ ├── animations/ ├── hooks/ ├── store/ ├── assets/ ├── shaders/ ├── layouts/ └── utils/ ``` Create reusable components. Avoid monolithic files. The machine registry must be data-driven so new machines can be added without touching core code. --- ## VISUAL DESIGN Build a dark-themed, premium engineering aesthetic: * Dark background (#0B0E14) * Raised panel surfaces (#121721) * Glassmorphism / subtle transparency effects * Sky blue accent colour (#4C8DFF) * Warm highlight colour (#FFB04C) * Muted secondary text * Fine hairline borders * Smooth hover and active states * Skeleton loading states with no layout shifts Typography should be clean, modern sans-serif with tabular numerals for data values. --- ## MACHINE CATALOGUE Build a browsable homepage catalogue with search, category filters, and difficulty tags. ### Phase 1 — Core Machines (must ship) **Engines** 1. Four Stroke Petrol Engine — intake, compression, combustion, exhaust strokes; valves, piston, crankshaft, camshaft 2. Two Stroke Engine — simplified port-based cycle 3. Diesel Engine — compression ignition variant with injector 4. V8 Engine — two banks of four cylinders, firing order animation, crankshaft 5. Wankel Rotary Engine — eccentric rotor, epitrochoid housing, port timing 6. Steam Engine — piston, slide valve, flywheel, governor 7. Jet Engine (Turbojet) — intake, compressor stages, combustion chamber, turbine, nozzle 8. Turbofan Engine — bypass duct, fan, core flow split **Gearboxes & Drives** 9. Planetary Gearbox — sun, planet, ring gear; selectable input/output 10. Differential Gear — torque split, cornering animation 11. Manual Gearbox (5-speed) — synchromesh, selector forks, layshaft 12. CVT (Continuously Variable Transmission) — belt and pulley ratio animation 13. Worm Gear Drive — high reduction ratio, self-locking demonstration 14. Bevel Gear Set — right-angle drive, spiral bevel variant **Pumps & Fluid Systems** 15. Centrifugal Pump — impeller, volute, cavitation indicator 16. Gear Pump — meshing gears, fluid displacement per revolution 17. Piston Pump — reciprocating action, inlet/outlet valves 18. Hydraulic Cylinder — extend/retract, seals, pressure indicator **Mechanisms** 19. Scotch Yoke — crank to linear motion conversion 20. Geneva Drive — intermittent motion mechanism 21. Cam and Follower — various cam profiles (eccentric, heart, snail) 22. Rack and Pinion — linear to rotary conversion 23. Slider Crank — connecting rod geometry, dead centre positions 24. Toggle Clamp — mechanical advantage demonstration **Structural / Other** 25. Ball Bearing — race, balls, cage, load distribution 26. Roller Bearing — tapered roller variant 27. Disc Brake Caliper — pad, rotor, piston actuation 28. Turbocharger — compressor wheel, turbine wheel, wastegate ### Phase 2 — Stretch Machines (architecture must support) * Radial Engine * Stirling Engine * Axial Piston Motor * Torque Converter * Harmonic Drive * Electric Motor (BLDC) * Solenoid Valve * Scroll Compressor --- ## 3D VIEWER Features: * Orbit controls with smooth damping * Zoom and pan * Camera presets (front, back, left, right, top, isometric) * Reset camera * Shareable view state via URL parameters Rendering: * Physically based rendering * HDR environment lighting * Soft shadows * Ambient occlusion * Tone mapping * Reflection support Performance: * Instancing where possible * Frustum culling * Lazy loading per machine * Asset compression (Draco / KTX2) * Mobile optimization Target 60 FPS on desktop, 30 FPS minimum on mobile. --- ## MACHINE INTERACTIONS Each machine supports: * Mouse / touch rotate, zoom, pan * Hover highlight with part name tooltip * Click to select part — shows description panel * Exploded view with adjustable distance * Per-part visibility toggle and opacity slider * Cross-section clipping plane (X / Y / Z axis) * Wireframe toggle * Annotation labels toggle --- ## ANIMATION SYSTEM Every machine supports: * Play / Pause / Resume / Restart * RPM slider * Time scale control (0.1× to 3×) * Step-through mode (advance one cycle step at a time) Animations must be physically believable and loop cleanly. Each machine defines its own animation module exporting a standard interface so the core player never needs to know machine-specific logic. --- ## LEARNING LAYER Each machine includes: * Title and one-paragraph description * Key engineering facts (efficiency, typical RPM range, invention date, common applications) * Per-part descriptions shown on selection * "How it works" guided tour — auto-plays camera moves and highlights parts in sequence with text captions * Difficulty badge (Beginner / Intermediate / Advanced) * Related machines suggestions --- ## CATALOGUE PAGE * Grid of machine cards with thumbnail, name, category, difficulty * Search by name or keyword * Filter by category (Engines, Gearboxes, Pumps, Mechanisms) * Filter by difficulty * Sort by name, newest, complexity * Favourite / bookmark per machine (stored in localStorage) --- ## SHARING * URL encodes current machine, camera position, explode state, visible parts * Copy link button in toolbar * Social preview meta tags per machine --- ## UI REGIONS * Top navigation bar — logo, catalogue link, search, theme toggle * Left sidebar — component list, per-part visibility and opacity * Right control panel — playback, exploded view, cross-section, display settings * 3D viewer canvas — fills remaining viewport * Viewer overlays — camera preset buttons, reset, toolbar * Bottom status bar — part count, FPS counter, current machine name * Detail drawer — slides in on part selection with description and specs --- ## RESPONSIVENESS Desktop: 1440+ / 1280+ Tablet: 1024 / 768 Mobile: 430 / 390 / 375 --- ## ACCESSIBILITY * Full keyboard navigation * ARIA labels throughout * Focus-visible states * Reduced motion support * Colour contrast compliance (WCAG AA) --- ## LOADING EXPERIENCE * Machine catalogue loads instantly with skeleton cards * 3D viewer shows skeleton UI and progress bar during asset load * No white flashes * No layout shifts * Smooth scene-to-scene transitions --- ## CODE QUALITY * Strict TypeScript * Clean architecture * Reusable components * No duplicate logic * No hardcoded values * Environment configuration via `.env` * ESLint + Prettier --- ## DELIVERABLES 1. Complete source code 2. Component architecture document 3. Three.js scene architecture document 4. Animation system architecture 5. Machine registry format and how to add new machines 6. Asset pipeline and loading system 7. State management documentation 8. Deployment instructions (Vercel) 9. Performance optimization report The final application must feel like a premium engineering visualization platform comparable to professional CAD and educational simulation software.