Interactive 3D bowling encyclopedia. Every bowling concept paired with a manipulable 3D visualization. Left panel: educational content. Right panel: spinning balls, oil patterns, pin action, bowler figures — all reacting to what you read.
Live: roll-model.vercel.app
Tech: Next.js 15 (App Router) · React 19 · React Three Fiber 9 · MDX · Tailwind CSS · Vercel
# Install
npm install
# Dev server (always port 6200)
npm run dev
# Production build
npm run build
# Type check
npx tsc --noEmit
# Lint
npm run lintIf port 6200 is occupied:
lsof -ti :6200 | xargs kill
npm run devNever use pkill -f "next dev" — it kills all Next.js servers on the machine, not just this one.
roll-model/
├── content/ # MDX content files (chapter/section .mdx)
│ ├── the-release/
│ │ └── rev-rate.mdx # The production reference section
│ └── prototypes.mdx # Dev sandbox
├── docs/
│ ├── SESSION-KICKOFF.md # Original project brief
│ ├── research/ # 11,908 lines of bowling science source material
│ ├── specs/ # Technical specifications (read 00-INDEX.md first)
│ ├── plans/ # Implementation plans
│ └── reference/ # Historical reference material
├── src/
│ ├── app/ # Next.js App Router
│ │ └── learn/[...slug]/ # Dynamic MDX content renderer
│ ├── components/
│ │ ├── 3d/
│ │ │ ├── bowling-ball.tsx # Hero ball asset (clearcoat + spin)
│ │ │ ├── scene-lighting.tsx # Lightformer studio environment
│ │ │ ├── post-processing.tsx # N8AO + Bloom + AgX tone mapping
│ │ │ ├── assets/
│ │ │ │ └── pins/ # Pin deck (lathe geometry)
│ │ │ └── scenes/ # Per-section scene components
│ │ ├── content/ # MDX custom components (Callout, SceneCue)
│ │ └── layout/ # Resizable panels, sidebar, scene canvas
│ └── lib/
│ ├── content-map.ts # Chapter/section registry
│ ├── scene-context.tsx # React Context for 3D scene state
│ └── constants.ts # Bowling ball dimensions, RPM ranges
├── assets/ # GLB models, HDRI, textures (currently empty — procedural)
└── public/ # Static assets
If you're starting a new session, read these in order:
- docs/STATUS.md — Current state dashboard. What's done, what's next, what's blocking.
- docs/specs/14-PRD.md — The product requirements doc. Vision, personas, requirements, milestones, definition of done. Every session works toward something in here.
- docs/handoffs/README.md — The dedicated session handoffs folder. Pick the next handoff and follow its master prompt.
- docs/specs/00-INDEX.md — Master index of all reference specs.
Next session ready to run: Content Batch 1 — Custom Ball Owner Cluster. Open a fresh Claude Code session and paste the master prompt from Part 12 of that doc.
| Doc | What |
|---|---|
| 01-ARCHITECTURE | Tech stack, file structure, data flow, component hierarchy |
| 04-3D-RENDERING | Lighting, materials, post-processing, performance |
| 05-CONTENT-ARCHITECTURE | MDX pipeline, full chapter/section map |
| 07-INTERACTION-BLUEPRINTS | Complete interaction design for all 53 sections |
| 09-ASSET-ARCHITECTURE | Swappable asset pattern + Lane/Figure/Pins prototypes |
| GLOSSARY | Canonical bowling terminology |
When starting a new focused session, point Claude at the matching handoff:
| Session Type | Handoff Doc |
|---|---|
| Write MDX content (5-section batches) | 08-CONTENT-BATCHING-HANDOFF |
| Build the Lane asset | 10-SESSION-LANE-ASSET |
| Build the Figure asset | 11-SESSION-FIGURE-ASSET |
| Build the oil pattern data library | 12-SESSION-OIL-DATA |
| Build scene components for content | 13-SESSION-SCENE-BUILDING |
Each handoff is self-contained: read the doc, follow the instructions, ship the work.
Roll Model is an interactive 3D bowling encyclopedia — "the best bowling textbook that never existed, but interactive and in 3D." 12 chapters, 53 sections, each paired with a manipulable 3D visualization. Built as a personal learning resource for a new bowler with a custom ball, designed to become a free community resource for the 67.3 million annual bowlers in the US.
The design philosophy follows Shopify Editions and Stripe Press: content-first 3D. Every visual effect illustrates a concept instantly. Readers interact with the 3D scene via inline <SceneCue> buttons that change what they see as they read about rev rate, oil patterns, entry angles, pin action.
Only 1 of 53 content sections is written. The rest is architected and blueprinted, ready to produce.
Production auto-deploys from main to Vercel. Preview deployments on every PR. See 06-DEPLOYMENT-CICD for details.
MIT — see LICENSE.