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.

Produce a complete technical planning package and Vite/React/TypeScript project scaffold for Mechanica. Deliverables include the component architecture document, Three.js scene architecture document, animation interface design, machine registry schema, URL state model, accessibility plan, asset pipeline strategy, performance budget, directory structure, ESLint/Prettier/Tailwind/Zustand setup, theme tokens, routing layout, and initial placeholder pages. This milestone defines how the ambitious 28-machine catalogue will be implemented in a data-driven way without monolithic files.

Build the production frontend shell: dark engineering visual system, top navigation, catalogue homepage, searchable/filterable/sortable machine grid, difficulty/category tags, favourite/bookmark persistence via localStorage, responsive layouts for desktop/tablet/mobile, skeleton loading states, theme toggle, focus-visible styling, ARIA labelling, and shared UI primitives. Deliverables include React components, Zustand stores, registry-driven catalogue data for all core and stretch machines, routing, CSS variables/Tailwind configuration, and UI documentation.

Implement the reusable React Three Fiber viewer engine. Deliverables include OrbitControls with damping, camera presets and reset, shareable camera/view state via URL parameters, physically based lighting defaults, HDR/environment hooks, soft shadow configuration, model/procedural-asset loading layer, selection and hover highlighting, part tooltips, detail drawer integration, component visibility/opacity controls, wireframe mode, annotation labels, FPS/status bar, loading progress UI, mobile-safe rendering settings, and viewer architecture documentation.

Create the standardized machine animation module interface and core animation player: play/pause/resume/restart, RPM slider, time scale, loop control, step-through mode, GSAP/RAF timing integration, reduced-motion handling, and per-machine animation lifecycle hooks. Build a polished demo set of representative procedural 3D machines with believable working animations and guided tours: four-stroke petrol engine, planetary gearbox, differential gear, centrifugal pump, Geneva drive, ball bearing, disc brake caliper, and Wankel rotary engine. Include per-part metadata, engineering facts, labels, highlight choreography, and clean looping animations.

Expand the registry, educational layer, procedural visualization configs, part lists, guided tour scripts, and animation modules to cover all 28 Phase 1 core machines. Each machine should include title, description, difficulty, category, engineering facts, related machines, component hierarchy, per-part descriptions, camera presets, animation behavior, exploded-view metadata, labels, and catalogue thumbnail strategy. Where exact CAD geometry is not feasible from text alone, provide clean procedural/diagrammatic assemblies and documented GLB replacement points so professional assets can be swapped in without touching core code.

Finalize the Vercel-ready application with performance optimization, lazy loading, code splitting, error boundaries, loading fallbacks, keyboard navigation checks, reduced-motion support, URL sharing/copy-link behavior, social/meta tag strategy, mobile tuning, and documentation. Deliverables include deployment instructions, state management documentation, machine-authoring guide, asset compression/loading guide for Draco/KTX2 workflows, performance optimization report, QA checklist, regression test plan, example environment configuration, and final README for maintainers.