WebJuggle
Parametric club builder that turns curated browser inputs into printable STL assemblies.
03
One part of a portfolio focused on expressive interfaces and disciplined systems.
A real locally generated WebJuggle build showing the keyed traditional preset with visible option selections and the completed STL preview.
Overview
WebJuggle is a 2026 side-project that lets hobby jugglers design custom juggling clubs in the browser and instantly download print-ready STL assemblies. I owned product design and end-to-end engineering.
What The App Does
• Users pick from a curated set of parameters—handle length, knob type, weight chambers, stand adapters, etc. • On submit, the app generates a complete juggling club assembly using a vendored CadQuery script and returns a ZIP of STL parts. • A Three.js viewer renders the returned geometry so the user can inspect scale and balance before printing. • No sign-in, payments, or persistence: every job is an ephemeral, anonymous build that lives only long enough for the download.
Product/UX Review
The flow is linear and opinionated:
- Static Next.js page loads instantly; all options are above the fold on desktop.
- Form validation prevents illegal parameter mixes by hard-coding the same rules used in CadQuery.
- Generation status is streamed to the UI; the 3D preview appears once the ZIP lands.
- A single “Download STL” call-to-action completes the journey.
Strengths • Zero-friction onboarding; nothing to install. • Real-time 3D preview builds trust that prints will fit. • Static export means the site works even behind aggressive CDNs.
Limitations • No project save/return; users must re-enter parameters. • Heavy mobile interaction can be clumsy; the controls are tuned for a mouse.
Technical Architecture
Frontend
• Next.js + React + TypeScript, built with next export to a fully static site.
• Tailwind for styling, Three.js + react-three-fiber for STL rendering (StlViewer.tsx).
• Deployed via a lightweight Nginx container.
Backend
• FastAPI service (apps/api) fronting a Python 3.11 “engine” folder that contains all CadQuery generators (generate_club.py, ancillary scripts).
• Jobs are written to a shared out/ directory; a background task cleans up on an interval.
• Docker-Compose stitches web and API, and systemd files (webjuggle-api.service.example) support bare-metal deploys.
• No database; the filesystem is the single source of truth for transient artifacts.
Build & Ops
• Makefile targets wrap local setup (make setup-api, make dev-api).
• CI GitHub Action only runs lint/build because the engine requires CAD kernels not available in the runner.
AI Techniques And Patterns
No AI or LLM components are present; all geometry is produced deterministically by CadQuery.
What Was Learned
• Verified that a static Next.js front can still deliver dynamic artifacts by delegating all compute to a minimal API.
• CadQuery’s STL generation time balloons with complex lofts; caching at the filesystem layer saves ~40 % wall-time on common builds.
• Three.js camera fitting math (fitCamera) must account for wildly different bounding boxes when parameters swing.
• Cleaning up large build folders early prevents container disks from filling in weeks rather than months.
Strengths And Tradeoffs
Strengths • Very low hosting cost: CDN-served static assets plus a small Python microservice. • Clear separation of concerns—type-safe React UI, pure-Python CAD engine. • Dockerised workflow makes local and production parity trivial.
Tradeoffs • No authentication or history: great for privacy, bad for iterative tweaking. • CPU-bound CadQuery jobs limit concurrency; horizontal scaling would require extra orchestration. • The app’s tight coupling to CadQuery means swapping to a different CAD kernel would be non-trivial.